You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by cr...@apache.org on 2004/08/10 03:59:39 UTC
svn commit: rev 36146 - in forrest/trunk/src/core/fresh-site/src/documentation/content: . samples samples/subdir xdocs xdocs/samples
Author: crossley
Date: Mon Aug 9 18:59:39 2004
New Revision: 36146
Added:
forrest/trunk/src/core/fresh-site/src/documentation/content/samples/
forrest/trunk/src/core/fresh-site/src/documentation/content/samples/subdir/
forrest/trunk/src/core/fresh-site/src/documentation/content/samples/subdir/test4.html (contents, props changed)
forrest/trunk/src/core/fresh-site/src/documentation/content/samples/test3.html (contents, props changed)
forrest/trunk/src/core/fresh-site/src/documentation/content/xdocs/samples/linking.xml (contents, props changed)
forrest/trunk/src/core/fresh-site/src/documentation/content/xdocs/samples/static.xml (contents, props changed)
Removed:
forrest/trunk/src/core/fresh-site/src/documentation/content/xdocs/samples/sample2.xml
Modified:
forrest/trunk/src/core/fresh-site/src/documentation/content/test1.html
forrest/trunk/src/core/fresh-site/src/documentation/content/test2.html
forrest/trunk/src/core/fresh-site/src/documentation/content/xdocs/site.xml
Log:
Add the "linking" demonstration and better "raw" demonstration.
Added: forrest/trunk/src/core/fresh-site/src/documentation/content/samples/subdir/test4.html
==============================================================================
--- (empty file)
+++ forrest/trunk/src/core/fresh-site/src/documentation/content/samples/subdir/test4.html Mon Aug 9 18:59:39 2004
@@ -0,0 +1,32 @@
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ 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.
+-->
+<html>
+ <head>
+ <title>Raw un-processed HTML page (test4)</title>
+ </head>
+ <body>
+ <h1>Raw un-processed HTML page (test4)</h1>
+ <p>
+ This raw HTML page is in a "raw content" sub-directory and
+ is linked to from xdocs/samples/linking.xml
+ </p>
+ <hr />
+ <p>
+ [return to <a href="../../index.html">Index</a>]<br>
+ [return to <a href="../linking.html#raw">Linking demonstration</a>]
+ </p>
+ </body>
+</html>
Added: forrest/trunk/src/core/fresh-site/src/documentation/content/samples/test3.html
==============================================================================
--- (empty file)
+++ forrest/trunk/src/core/fresh-site/src/documentation/content/samples/test3.html Mon Aug 9 18:59:39 2004
@@ -0,0 +1,33 @@
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ 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.
+-->
+<html>
+ <head>
+ <title>Raw un-processed HTML page (test3)</title>
+ </head>
+ <body>
+ <h1>Raw un-processed HTML page (test3)</h1>
+ <p>
+ This raw HTML page is in a "raw content" sub-directory and
+ is linked to from xdocs/samples/linking.xml
+ and from xdocs/samples/static.xml
+ </p>
+ <hr />
+ <p>
+ [return to <a href="../index.html">Index</a>]<br>
+ [return to <a href="linking.html">Linking demonstration</a>]
+ </p>
+ </body>
+</html>
Modified: forrest/trunk/src/core/fresh-site/src/documentation/content/test1.html
==============================================================================
--- forrest/trunk/src/core/fresh-site/src/documentation/content/test1.html (original)
+++ forrest/trunk/src/core/fresh-site/src/documentation/content/test1.html Mon Aug 9 18:59:39 2004
@@ -14,14 +14,23 @@
limitations under the License.
-->
<html>
+ <head>
+ <title>Raw un-processed HTML page (test1)</title>
+ </head>
<body>
- <h1>Test HTML page</h1>
+ <h1>raw un-processed HTML page (test1)</h1>
<p>
- This raw HTML page is linked to from xdocs/sample2.xml.
+ This raw HTML page is linked to from xdocs/samples/static.xml
+ and from xdocs/samples/linking.xml
</p>
- <p>All linked-to pages, like <a href="test2.html">this one</a>, are
+ <p>All linked-to pages (for example:
+ <a href="test2.html"><a href="test2.html"></a>) are
also available.
+ </p>
<hr />
- [<a href="index.html">Index</a>]
+ <p>
+ [return to <a href="index.html">Index</a>]<br>
+ [return to <a href="samples/linking.html">Linking demonstration</a>]
+ </p>
</body>
</html>
Modified: forrest/trunk/src/core/fresh-site/src/documentation/content/test2.html
==============================================================================
--- forrest/trunk/src/core/fresh-site/src/documentation/content/test2.html (original)
+++ forrest/trunk/src/core/fresh-site/src/documentation/content/test2.html Mon Aug 9 18:59:39 2004
@@ -14,10 +14,16 @@
limitations under the License.
-->
<html>
- <h1>Test 2</h1>
- <p>
- A linked-to-from-HTML page.
- <hr />
- [<a href="index.html">Index</a>] [<a href="test1.html">test1.html</a>]
- </p>
+ <head>
+ <title>Raw un-processed HTML page (test2)</title>
+ </head>
+ <body>
+ <h1>Raw un-processed HTML page (test2)</h1>
+ <p>
+ This raw HTML document was linked to from another raw html document.
+ <hr />
+ [return to <a href="index.html">Index</a>]
+ [return to the linkee <a href="test1.html">test1.html</a>]
+ </p>
+ </body>
</html>
Added: forrest/trunk/src/core/fresh-site/src/documentation/content/xdocs/samples/linking.xml
==============================================================================
--- (empty file)
+++ forrest/trunk/src/core/fresh-site/src/documentation/content/xdocs/samples/linking.xml Mon Aug 9 18:59:39 2004
@@ -0,0 +1,253 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN"
+"http://apache.org/forrest/dtd/document-v13.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 "<link href="ext:linking">Menus and Linking</link>"
+ 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 the generated 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>
+ <p>
+ For the raw un-processed content, the top-level of the URI space
+ corresponds to the "<code>content/</code>" directory.
+ </p>
+ <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
+
+Raw un-processed content ...
+ content/hello.pdf hello.pdf
+ content/test1.html test1.html
+ content/samples/test3.html samples/test3.html
+ content/samples/subdir/test4.html samples/subdir/test4.html
+]]></source>
+ <p>Now for some examples ...</p>
+ </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[<link href="sample.html">]]><link href="sample.html">sample.html</link><![CDATA[</link>]]></source>
+ <p>In a sub-directory, which corresponds to
+ <code>content/xdocs/samples/subdir/index.html</code> ...
+ </p>
+ <source><![CDATA[<link href="subdir/index.html">]]><link href="subdir/index.html">subdir/index.html</link><![CDATA[</link>]]></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. plain html, pre-prepared PDFs, zip archives).
+ The "<code>content/</code>" directory corresponds to the
+ top-level of the URI space.
+ </p>
+ <p>A raw document in the current directory, which corresponds to
+ <code>content/samples/test3.html</code> ...
+ </p>
+ <source><![CDATA[<link href="test3.html">]]><link href="test3.html">test3.html</link><![CDATA[</link>]]></source>
+ <p>A raw document in a sub-directory, which corresponds to
+ <code>content/samples/subdir/test4.html</code> ...
+ </p>
+ <source><![CDATA[<link href="subdir/test4.html">]]><link href="subdir/test4.html">subdir/test4.html</link><![CDATA[</link>]]></source>
+ <p>A raw document at the next level up, which corresponds to
+ <code>content/test1.html</code> ...
+ </p>
+ <source><![CDATA[<link href="../test1.html">]]><link href="../test1.html">../test1.html</link><![CDATA[</link>]]></source>
+ <p>A raw document at the next level up, which corresponds to
+ <code>content/hello.pdf</code> ...
+ </p>
+ <source><![CDATA[<link href="../hello.pdf">]]><link href="../hello.pdf">../hello.pdf</link><![CDATA[</link>]]></source>
+ </section>
+
+ <section id="url">
+ <title>Full URL to external documents</title>
+ <p>A full URL ...</p>
+ <source><![CDATA[<link href="http://forrest.apache.org/">]]><link href="http://forrest.apache.org/">http://forrest.apache.org/</link><![CDATA[</link>]]></source>
+ <p>A full URL with a fragment identifier ...</p>
+ <source><![CDATA[<link href="http://forrest.apache.org/faq.html#link_raw">]]><link href="http://forrest.apache.org/faq.html#link_raw">http://forrest.apache.org/faq.html#link_raw</link><![CDATA[</link>]]></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[<link href="site:index">]]><link href="site:index">site:index</link><![CDATA[</link>]]></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[<link href="site:samples">]]><link href="site:samples">site:samples</link><![CDATA[</link>]]></source>
+ <p>
+ and a link to a generated document, which corresponds to
+ <code>content/xdocs/samples/faq.xml</code> ...
+ </p>
+ <source>
+<![CDATA[<link href="site:faq">]]><link href="site:faq">site:faq</link><![CDATA[</link>]]>
+which can also be a complete reference
+<![CDATA[<link href="site:samples/faq">]]><link href="site:samples/faq">site:samples/faq</link><![CDATA[</link>]]>
+ </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[<link href="site:samples/sample/section">]]><link href="site:samples/sample/section">site:samples/sample/section</link><![CDATA[</link>]]></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[<link href="site:hello_print">]]><link href="site:hello_print">site:hello_print</link><![CDATA[</link>]]></source>
+
+ <p>This entry ...</p>
+ <source><![CDATA[<test3 href="samples/test3.html"/>]]></source>
+ <p>
+ enables a link to a raw document, which corresponds to
+ <code>content/samples/test3.html</code> ...
+ </p>
+ <source><![CDATA[<link href="site:test3">]]><link href="site:test3">site:test3</link><![CDATA[</link>]]></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[<link href="ext:forrest">]]><link href="ext:forrest">ext:forrest</link><![CDATA[</link>]]></source>
+ <p>
+ and a link to another external URL ...
+ </p>
+ <source>
+<![CDATA[<link href="ext:linking">]]><link href="ext:linking">ext:linking</link><![CDATA[</link>]]>
+which can also be a complete reference
+<![CDATA[<link href="ext:forrest/linking">]]><link href="ext:forrest/linking">ext:forrest/linking</link><![CDATA[</link>]]>
+ </source>
+ <p>
+ and a link to another external URL with a fragment identifier ...
+ </p>
+ <source>
+<![CDATA[<link href="ext:webapp">]]><link href="ext:webapp">ext:webapp</link><![CDATA[</link>]]>
+which can also be a complete reference
+<![CDATA[<link href="ext:forrest/webapp">]]><link href="ext:forrest/webapp">ext:forrest/webapp</link><![CDATA[</link>]]>
+ </source>
+ </section>
+ </section>
+ </body>
+</document>
Added: forrest/trunk/src/core/fresh-site/src/documentation/content/xdocs/samples/static.xml
==============================================================================
--- (empty file)
+++ forrest/trunk/src/core/fresh-site/src/documentation/content/xdocs/samples/static.xml Mon Aug 9 18:59:39 2004
@@ -0,0 +1,48 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ 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 V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd">
+<document>
+ <header>
+ <title>Static content - including raw un-processed files and documents</title>
+ </header>
+ <body>
+ <section>
+ <title>Linking to static content</title>
+ <p>
+ You can include raw HTML, PDFs, plain-text, and other files.
+ They are included in the Forrest-built site, by placing them in the
+ <code>src/documentation/content/</code> directory and
+ they will be copied over automatically. You can link to them as
+ normal, e.g.
+ <strong><link href="test3.html"></strong><link href="test3.html">test3.html</link><strong></link></strong>
+ and
+ <strong><link href="../hello.pdf"></strong><link href="../hello.pdf">hello.pdf</link><strong></link></strong>
+ </p>
+ <p>
+ You can also have sub-directories such as
+ <code>src/documentation/content/samples/subdir/</code> which
+ reflects your main
+ <code>xdocs/</code> tree. The raw files will then end up
+ beside your documents.
+ </p>
+ <p>
+ More information in the
+ <link href="site:linking">Linking demonstration</link>.
+ </p>
+ </section>
+ </body>
+</document>
Modified: forrest/trunk/src/core/fresh-site/src/documentation/content/xdocs/site.xml
==============================================================================
--- forrest/trunk/src/core/fresh-site/src/documentation/content/xdocs/site.xml (original)
+++ forrest/trunk/src/core/fresh-site/src/documentation/content/xdocs/site.xml Mon Aug 9 18:59:39 2004
@@ -43,8 +43,10 @@
<top href="#top"/>
<section href="#section"/>
</sample>
- <sample2 label="Static content" href="sample2.html"
+ <static label="Static content" href="static.html"
description="More Samples" />
+ <linking label="Linking" href="linking.html"
+ description="Linking explained and demonstrated" />
<sample-wiki label="Wiki page" href="wiki-sample.html"
description="wiki-sample" />
<sample-ihtml label="ihtml page" href="ihtml-sample.html"
@@ -62,6 +64,12 @@
</subdir>
</samples>
+ <files>
+ <hello_print href="hello.pdf" />
+ <test1 href="test1.html" />
+ <test3 href="samples/test3.html" />
+ </files>
+
<!--
<all label="All">
<whole_site_html label="Whole Site HTML" href="site.html"/>
@@ -71,6 +79,7 @@
<external-refs>
<forrest href="http://forrest.apache.org/">
+ <linking href="docs/linking.html"/>
<validation href="docs/validation.html"/>
<webapp href="docs/your-project.html#webapp"/>
<dtd-docs href="docs/dtd-docs.html"/>