--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2002-2004 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://apache.org/forrest/dtd/document-v20.dtd">
+<document>
+ <header>
+ <title>Demonstration of linking</title>
+ </header>
+
+ <body>
+ <section id="overview">
+ <title>Overview</title>
+ <p>Forrest has many powerful techniques for linking between documents
+ and for managing the site navigation. This document demonstrates those
+ techniques.
+ The document "<a href="ext:linking">Menus and Linking</a>"
+ has the full details.
+ </p>
+ </section>
+
+ <section id="uri-space">
+ <title>Building and maintaining consistent URI space</title>
+ <p>
+ When Forrest builds your site, it starts from the front page. Like
+ a robot, it traverses all of the links that it finds in the documents
+ and builds the corresponding pages. Any new links are further traversed.
+ </p>
+ <p>
+ Sometimes those links lead to documents that are generated directly
+ from xml source files, sometimes they are generated from other source
+ via an intermediate xml format. Other times the links lead to raw
+ un-processed content.
+ </p>
+ <p>
+ The site navigation configuration file "<code>site.xml</code>" provides
+ a way to manage this URI space. In the future, when documents are
+ re-arranged and renamed, the site.xml configuration will enable this
+ smoothly.
+ </p>
+ </section>
+
+ <section id="resource-space">
+ <title>Mapping the local resource space to the final URI space</title>
+ <p>
+ For both generated and raw (un-processed) files, the top-level of the
+ URI space corresponds to the "<code>content/xdocs/</code>" directory,
+ i.e. the location of the "<code>site.xml</code>" configuration file.
+ </p>
+ <note>
+ In versions prior to 0.7 raw un-processed content was stored in
+ the "<code>content/</code>" directory. In 0.7 onwards, raw
+ un-processed data is stored alongside the xdocs. In addition,
+ in 0.6 and earlier, HTML documents could be stored in the xdocs
+ directory and served without processing. If you
+ you wish to emulate the behaviour of 0.6 and earlier see the
+ next section.
+ </note>
+ <p>
+ A diagram will help.
+ </p>
+ <source><![CDATA[
+The resource space ==============> The final URI space
+------------------ -------------------
+Generated content ...
+ content/xdocs/index.xml index.html
+ content/xdocs/samples/index.xml samples/index.html
+ content/xdocs/samples/faq.xml samples/faq.html
+ content/xdocs/test1.html test1.html
+ content/xdocs/samples/test3.html samples/test3.html
+ content/xdocs/samples/subdir/test4.html samples/subdir/test4.html
+
+Raw un-processed content ...
+ content/xdocs/hello.pdf hello.pdf
+ content/xdocs/hello.sxw hello.sxw
+ content/xdocs/subdir/hello.sxw subdir/hello.sxw
+]]></source>
+
+ <section>
+ <title>How Plugins May Affect The URI Space</title>
+ <p>By using <a href="site:plugins">Forrest Input Plugins</a>
+ you can process some file formats, such as
+ OpenOffice.org documents and produce processed content from them. For example,
+ the file <code>content/xdocs/hello.sxw</code> can be used to produce a
+ skinned version of the document at with the name <code>hello.html</code>.
+ Similarly, you can use <a href="site:plugins">Forrest Output
+ Plugins</a> to create different output formats such as PDF, in this
+ case <code>content/xdocs/hello.sxw</code> can produce
+ <code>hello.pdf</code>.</p>
+
+ <p>However, this does not affect the handling of raw content. That is, you
+ can still retrieve the raw un-processed version with, for example,
+ <code>hello.sxw</code>. If you want to prevent the user retrieving the
+ un-processed version you will have to create matchers that intercept
+ these requests within your project sitemap.</p>
+ </section>
+
+ </section>
+
+ <section id="generated">
+ <title>Basic link to internal generated pages</title>
+ <p>
+ When this type of link is encountered, Forrest will look for a
+ corresponding xml file, relative to this document (i.e. in
+ <code>content/xdocs/samples/</code>).
+ </p>
+ <p>A generated document in the current directory, which corresponds to
+ <code>content/xdocs/samples/sample.html</code> ...
+ </p>
+ <source><![CDATA[<a href="sample.html">]]><a href="sample.html">sample.html</a><![CDATA[</a>]]></source>
+ <p>In a sub-directory, which corresponds to
+ <code>content/xdocs/samples/subdir/index.html</code> ...
+ </p>
+ <source><![CDATA[<a href="subdir/index.html">]]><a href="subdir/index.html">subdir/index.html</a><![CDATA[</a>]]></source>
+ </section>
+
+ <section id="raw">
+ <title>Basic link to raw un-processed content</title>
+ <p>
+ Raw content files are not intended for any processing, they are just
+ linked to (e.g. pre-prepared PDFs, zip archives).
+ These files are placed alongside your normal content in the
+ "<code>content/xdocs</code>" directory.
+ </p>
+ <p>A raw document in the current directory, which corresponds to
+ <code>content/xdocs/samples/helloAgain.pdf</code> ...
+ </p>
+ <source><![CDATA[<a href="helloAgain.pdf">]]><a href="helloAgain.pdf">helloAgain.pdf</a><![CDATA[</a>]]></source>
+ <p>A raw document in a sub-directory, which corresponds to
+ <code>content/xdocs/samples/subdir/hello.zip</code> ...
+ </p>
+ <source><![CDATA[<a href="subdir/hello.zip">]]><a href="subdir/hello.zip">subdir/hello.zip</a><![CDATA[</a>]]></source>
+ <p>A raw document at the next level up, which corresponds to
+ <code>content/hello.pdf</code> ...
+ </p>
+ <source><![CDATA[<a href="../hello.pdf">]]><a href="../hello.pdf">../hello.pdf</a><![CDATA[</a>]]></source>
+
+ <section>
+ <title>Serving (X)HTML content without Skinning</title>
+
+ <p>Prior to version 0.7, the raw un-processed content was stored in
+ the "<code>content/</code>" directory. In 0.7 onwards, raw
+ un-processed data is stored alongside the xdocs. In addition
+ in 0.6 and earlier, HTML files could be stored in the xdocs
+ directory and they would be served without further processing.
+ As described above, this is not the case in 0.7 where HTML files
+ are, by default, skinned by Forrest.</p>
+
+ <p>If you
+ you wish to emulate the behaviour of 0.6 and earlier then you
+ must add the following to your project sitemap.</p>
+
+ <source>
+<map:match pattern="**.html">
+ <map:select type="exists">
+ <map:when test="{project:content}{0}">
+ <map:read src="{project:content}/{0}" mime-type="text/html"/>
+ <!--
+ Use this instead if you want JTidy to clean up your HTML
+ <map:generate type="html" src="{project:content}/{0}" />
+ <map:serialize type="html"/>
+ -->
+ </map:when>
+ <map:when test="{project:content.xdocs}{0}">
+ <map:read src="{project:content.xdocs}/{0}" mime-type="text/html"/>
+ <!--
+ Use this instead if you want JTidy to clean up your HTML
+ <map:generate type="html" src="{project:content.xdocs}/{0}" />
+ <map:serialize type="html"/>
+ -->
+ </map:when>
+ </map:select>
+</map:match>
+ </source>
+
+ <p>The above allows us to create links to un-processed skinned files stored
+ in the <code>{project:content}</code> or <code>{project:content.xdocs}</code>
+ directory. For example:
+ <a href="/test1.html">HTML content</a>. However, it will
+ break the 0.7 behaviour of skinning HTML content. For this reason the old
+ ".ehtml" extension can be used to embed HTML content in a Forrest skinned
+ site </p>
+
+ <p>Note that you can change the matchers above to selectively serve some
+ content as raw un-processed content, whilst still serving other content
+ as skinned documents. For example, the following snippet would allow
+ you to serve the content of an old, deprecated site without processing
+ from Forrest, whilst still allowing all other content to be processed
+ by Forrest in the normal way:</p>
+
+ <source>
+<map:match pattern="old_site/**.html">
+ <map:select type="exists">
+ <map:when test="{project:content}{1}.html">
+ <map:read src="{project:content}/{1}.html" mime-type="text/html"/>
+ <!--
+ Use this instead if you want JTidy to clean up your HTML
+ <map:generate type="html" src="{project:content}/{0}" />
+ <map:serialize type="html"/>
+ -->
+ </map:when>
+</map:match>
+ </source>
+
+ <p>For example, <a href="/old_site/test1.html">HTML content</a>.</p>
+ </section>
+ </section>
+
+ <section id="url">
+ <title>Full URL to external documents</title>
+ <p>A full URL ...</p>
+ <source><![CDATA[<a href="http://forrest.apache.org/">]]><a href="http://forrest.apache.org/">http://forrest.apache.org/</a><![CDATA[</a>]]></source>
+ <p>A full URL with a fragment identifier ...</p>
+ <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>
+ <p>
+ Note that Forrest does not traverse external links to look for
+ other links.
+ </p>
+ </section>
+
+ <section id="site">
+ <title>Using site.xml to manage the links</title>
+ <p>As you will have discovered, using pathnames with ../../ etc. will
+ get very nasty. Real problems occur when you use a smart text editor
+ that tries to manage the links for you. For example, it will have
+ trouble linking to the raw content files which are not yet in their
+ final location.
+ </p>
+ <p>
+ Links and filenames are bound to change and re-arrange. It is
+ essential to only change those links in one central place, not in every
+ document.
+ </p>
+ <p>
+ The "<code>site.xml</code>" configuration file to the rescue. It maps
+ symbolic names to actual resources.
+ </p>
+
+ <section id="site-simple">
+ <title>Basic link to internal generated pages</title>
+ <p>This single entry ...</p>
+ <source><![CDATA[<index label="Index" href="index.html"/>]]></source>
+ <p>
+ enables a simple link to a generated document, which corresponds to
+ <code>content/xdocs/index.xml</code> ...
+ </p>
+ <source><![CDATA[<a href="site:index">]]><a href="site:index">site:index</a><![CDATA[</a>]]></source>
+ </section>
+
+ <section id="site-compound">
+ <title>Group some items</title>
+ <p>This compound entry ...</p>
+ <source><![CDATA[
+ <samples label="Samples" href="samples/" tab="samples">
+ <faq label="FAQ" href="faq.html"/>
+ ...
+ </samples>
+]]></source>
+ <p>
+ enables a link to a generated document, which corresponds to
+ <code>content/xdocs/samples/index.xml</code> ...
+ </p>
+ <source><![CDATA[<a href="site:samples">]]><a href="site:samples">site:samples</a><![CDATA[</a>]]></source>
+ <p>
+ and a link to a generated document, which corresponds to
+ <code>content/xdocs/samples/faq.xml</code> ...
+ </p>
+ <source>
+<![CDATA[<a href="site:faq">]]><a href="site:faq">site:faq</a><![CDATA[</a>]]>
+which can also be a complete reference
+<![CDATA[<a href="site:samples/faq">]]><a href="site:samples/faq">site:samples/faq</a><![CDATA[</a>]]>
+ </source>
+ </section>
+
+ <section id="site-fragment">
+ <title>Fragment identifiers</title>
+ <p>This compound entry ...</p>
+ <source><![CDATA[
+ <samples label="Samples" href="samples/" tab="samples">
+ <sample label="Apache document" href="sample.html">
+ <top href="#top"/>
+ <section href="#section"/>
+ </sample>
+ ...
+ </samples>
+]]></source>
+ <p>
+ enables a link to a fragment identifier within the
+ <code>samples/sample.html</code> document ...
+ </p>
+ <source><![CDATA[<a href="site:samples/sample/section">]]><a href="site:samples/sample/section">site:samples/sample/section</a><![CDATA[</a>]]></source>
+ </section>
+
+ <section id="site-raw">
+ <title>Define items for raw content</title>
+ <p>This entry ...</p>
+ <source><![CDATA[<hello_print href="hello.pdf"/>]]></source>
+ <p>
+ enables a link to a raw document, which corresponds to
+ <code>content/hello.pdf</code> ...
+ </p>
+ <source><![CDATA[<a href="site:hello_print">]]><a href="site:hello_print">site:hello_print</a><![CDATA[</a>]]></source>
+
+ </section>
+
+ <section id="site-ext">
+ <title>External links</title>
+ <p>This compound entry ...</p>
+ <source><![CDATA[
+ <external-refs>
+ <forrest href="http://forrest.apache.org/">
+ <linking href="docs/linking.html"/>
+ <webapp href="docs/your-project.html#webapp"/>
+ </forrest>
+ </external-refs>
+]]></source>
+ <p>
+ enables a link to an external URL ...
+ </p>
+ <source><![CDATA[<a href="ext:forrest">]]><a href="ext:forrest">ext:forrest</a><![CDATA[</a>]]></source>
+ <p>
+ and a link to another external URL ...
+ </p>
+ <source>
+<![CDATA[<a href="ext:linking">]]><a href="ext:linking">ext:linking</a><![CDATA[</a>]]>
+which can also be a complete reference
+<![CDATA[<a href="ext:forrest/linking">]]><a href="ext:forrest/linking">ext:forrest/linking</a><![CDATA[</a>]]>
+ </source>
+ <p>
+ and a link to another external URL with a fragment identifier ...
+ </p>
+ <source>
+<![CDATA[<a href="ext:webapp">]]><a href="ext:webapp">ext:webapp</a><![CDATA[</a>]]>
+which can also be a complete reference
+<![CDATA[<a href="ext:forrest/webapp">]]><a href="ext:forrest/webapp">ext:forrest/webapp</a><![CDATA[</a>]]>
+ </source>
+ </section>
+ </section>
+ </body>
+</document>
git://wamblee.org / utils / blobdiff