forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: rev 36146 - in forrest/trunk/src/core/fresh-site/src/documentation/content: . samples samples/subdir xdocs xdocs/samples
Date Tue, 10 Aug 2004 01:59:39 GMT
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">&lt;a href="test2.html"&gt;</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>&lt;link href="test3.html"&gt;</strong><link href="test3.html">test3.html</link><strong>&lt;/link&gt;</strong>
+        and
+        <strong>&lt;link href="../hello.pdf"&gt;</strong><link href="../hello.pdf">hello.pdf</link><strong>&lt;/link&gt;</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"/>

Mime
View raw message