wamblee.org Git - utils/blob

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3   Copyright 2002-2004 The Apache Software Foundation or its licensors,
   4   as applicable.
   5
   6   Licensed under the Apache License, Version 2.0 (the "License");
   7   you may not use this file except in compliance with the License.
   8   You may obtain a copy of the License at
   9
  10       http://www.apache.org/licenses/LICENSE-2.0
  11
  12   Unless required by applicable law or agreed to in writing, software
  13   distributed under the License is distributed on an "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15   See the License for the specific language governing permissions and
  16   limitations under the License.
  17 -->
  18 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://apache.org/forrest/dtd/document-v20.dtd">
  19 <document>
  20   <header>
  21     <title>Demonstration of linking</title>
  22   </header>
  23
  24   <body>
  25     <section id="overview">
  26       <title>Overview</title>
  27       <p>Forrest has many powerful techniques for linking between documents
  28       and for managing the site navigation. This document demonstrates those
  29       techniques.
  30       The document "<a href="ext:linking">Menus and Linking</a>"
  31       has the full details.
  32       </p>
  33     </section>
  34
  35     <section id="uri-space">
  36       <title>Building and maintaining consistent URI space</title>
  37       <p>
  38       When Forrest builds your site, it starts from the front page. Like
  39       a robot, it traverses all of the links that it finds in the documents
  40       and builds the corresponding pages. Any new links are further traversed.
  41       </p>
  42       <p>
  43       Sometimes those links lead to documents that are generated directly
  44       from xml source files, sometimes they are generated from other source
  45       via an intermediate xml format. Other times the links lead to raw
  46       un-processed content.
  47       </p>
  48       <p>
  49        The site navigation configuration file "<code>site.xml</code>" provides
  50        a way to manage this URI space. In the future, when documents are
  51        re-arranged and renamed, the site.xml configuration will enable this
  52        smoothly.
  53       </p>
  54     </section>
  55
  56     <section id="resource-space">
  57       <title>Mapping the local resource space to the final URI space</title>
  58       <p>
  59        For both generated and raw (un-processed) files, the top-level of the
  60        URI space corresponds to the "<code>content/xdocs/</code>" directory,
  61        i.e. the location of the "<code>site.xml</code>" configuration file.
  62       </p>
  63       <note>
  64         In versions prior to 0.7 raw un-processed content was stored in
  65         the "<code>content/</code>" directory. In 0.7 onwards, raw
  66         un-processed data is stored alongside the xdocs. In addition,
  67         in 0.6 and earlier, HTML documents could be stored in the xdocs
  68         directory and served without processing. If you
  69         you wish to emulate the behaviour of 0.6 and earlier see the
  70         next section.
  71       </note>
  72       <p>
  73         A diagram will help.
  74       </p>
  75       <source><![CDATA[
  76 The resource space          ==============>    The final URI space
  77 ------------------                             -------------------
  78 Generated content ...
  79  content/xdocs/index.xml                       index.html
  80  content/xdocs/samples/index.xml               samples/index.html
  81  content/xdocs/samples/faq.xml                 samples/faq.html
  82  content/xdocs/test1.html                      test1.html
  83  content/xdocs/samples/test3.html              samples/test3.html
  84  content/xdocs/samples/subdir/test4.html       samples/subdir/test4.html
  85
  86 Raw un-processed content ...
  87  content/xdocs/hello.pdf                       hello.pdf
  88  content/xdocs/hello.sxw                       hello.sxw
  89  content/xdocs/subdir/hello.sxw                subdir/hello.sxw
  90 ]]></source>
  91
  92   <section>
  93     <title>How Plugins May Affect The URI Space</title>
  94       <p>By using <a href="site:plugins">Forrest Input Plugins</a>
  95       you can process some file formats, such as
  96       OpenOffice.org documents and produce processed content from them. For example,
  97       the file <code>content/xdocs/hello.sxw</code> can be used to produce a
  98       skinned version of the document at with the name <code>hello.html</code>.
  99       Similarly, you can use <a href="site:plugins">Forrest Output
 100       Plugins</a> to create different output formats such as PDF, in this
 101       case <code>content/xdocs/hello.sxw</code> can produce
 102       <code>hello.pdf</code>.</p>
 103
 104       <p>However, this does not affect the handling of raw content. That is, you
 105       can still retrieve the raw un-processed version with, for example,
 106       <code>hello.sxw</code>. If you want to prevent the user retrieving the
 107       un-processed version you will have to create matchers that intercept
 108       these requests within your project sitemap.</p>
 109       </section>
 110
 111     </section>
 112
 113     <section id="generated">
 114       <title>Basic link to internal generated pages</title>
 115       <p>
 116       When this type of link is encountered, Forrest will look for a
 117       corresponding xml file, relative to this document (i.e. in
 118       <code>content/xdocs/samples/</code>).
 119       </p>
 120       <p>A generated document in the current directory, which corresponds to
 121       <code>content/xdocs/samples/sample.html</code> ...
 122       </p>
 123       <source><![CDATA[<a href="sample.html">]]><a href="sample.html">sample.html</a><![CDATA[</a>]]></source>
 124       <p>In a sub-directory, which corresponds to
 125       <code>content/xdocs/samples/subdir/index.html</code> ...
 126       </p>
 127       <source><![CDATA[<a href="subdir/index.html">]]><a href="subdir/index.html">subdir/index.html</a><![CDATA[</a>]]></source>
 128     </section>
 129
 130     <section id="raw">
 131       <title>Basic link to raw un-processed content</title>
 132       <p>
 133       Raw content files are not intended for any processing, they are just
 134       linked to (e.g. pre-prepared PDFs, zip archives).
 135       These files are placed alongside your normal content in the
 136       "<code>content/xdocs</code>" directory.
 137       </p>
 138       <p>A raw document in the current directory, which corresponds to
 139       <code>content/xdocs/samples/helloAgain.pdf</code> ...
 140       </p>
 141       <source><![CDATA[<a href="helloAgain.pdf">]]><a href="helloAgain.pdf">helloAgain.pdf</a><![CDATA[</a>]]></source>
 142       <p>A raw document in a sub-directory, which corresponds to
 143       <code>content/xdocs/samples/subdir/hello.zip</code> ...
 144       </p>
 145       <source><![CDATA[<a href="subdir/hello.zip">]]><a href="subdir/hello.zip">subdir/hello.zip</a><![CDATA[</a>]]></source>
 146       <p>A raw document at the next level up, which corresponds to
 147       <code>content/hello.pdf</code> ...
 148       </p>
 149       <source><![CDATA[<a href="../hello.pdf">]]><a href="../hello.pdf">../hello.pdf</a><![CDATA[</a>]]></source>
 150
 151       <section>
 152         <title>Serving (X)HTML content without Skinning</title>
 153
 154         <p>Prior to version 0.7, the raw un-processed content was stored in
 155         the "<code>content/</code>" directory. In 0.7 onwards, raw
 156         un-processed data is stored alongside the xdocs. In addition
 157         in 0.6 and earlier, HTML files could be stored in the xdocs
 158         directory and they would be served without further processing.
 159         As described above, this is not the case in 0.7 where HTML files
 160         are, by default, skinned by Forrest.</p>
 161
 162         <p>If you
 163         you wish to emulate the behaviour of 0.6 and earlier then you
 164         must add the following to your project sitemap.</p>
 165
 166         <source>
 167 &lt;map:match pattern="**.html"&gt;
 168  &lt;map:select type="exists"&gt;
 169   &lt;map:when test="{project:content}{0}"&gt;
 170     &lt;map:read src="{project:content}/{0}" mime-type="text/html"/&gt;
 171     &lt;!--
 172       Use this instead if you want JTidy to clean up your HTML
 173       &lt;map:generate type="html" src="{project:content}/{0}" /&gt;
 174       &lt;map:serialize type="html"/&gt;
 175     --&gt;
 176   &lt;/map:when&gt;
 177   &lt;map:when test="{project:content.xdocs}{0}"&gt;
 178     &lt;map:read src="{project:content.xdocs}/{0}" mime-type="text/html"/&gt;
 179     &lt;!--
 180       Use this instead if you want JTidy to clean up your HTML
 181       &lt;map:generate type="html" src="{project:content.xdocs}/{0}" /&gt;
 182       &lt;map:serialize type="html"/&gt;
 183     --&gt;
 184   &lt;/map:when&gt;
 185  &lt;/map:select&gt;
 186 &lt;/map:match&gt;
 187         </source>
 188
 189         <p>The above allows us to create links to un-processed skinned files stored
 190         in the <code>{project:content}</code> or <code>{project:content.xdocs}</code>
 191         directory. For example:
 192         &lt;a href="/test1.html"&gt;HTML content&lt;/a&gt;. However, it will
 193         break the 0.7 behaviour of skinning HTML content. For this reason the old
 194         ".ehtml" extension can be used to embed HTML content in a Forrest skinned
 195         site </p>
 196
 197         <p>Note that you can change the matchers above to selectively serve some
 198         content as raw un-processed content, whilst still serving other content
 199         as skinned documents. For example, the following snippet would allow
 200         you to serve the content of an old, deprecated site without processing
 201         from Forrest, whilst still allowing all other content to be processed
 202         by Forrest in the normal way:</p>
 203
 204         <source>
 205 &lt;map:match pattern="old_site/**.html"&gt;
 206  &lt;map:select type="exists"&gt;
 207   &lt;map:when test="{project:content}{1}.html"&gt;
 208     &lt;map:read src="{project:content}/{1}.html" mime-type="text/html"/&gt;
 209     &lt;!--
 210       Use this instead if you want JTidy to clean up your HTML
 211       &lt;map:generate type="html" src="{project:content}/{0}" /&gt;
 212       &lt;map:serialize type="html"/&gt;
 213     --&gt;
 214   &lt;/map:when&gt;
 215 &lt;/map:match&gt;
 216         </source>
 217
 218         <p>For example, <a href="/old_site/test1.html">HTML content</a>.</p>
 219       </section>
 220     </section>
 221
 222     <section id="url">
 223       <title>Full URL to external documents</title>
 224       <p>A full URL ...</p>
 225       <source><![CDATA[<a href="http://forrest.apache.org/">]]><a href="http://forrest.apache.org/">http://forrest.apache.org/</a><![CDATA[</a>]]></source>
 226       <p>A full URL with a fragment identifier ...</p>
 227       <source><![CDATA[<a href="http://forrest.apache.org/faq.html#link_raw">]]><a href="http://forrest.apache.org/faq.html#link_raw">http://forrest.apache.org/faq.html#link_raw</a><![CDATA[</a>]]></source>
 228       <p>
 229       Note that Forrest does not traverse external links to look for
 230       other links.
 231       </p>
 232     </section>
 233
 234     <section id="site">
 235       <title>Using site.xml to manage the links</title>
 236       <p>As you will have discovered, using pathnames with ../../ etc. will
 237       get very nasty. Real problems occur when you use a smart text editor
 238       that tries to manage the links for you. For example, it will have
 239       trouble linking to the raw content files which are not yet in their
 240       final location.
 241       </p>
 242       <p>
 243       Links and filenames are bound to change and re-arrange. It is
 244       essential to only change those links in one central place, not in every
 245       document.
 246       </p>
 247       <p>
 248       The "<code>site.xml</code>" configuration file to the rescue. It maps
 249       symbolic names to actual resources.
 250       </p>
 251
 252       <section id="site-simple">
 253         <title>Basic link to internal generated pages</title>
 254         <p>This single entry ...</p>
 255         <source><![CDATA[<index label="Index" href="index.html"/>]]></source>
 256         <p>
 257         enables a simple link to a generated document, which corresponds to
 258         <code>content/xdocs/index.xml</code> ...
 259         </p>
 260         <source><![CDATA[<a href="site:index">]]><a href="site:index">site:index</a><![CDATA[</a>]]></source>
 261       </section>
 262
 263       <section id="site-compound">
 264         <title>Group some items</title>
 265         <p>This compound entry ...</p>
 266         <source><![CDATA[
 267   <samples label="Samples" href="samples/" tab="samples">
 268     <faq label="FAQ" href="faq.html"/>
 269     ...
 270   </samples>
 271 ]]></source>
 272         <p>
 273         enables a link to a generated document, which corresponds to
 274         <code>content/xdocs/samples/index.xml</code> ...
 275         </p>
 276         <source><![CDATA[<a href="site:samples">]]><a href="site:samples">site:samples</a><![CDATA[</a>]]></source>
 277         <p>
 278         and a link to a generated document, which corresponds to
 279         <code>content/xdocs/samples/faq.xml</code> ...
 280         </p>
 281         <source>
 282 <![CDATA[<a href="site:faq">]]><a href="site:faq">site:faq</a><![CDATA[</a>]]>
 283 which can also be a complete reference
 284 <![CDATA[<a href="site:samples/faq">]]><a href="site:samples/faq">site:samples/faq</a><![CDATA[</a>]]>
 285         </source>
 286       </section>
 287
 288       <section id="site-fragment">
 289         <title>Fragment identifiers</title>
 290         <p>This compound entry ...</p>
 291         <source><![CDATA[
 292   <samples label="Samples" href="samples/" tab="samples">
 293     <sample label="Apache document" href="sample.html">
 294       <top href="#top"/>
 295       <section href="#section"/>
 296     </sample>
 297     ...
 298   </samples>
 299 ]]></source>
 300         <p>
 301         enables a link to a fragment identifier within the
 302         <code>samples/sample.html</code> document ...
 303         </p>
 304         <source><![CDATA[<a href="site:samples/sample/section">]]><a href="site:samples/sample/section">site:samples/sample/section</a><![CDATA[</a>]]></source>
 305       </section>
 306
 307       <section id="site-raw">
 308         <title>Define items for raw content</title>
 309         <p>This entry ...</p>
 310         <source><![CDATA[<hello_print href="hello.pdf"/>]]></source>
 311         <p>
 312         enables a link to a raw document, which corresponds to
 313         <code>content/hello.pdf</code> ...
 314         </p>
 315         <source><![CDATA[<a href="site:hello_print">]]><a href="site:hello_print">site:hello_print</a><![CDATA[</a>]]></source>
 316
 317       </section>
 318
 319       <section id="site-ext">
 320         <title>External links</title>
 321         <p>This compound entry ...</p>
 322         <source><![CDATA[
 323   <external-refs>
 324     <forrest href="http://forrest.apache.org/">
 325       <linking href="docs/linking.html"/>
 326       <webapp href="docs/your-project.html#webapp"/>
 327     </forrest>
 328   </external-refs>
 329 ]]></source>
 330         <p>
 331         enables a link to an external URL ...
 332         </p>
 333         <source><![CDATA[<a href="ext:forrest">]]><a href="ext:forrest">ext:forrest</a><![CDATA[</a>]]></source>
 334         <p>
 335         and a link to another external URL ...
 336         </p>
 337         <source>
 338 <![CDATA[<a href="ext:linking">]]><a href="ext:linking">ext:linking</a><![CDATA[</a>]]>
 339 which can also be a complete reference
 340 <![CDATA[<a href="ext:forrest/linking">]]><a href="ext:forrest/linking">ext:forrest/linking</a><![CDATA[</a>]]>
 341         </source>
 342         <p>
 343         and a link to another external URL with a fragment identifier ...
 344         </p>
 345         <source>
 346 <![CDATA[<a href="ext:webapp">]]><a href="ext:webapp">ext:webapp</a><![CDATA[</a>]]>
 347 which can also be a complete reference
 348 <![CDATA[<a href="ext:forrest/webapp">]]><a href="ext:forrest/webapp">ext:forrest/webapp</a><![CDATA[</a>]]>
 349         </source>
 350       </section>
 351     </section>
 352   </body>
 353 </document>