forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gmcdon...@apache.org
Subject svn commit: r556367 [1/2] - in /forrest/trunk/main/fresh-site/src/documentation/content/xdocs: samples/ samples1/ samples1/locationmap/ samples2/ samples2/showonlywhenselected/ samples2/subdir/
Date Sun, 15 Jul 2007 06:39:31 GMT
Author: gmcdonald
Date: Sat Jul 14 23:39:28 2007
New Revision: 556367

URL: http://svn.apache.org/viewvc?view=rev&rev=556367
Log:
Part Two - Re-organised samples into two sections, highlights the use of sub-tabs etc. General improvement and also Fix for FOR-1001

Added:
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples/
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples/index.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/ascii-art.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/cocoon-pyramid.aart   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/custom.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/customSchema.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/ellipse.svg   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/embedded_html.html   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/faq.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/hello-v10.dtd   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/helloAgain.pdf   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/howto-howto.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/icon-d.png   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/index.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/linking.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/locationmap/
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/locationmap/index.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/sample.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/static.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/svg.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/usemap.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/xml-entities.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/demo-i18n.de.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/demo-i18n.fr.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/demo-i18n.nl.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/demo-i18n.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/i18n.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/index.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/showonlywhenselected/
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/showonlywhenselected/page1.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/showonlywhenselected/page2.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/subdir/
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/subdir/book-sample.xml   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/subdir/hello.zip   (with props)
    forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples2/subdir/index.xml   (with props)

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples/index.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples/index.xml?view=auto&rev=556367
==============================================================================
--- forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples/index.xml (added)
+++ forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples/index.xml Sat Jul 14 23:39:28 2007
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+  <header>
+    <title>Samples</title>
+  </header>
+  <body>
+    <section id="samples1">
+      <title>Samples are found in two areas</title>
+        <ul>
+                <li><a href="site:docs-samples1/index">Samples-1</a> Contains many examples including DTD usage; Linking Demo; SVG; XML Entities; Locationmap and more ...</li>
+                <li><a href="site:docs-samples2/index">Samples-2</a> Contains a few examples, mainly i18n Internationalisation; Sub-Directory usage and conditional display of menu items.</li>
+          </ul>
+    </section>
+
+    <section id="please-contribute">
+      <title>If something goes wrong..</title>
+      <p>
+        Patches are welcome:
+        <a href="http://forrest.apache.org/docs/faq.html">Forrest FAQ</a>
+      </p>
+    </section>
+  </body>
+</document>

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples/index.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/ascii-art.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/ascii-art.xml?view=auto&rev=556367
==============================================================================
--- forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/ascii-art.xml (added)
+++ forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/ascii-art.xml Sat Jul 14 23:39:28 2007
@@ -0,0 +1,65 @@
+<?xml version="1.0"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+  <header>
+    <title>Ascii Art sample</title>
+  </header>
+  <body>
+    <section>
+      <title>Sample Ascii Art</title>
+      <p>
+        To create a <code>.png</code> image like the one below with ASCII art,
+        just save the text file with the <code>.aart</code> extension and then
+        link from any page as an image (<code>&lt;image
+        src="asci-art-file.png"/&gt;</code>).
+      </p>
+      <p>
+        <img src="cocoon-pyramid.png" alt="cocoon pyramid of management-(logic-content-style)"/>
+      </p>
+      <p>
+        Here is the source file that has created the above image.
+      </p>
+      <source>
+ 
+         +-------------------+
+         |    Management     |
+         +-+-------+-------+-+
+           |       |       |                          
+           |       |       |
+   +-------+  +----+----+  +-------+  
+   | logic +--+ content +--+ style |  
+   +-------+  +---------+  +-------+  
+ 
+      </source>
+      <p>
+        An ascii art pad recognized following ascii characters:
+      </p>
+      <ul>
+        <li> '-' horizontal SVG line</li>
+        <li>'|' vertical SVG line</li>
+        <li> '+' corner</li>
+        <li> \ oblique line</li>
+        <li> String starting with letter, digit, or '_' is converted to a SVG text.</li>
+      </ul>
+    </section>
+  </body>
+  <footer>
+    <legal>Copyright 2002-2005 The Apache Software Foundation or its licensors, as applicable.</legal>
+  </footer>
+</document>

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/ascii-art.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/cocoon-pyramid.aart
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/cocoon-pyramid.aart?view=auto&rev=556367
==============================================================================
--- forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/cocoon-pyramid.aart (added)
+++ forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/cocoon-pyramid.aart Sat Jul 14 23:39:28 2007
@@ -0,0 +1,11 @@
+
+       +-------------------+
+       |    Management     |
+       +-+-------+-------+-+
+         |       |       |                          
+         |       |       |
+ +-------+  +----+----+  +-------+  
+ | logic +--+ content +--+ style |  
+ +-------+  +---------+  +-------+  
+
+ 

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/cocoon-pyramid.aart
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/custom.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/custom.xml?view=auto&rev=556367
==============================================================================
--- forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/custom.xml (added)
+++ forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/custom.xml Sat Jul 14 23:39:28 2007
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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 greeting PUBLIC "-//Acme//DTD Hello Document V1.0//EN" "hello-v10.dtd">
+<greeting>
+Hello XML Custom World!!
+</greeting>

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/custom.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/customSchema.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/customSchema.xml?view=auto&rev=556367
==============================================================================
--- forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/customSchema.xml (added)
+++ forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/customSchema.xml Sat Jul 14 23:39:28 2007
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+  <header>
+    <title>Custom Schema</title>
+  </header>
+  <body>
+    <p>
+      Forrest comes with a set of schemas for common documents, however, if you
+      have existing documents that use a different schema you will want to tell
+      Forrest how to work with them. The best way of doing this is to
+      <a href="ext:forrest/buildPlugin">build a plugin</a> so that you can
+      easily reuse the functionality on different projects. Plugins also allow
+      you to share this new functionality with other users, and to benefit from
+      their contributions to your work.
+    </p>
+    <p>
+      If you don't want to build a plugin you can make Forrest process them
+      within your project sitemap (but this won't really save you any work since
+      the process is almost the same). This sample site has a demonstration of
+      using a custom DTD. If you request <a href="site:custom-example">&lt;a
+      href="custom.html"&gt;</a> you can see the results.
+    </p>
+    <p>
+      Look at the project <code>sitemap.xmap</code> to see how it is done. View
+      the xml source at "src/documentation/content/samples/custom.xml" and refer
+      to the DTD and its configuration at "src/documentation/resources/schema/".
+      See the project sitemap at "src/documentation/sitemap.xmap" for how the
+      custom doctype is processed and the stylesheet is applied.
+    </p>
+    <p>
+      See the <a href="ext:forrest/new_content_type">full story</a> about
+      handling custom document types.
+    </p>
+    <note>
+      Adding custom schemas with a plugin has the added benefit of being able to
+      add the schema definition to the catalog file rather than having to
+      reference it directly from within the XML document.
+    </note>
+  </body>
+</document>

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/customSchema.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/ellipse.svg
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/ellipse.svg?view=auto&rev=556367
==============================================================================
--- forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/ellipse.svg (added)
+++ forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/ellipse.svg Sat Jul 14 23:39:28 2007
@@ -0,0 +1,30 @@
+<?xml version="1.0" standalone="no"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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 svg PUBLIC "-//W3C//DTD SVG 1.0//EN"
+"http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" version="1.0"
+   width="300" height="150"
+   viewBox="0 0 1500 1000"
+>
+  <desc>Ellipse</desc>
+  <rect x="1" y="1" width="1495" height="995"
+      fill="none" stroke="blue" stroke-width="5"/>
+  <ellipse transform="translate(200 200) rotate(-45)" 
+      rx="200" ry="100"
+      fill="none" stroke="red" stroke-width="20"/>
+</svg>

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/ellipse.svg
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/embedded_html.html
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/embedded_html.html?view=auto&rev=556367
==============================================================================
--- forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/embedded_html.html (added)
+++ forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/embedded_html.html Sat Jul 14 23:39:28 2007
@@ -0,0 +1,114 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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>Embedded HTML demonstration page</title>
+</head>
+<body>
+
+<h1><a name="intro" />Embedded HTML demonstration page</h1>
+		
+<p>An HTML document is used as the source for this page, and translated
+to the intermediate Apache Forrest xdocs document structure. The sitemap then
+does the normal aggregation with the navigation content and application of
+the skin.
+</p>
+
+<p>
+The html is being interpreted by Forrest and transformed to the
+intermediate Apache xdocs document structure. That stylesheet cannot deal
+with every possibility in unstructured html, so it tries to guess how to
+build &lt;section&gt; elements and such.
+It needs &lt;h1&gt; (&lt;h2&gt; etc.) headings in the source html
+in order to identify sections. Patches are welcome to enhance
+that transformer.
+</p>
+
+<p>
+You can still take advantage of Forrest's
+<a href="http://forrest.apache.org/docs/linking.html">"<b>site:<b>"
+method of linking</a>, for example:
+<a href="site:index">&lt;a href="site:index"&gt;</a>
+</p>
+
+<hr>
+<p class="note">XHTML can also be used, but it is just treated as interpreted
+html. Future versions of Forrest will take much more advantage of XHTML.
+</p>
+<hr>
+
+<h1><a name="examples" />Some example uses of HTML</h1>
+<p>
+There are situations when the Apache Forrest xdocs DTD is not sufficient.
+The use of embedded HTML enables you to use HTML code in these situations.
+</p>
+
+<h2><a name="js" />Embedded applets and Javascript</h2>
+      
+<p>
+See the
+<a href="javascript:alert('Opened with Javascript via the body of the source html.')">Javascript alert pop-up</a>
+</p>
+
+<h2><a name="forms" />HTML forms for user interaction</h2>
+<p>
+Search the Forrest website via Google:
+<!-- Search Google -->
+<form target="_blank" action="http://www.google.com/search" method="get" id="google-demo">
+<input value="forrest.apache.org" name="as_sitesearch" type="hidden">
+<input type="hidden" name="ie" value="UTF-8">
+<input type="hidden" name="oe" value="UTF-8">
+<a href="http://www.google.com/">
+<img src="http://www.google.com/logos/Logo_40wht.gif" 
+border="0" alt="Google Search" align="middle" width="150" height="55"></a>
+<input type="text" name="as_q" size="25" maxlength="255" value="HTML">
+&nbsp;
+<input type="submit" name="btnG" value="Google Search">
+</form>
+<!-- Search Google -->
+</p>
+
+<p>
+See a demonstration of "html" and "html forms" with our 
+<a name="mirror-example" href="http://forrest.apache.org/mirrors.cgi">Forrest download mirror</a>
+facility and the
+<a href="http://forrest.apache.org/howto/howto-asf-mirror.html">explanation</a> howto document.
+</p>
+
+<h2>Potentially Invalid XDocs</h2>
+
+<p>
+As shown above, you can add various different non-standard elements to enable
+other processing and abilities.
+However, it should also be noted that the resultant intermediate XML is not a valid document
+since it contains the additional HTML elements. If you are intending to use
+the intermediate XDocs for any purpose, then be aware of this fact.</p>
+
+<h2><a name="invalid" />Auto-correction of invalid HTML</h2>
+<p>
+This paragraph has a missing closing tag for the &lt;p&gt; element. If you look
+at the <a href="embedded_html.xml" title="view intermediate xml in separate window" target="_blank">intermediate XML created by Forrest</a> you'll notice that 
+Forrest has fixed this.
+
+<h2><a name="blink" />Other non-standard html-type abilities</h2>
+<p>
+Use other HTML <blink>delights (???) and tricks</blink>.
+</p>
+</body>
+</html>

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/embedded_html.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/faq.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/faq.xml?view=auto&rev=556367
==============================================================================
--- forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/faq.xml (added)
+++ forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/faq.xml Sat Jul 14 23:39:28 2007
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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 faqs PUBLIC "-//APACHE//DTD FAQ V2.0//EN" "http://forrest.apache.org/dtd/faq-v20.dtd">
+<faqs>
+  <title>Frequently Asked Questions</title>
+  <faqsection id="docs">
+    <title>Documentation</title>
+    <faq id="forrest">
+      <question>
+        How can I help write documentation?
+      </question>
+      <answer>
+        <p>
+          This project uses <a href="ext:forrest">Apache Forrest</a> to generate
+          documentation from XML. Please download a copy of Forrest, which can
+          be used to <a
+            href="ext:forrest/validation">validate</a>,
+          <a
+            href="ext:forrest/webapp">develop</a> and render a
+          project site.
+        </p>
+      </answer>
+    </faq>
+<!-- More faqs or parts here -->
+  </faqsection>
+  <faqsection id="motd">
+    <title>Message of the day (MOTD).</title>
+    <faq id="motd1">
+      <question>
+	How do I enable MOTD?
+      </question>
+      <answer>
+        <p>
+          There is example MOTD code in /src/documentation/skinconf.xml. Enable
+          this and make sure the motd-option pattern URI points to the page or
+          pages you want the message to appear.
+        </p>
+      </answer>
+    </faq>
+  </faqsection>
+<!-- More faqs or parts here -->
+</faqs>

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/faq.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/hello-v10.dtd
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/hello-v10.dtd?view=auto&rev=556367
==============================================================================
--- forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/hello-v10.dtd (added)
+++ forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/hello-v10.dtd Sat Jul 14 23:39:28 2007
@@ -0,0 +1,49 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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.
+-->
+<!-- ===================================================================
+
+     Apache Hello Document DTD (Version 1.1)
+
+PURPOSE:
+  This DTD was developed to create a sample of custom document.
+
+TYPICAL INVOCATION:
+
+  <!DOCTYPE greeting PUBLIC
+       "-//APACHE//DTD Hello Document Vx.y//EN"
+       "hello-vxy.dtd">
+
+  where
+
+    x := major version
+    y := minor version
+
+NOTES:
+
+FIXME:
+
+CHANGE HISTORY:
+[Version 1.0]
+  20050112 Initial version. (JJP)
+
+==================================================================== -->
+
+<!ELEMENT greeting (#PCDATA)>
+
+<!-- =============================================================== -->
+<!-- End of DTD -->
+<!-- =============================================================== -->

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/hello-v10.dtd
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/helloAgain.pdf
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/helloAgain.pdf?view=auto&rev=556367
==============================================================================
Binary file - no diff available.

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/helloAgain.pdf
------------------------------------------------------------------------------
    svn:mime-type = application/pdf

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/howto-howto.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/howto-howto.xml?view=auto&rev=556367
==============================================================================
--- forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/howto-howto.xml (added)
+++ forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/howto-howto.xml Sat Jul 14 23:39:28 2007
@@ -0,0 +1,230 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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 howto PUBLIC "-//APACHE//DTD How-to V2.0//EN"
+"http://forrest.apache.org/dtd/howto-v20.dtd">
+<howto>
+  <header>
+    <title>How to write a How-To</title>
+    <version>0.3</version>
+    <abstract>
+      This How-To describes the steps necessary to write a How-To document.
+      Writing documentation is a valuable way to give back to the community.
+    </abstract>
+    <last-modified-content-date date="2005-07-18" />
+  </header>
+  <audience title="Intended Audience">
+    <p>
+      Users who are ready to share their knowledge and experiences with the
+      community.
+    </p>
+  </audience>
+  <purpose title="Purpose">
+    <p>
+      These guidelines are based on successful how-to document structures used
+      by other open source projects with diverse author groups. Following these
+      tried and true guidelines will help to ensure the effectiveness of your
+      work.
+    </p>
+  </purpose>
+  <prerequisites title="Prerequisites">
+    <p>
+      How-To authors should have:
+    </p>
+    <ul>
+      <li>A unique How-To topic, related to using Forrest, which fulfills a
+      specific need. Look at existing How-Tos to find a niche for your work.
+      Consider posting your idea for the How-To to user mailing list, to make
+      sure another author's draft is not already in process.</li>
+      <li>A sufficient ability in English to write the document. However, we would
+      rather that you just make a start, as the community can help to
+      fine-tune the document.</li>
+      <li>Copy this template document "howto-howto.xml" to be modified with
+      your own content as necessary.</li>
+      <li>An understanding of the How-To document structure. Just use this
+      template document and you will be safe.
+      Make sure you run '<code>forrest validate-xdocs</code>' before
+      contributing your document.</li>
+    </ul>
+  </prerequisites>
+  <steps title="Steps">
+    <p>
+      Here is how to proceed.
+    </p>
+    <section id="overview">
+      <title>Write the Overview</title>
+      <p>
+        An overview helps potential readers to determine quickly if a particular
+        How-To matches their interests or needs. In a few sentences, summarize
+        the main points of your How-To. Make sure to include any critical
+        definitions which will help readers evaluate the utility of your How-To.
+        Consider writing the overview last, after you have completed all other
+        sections.
+      </p>
+    </section>
+    <section id="audience">
+      <title>Describe your Intended Audience</title>
+      <p>
+        If your How-To is targetted at a specific audience, describe it here.
+        For example, potential readers will have different levels of skill using
+        Forrest. They will also bring different areas of expertise and
+        backgrounds to their How-To learning experience. When you clarify your
+        target audience up front, you will save all other readers time and
+        confusion.
+      </p>
+    </section>
+    <section id="purpose">
+      <title>State the Purpose</title>
+      <p>
+        State the purpose of your How-To. Explain how the reader will benefit by
+        reading it. Give your reader an incentive or two to continue.
+      </p>
+    </section>
+    <section id="prerequisites">
+      <title>List any Prerequisites</title>
+      <p>
+        Inform your reader about any required knowledge, configuration, or
+        resources they may need before stepping through your How-To. Assist them
+        in this preparation by linking to other useful resources on the Forrest
+        site or the web. Helping your readers to prepare increases the
+        likelihood that they will continue reading your How-To.
+      </p>
+    </section>
+    <section id="steps">
+      <title>Describe the Steps of your How-To</title>
+      <p>
+        In a precise, step-by-step approach, walk your reader through the
+        process. Make sure your reader can reproduce your intended result by
+        following your exact steps. Make the learning process efficient by
+        supplying sample code snippets or configuration details as necessary.
+      </p>
+    </section>
+    <section id="extension">
+      <title>Extend the Learning</title>
+      <p>
+        Provide your reader with a few real-world examples of how the techniques
+        or capabilities gained from your How-To could be applied. Reward the
+        reader for successfully completing the How-To with a few ideas about how
+        it will pay off.
+      </p>
+    </section>
+    <section id="summarize">
+      <title>Summarize the Entire Process</title>
+      <p>
+        In a few sentences, remind the reader what they have just learned. This
+        helps to reinforce the main points of your How-To.
+      </p>
+    </section>
+    <section id="tips">
+      <title>Additional Tips or FAQs</title>
+      <p>
+        In some cases, step-by-step instructions simply aren't enough. Use this
+        section to pass on any other tips or frequently asked questions.
+        Anticipating the needs of your readers will increase the overall success
+        of your writing effort.
+      </p>
+    </section>
+    <section id="references">
+      <title>References</title>
+      <p>
+        Remember to acknowledge any third-party resources or individuals who
+        contributed to the development of your How-To. Consider providing links
+        for those motivated readers who want to learn more.
+      </p>
+    </section>
+    <section id="contribute">
+      <title>Submit via the project issue tracker</title>
+      <p>
+        Create an attachment for your How-To document, and submit it via the
+        project issue tracker.
+      </p>
+    </section>
+    <section id="feedback">
+      <title>Get some feedback</title>
+      <p>
+        When the committers have added your document then it will be available
+        for everyone to to build upon and enhance. Feedback will happen via the
+        mailing lists.
+      </p>
+    </section>
+  </steps>
+  <extension title="Extension">
+    <p>
+      Solutions can be extended to cover many different problem domains. A
+      nearly unlimited number of potential How-To topics, from simple to
+      complex, are available right now, limited only by your imagination.
+    </p>
+  </extension>
+  <faqs id="faqs">
+    <title>Frequently Asked Questions</title>
+    <faqsection id="faq-general">
+      <title>General issues</title>
+      <faq id="faq-difference">
+        <question>What is the difference between a How-To and a
+        tutorial?</question>
+        <answer>
+          <p>
+            The goal of a How-To is to help the reader to accomplish a specific
+            task with clear and consise instructions. While tutorials may
+            contain How-To-like instructions and content, they also include
+            additional background and conceptual content to help teach their
+            readers higher order concepts along the way. How-Tos are concerned
+            about filling an immediate, short-term need. Tutorials often provide
+            long-term knowledge which can be applied across a range of needs.
+          </p>
+        </answer>
+      </faq>
+    </faqsection>
+    <faqsection id="faq-style">
+      <title>Style issues</title>
+      <faq id="spelling">
+        <question>What spelling convention should I follow?</question>
+        <answer>
+          <p>
+            Use whatever spelling convention (American, British, etc.) that is
+            most intuitive to you.
+          </p>
+        </answer>
+      </faq>
+    </faqsection>
+  </faqs>
+  <tips title="Tips">
+    <section id="tip-dtd">
+      <title>How-To dtd</title>
+      <p>
+        The document structure is likely to change at some time. Please note
+        that this HOWTO page is likely to change as well.
+      </p>
+    </section>
+  </tips>
+  <references title="References">
+    <p>
+      This is not the first, nor will it be the last, How-To on writing How-Tos.
+      For other ideas and opinions on the matter, check out the following
+      sources.
+    </p>
+    <ul>
+      <li>Joel D. Canfield's <a
+      href="http://www.evolt.org/article/How_To_Write_A_How_To/9741/18250/index.html">How
+      to Write a How-To</a> on evolt.org.</li>
+      <li>The Linux Documentation Project's <a
+      href="http://www.tldp.org/HOWTO/HOWTO-INDEX/index.html">HOWTO</a>
+      index page provides many excellent How-To documents to inspire your
+      efforts.</li>
+    </ul>
+  </references>
+</howto>

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/howto-howto.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/icon-d.png
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/icon-d.png?view=auto&rev=556367
==============================================================================
Binary file - no diff available.

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/icon-d.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/index.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/index.xml?view=auto&rev=556367
==============================================================================
--- forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/index.xml (added)
+++ forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/index.xml Sat Jul 14 23:39:28 2007
@@ -0,0 +1,63 @@
+<?xml version="1.0"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+  <header>
+    <title>Samples 1 Documentation</title>
+  </header>
+  <body>
+    <section id="samples1-intro">
+      <title>Samples 1 Documentation Overview</title>
+      <p>
+              Samples are currently split into two areas. This is purely to help
+              envisage and document by example the usage of tabs and sub-tabs.
+              One section is no more important than the other.
+      </p>
+      <ul>
+              <li>The Navigation Menu will show documentation contained in the 'samples1' directory.</li>
+              <li>The Navigation highlights the current page. (This index.html page has a label of 'Overview')</li>
+              <li>The current selected 'Tab' will show 'Samples'.</li>
+              <li>The current selected 'SubTab' will show 'Samples 1'</li>
+      </ul>
+    </section>
+    <section id="samples1-docs">
+      <title>Documentation contained in Samples 1</title>
+      <ul>
+              <li><a href="site:docs-samples1/sample">Apache Doc V2.0</a> A demonstration document using all elements in the Apache Forrest xdocs document-v20.dtd.</li>
+              <li><a href="site:docs-samples1/linking">Linking</a> A Demonstration of Linking.</li>
+              <li><a href="site:docs-samples1/sample-howto">HowTo</a> Describes the steps neccessary to create a How-To document.</li>
+              <li><a href="site:docs-samples1/sample-html">Embedded HTML</a> A demonstration page showing how to embed HTML in Forrest.</li>
+              <li><a href="site:docs-samples1/sample-ascii-art">ascii-art page</a> ASCII Art Sample page.</li>
+              <li><a href="site:docs-samples1/svg">Using SVG</a> Using Scalable Vector Graphics (SVG), contains links to SVG examples.</li>
+              <li><a href="site:docs-samples1/sample-usemap">Usemap</a> Interactive client-side imagemaps - the usemap attribute.</li>
+              <li><a href="site:docs-samples1/sample-custom">Custom Schema</a> Contains a custom schema example.</li>
+              <li><a href="site:docs-samples1/xml-entities">XML Entities</a> Using XML entities for character replacements.</li>
+              <li><a href="site:docs-samples1/faq">FAQ</a> Frequently Asked Questions.</li>
+              <li><a href="site:docs-samples1/locationmap">Locationmap</a> An introduction and examples of using the Locationmap.</li>
+
+      </ul>
+</section>
+<section id="samples1-where-else">
+        <title>Links to other Sample Documentation</title>
+      <p>
+              Take a look at <a href="site:samples/overview">the Samples Index</a> to view other
+              samples sections. (Currently we have 'Samples 1' and '<a href="site:docs-samples2/index">Samples 2</a>')
+      </p>
+    </section>
+  </body>
+</document>

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/index.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/linking.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/linking.xml?view=auto&rev=556367
==============================================================================
--- forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/linking.xml (added)
+++ forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/linking.xml Sat Jul 14 23:39:28 2007
@@ -0,0 +1,555 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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 id="no-decoration">
+        <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>
+&lt;map:match pattern="**.html"&gt;
+ &lt;map:select type="exists"&gt;
+  &lt;map:when test="{properties:content}{0}"&gt;
+    &lt;map:read src="{properties:content}/{0}" mime-type="text/html"/&gt;
+    &lt;!--
+      Use this instead if you want JTidy to clean up your HTML
+      &lt;map:generate type="html" src="{properties:content}/{0}" /&gt;
+      &lt;map:serialize type="html"/&gt;
+    --&gt;
+  &lt;/map:when&gt;
+  &lt;map:when test="{properties:content.xdocs}{0}"&gt;
+    &lt;map:read src="{properties:content.xdocs}/{0}" mime-type="text/html"/&gt;
+    &lt;!--
+      Use this instead if you want JTidy to clean up your HTML
+      &lt;map:generate type="html" src="{properties:content.xdocs}/{0}" /&gt;
+      &lt;map:serialize type="html"/&gt;
+    --&gt;
+  &lt;/map:when&gt;
+ &lt;/map:select&gt;
+&lt;/map:match&gt;
+        </source>
+        <p>
+          The above allows us to create links to un-processed skinned files
+          stored in the <code>{properties:content}</code> or
+          <code>{properties:content.xdocs}</code> directory. For example: &lt;a
+          href="/test1.html"&gt;HTML content&lt;/a&gt;. 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>
+&lt;map:match pattern="old_site/**.html"&gt;
+ &lt;map:select type="exists"&gt;
+  &lt;map:when test="{properties:content}{1}.html"&gt;
+    &lt;map:read src="{properties:content}/{1}.html" mime-type="text/html"/&gt;
+    &lt;!--
+      Use this instead if you want JTidy to clean up your HTML
+      &lt;map:generate type="html" src="{properties:content}/{0}" /&gt;
+      &lt;map:serialize type="html"/&gt;
+    --&gt;
+  &lt;/map:when&gt;
+&lt;/map:match&gt;
+        </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>
+    <section id="images">
+      <title>Images</title>
+      <p>
+        Images (and other resources) are handled by the
+        main/webapp/resource.xmap sitemap. It uses the
+        main/webapp/locationmap.xml to look in various locations for images. As
+        usual, the first match wins.
+      </p>
+      <p>
+        Here is the locationmap snippet ...
+      </p>
+      <source>
+<![CDATA[
+    <match pattern="project.images.**.*">
+      <select>
+        <location src="{properties:resources.images}{1}.{2}" />
+        <location src="{properties:content}../resources/images/{1}.{2}" />
+        <location src="{properties:content.xdocs}images/{1}.{2}" />
+        <location src="{properties:content.xdocs}{1}.{2}" />
+      </select>
+    </match>
+]]>
+      </source>
+      <p>
+        Which means look first in a project-defined images directory, then in
+        the default location (which is usually
+        src/documentation/resources/images/), then in the old default location
+        (src/documentation/content/xdocs/images/), then relative to the root of
+        your xdocs.
+      </p>
+      <p>
+        The document author specifies the final image locations with these
+        various "<code>src=</code>" links. Behind-the-scenes Cocoon handles the
+        requests using the sitemap and locationmap.
+      </p>
+      <p>
+        This sample has the following image locations:
+      </p>
+      <source>
+<![CDATA[
+    src/documentation/resources/images/ellipse-2.svg
+    src/documentation/resources/images/icon-a.png
+    src/documentation/resources/images/icon-b.png
+    src/documentation/resources/images/sub-dir/icon-c.png
+    src/documentation/content/xdocs/images/icon-e.png
+    src/documentation/content/xdocs/samples/icon-d.png
+    src/documentation/content/xdocs/samples/ellipse.svg
+    src/documentation/content/xdocs/samples/cocoon-pyramid.aart
+]]>
+      </source>
+      <p>
+        Here is the effect of the various image links ...
+      </p>
+      <ol>
+        <li><img src="/images/icon-a.png" alt="Icon" /><code>&lt;img src="/images/icon-a.png"</code>
+          ... The source file is found in src/documentation/resources/images/ directory.
+        </li>
+        <li><img src="/images/sub-dir/icon-c.png" alt="Icon" /><code>&lt;img src="/images/sub-dir/icon-c.png"</code>
+          ... The source file is found in src/documentation/resources/images/sub-dir/ directory.
+        </li>
+        <li><img src="/images/icon-e.png" alt="Icon" /><code>&lt;img src="/images/icon-e.png"</code>
+          ... The source file is not found in the normal src/documentation/resources/images/
+          so Cocoon looks in the next location and finds the source in
+          src/documentation/content/xdocs/images/ directory.
+          This supports backward-compatibility for this old default location.
+        </li>
+        <li><img src="images/icon-a.png" alt="Icon" /><code>&lt;img src="images/icon-a.png"</code>
+          ... same as example 1 above. Except this time the generated image is relative to the document.
+        </li>
+        <li><img src="../images/icon-a.png" alt="Icon" /><code>&lt;img src="../images/icon-a.png"</code>
+          ... Relative reference. Forrest "absolutizes" the URLs to be like the URLs
+          in examples 1 and 2 and 3. Then Cocoon looks in the normal locations as described above.
+          The source file is found in src/documentation/resources/images/ directory.
+        </li>
+        <li><img src="../../images/icon-b.png" alt="Icon" /><code>&lt;img src="../../images/icon-b.png"</code>
+          ... Broken relative reference (it points up beyond the document root).
+          Never mind, Forrest "absolutizes" the URLs to be like the URLs in examples 1 and 2 and 3. 
+          The source file is found in src/documentation/resources/images/ directory.
+          However there is a problem here. When using Forrest in command-line mode,
+          the image will be generated outside the document directory.
+          It is better to use absolute /image/ URLs or be very careful about using
+          such relative links (Forrest will not report an error).
+        </li>
+        <li><img src="/images/ellipse-2.png" alt="Icon" />
+          <br /><code>&lt;img src="/images/ellipse-2.png"</code>
+        ... Cocoon tried the various locations for a PNG image called
+        ellipse-2.png but did not find one anywhere. So the next sitemap match
+        looks for a corresponding
+        ellipse-2.svg and generates the PNG image on-the-fly.
+        The source file is found in src/documentation/resources/images/ directory.
+      </li>
+<!-- Remove this sample.
+  See: http://marc.theaimsgroup.com/?t=114925130200003
+        <li>
+          <img src="/icon-b.png" alt="Icon" />
+          <code>&lt;img src="/icon-b.png"</code>
+          ... Magic.
+          The source file is found in src/documentation/resources/images/ directory.
+        </li>
+-->
+      </ol>
+      <p>
+        The image links shown above are handled by the resources.xmap using
+        special matches for the "images" directory in the URI.
+      </p>
+      <p>
+        The main/webapp/resources.xmap has another section to deal specifically
+        with PNG images. It looks first for an SVG source file which will be
+        used to generate the PNG image. If that is not found then it looks for
+        an ASCII art source file. Then looks for a pre-prepared PNG image.
+      </p>
+      <ol>
+        <li><img src="ellipse.png" alt="Icon" />
+          <br /><code>&lt;img src="ellipse.png"</code>
+        ... Cocoon tried the various locations for a PNG image called
+        ellipse-2.png but did not find one anywhere. So the next sitemap match
+        looks for a corresponding
+        ellipse-2.svg and generates the PNG image on-the-fly.
+        The source file is found in the current directory src/documentation/content/xdocs/samples/
+      </li>
+        <li><img src="cocoon-pyramid.png" alt="Icon"/>
+          <br /><code>&lt;img src="cocoon-pryamid.png"</code>
+        ... ASCII Art. Cocoon did not find a PNG image, nor an SVG file.
+        So the next sitemap match looks for a corresponding
+        cocoon-pryamid.aart and generates the PNG image on-the-fly.
+        The source file is found in the current directory src/documentation/content/xdocs/samples/
+        </li>
+        <li><img src="icon-d.png" alt="Icon" /><code>&lt;img src="icon-d.png"</code>
+          ... Relative to this document.
+          The source file is found in the current directory src/documentation/content/xdocs/samples/
+        </li>
+      </ol>
+      <note>
+        You might wonder why the above images all show correctly in dynamic
+        'forrest run' mode, but some appear to be broken during static docs
+        generation 'forrest site' mode. The latter is for generating a set of
+        static docs for deployment to a server. If you used URLs beginning with
+        a slash, "/images/...", then that is their location. So the generated
+        docs on the "<a href="ext:forrest-zone">forrest zone</a>" demos appear
+        to be broken.
+      </note>
+    </section>
+  </body>
+</document>

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/linking.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/locationmap/index.xml
URL: http://svn.apache.org/viewvc/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/locationmap/index.xml?view=auto&rev=556367
==============================================================================
--- forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/locationmap/index.xml (added)
+++ forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/locationmap/index.xml Sat Jul 14 23:39:28 2007
@@ -0,0 +1,131 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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://forrest.apache.org/dtd/document-v20.dtd">
+<document>
+  <header>
+    <title>Locationmaps</title>
+  </header>
+  <body>
+    <section id="overview">
+      <title>About Locationmaps</title>
+      <p>
+        A locationmap defines a mapping from requests to location strings.
+      </p>
+      <p>
+        It was conceived to:
+      </p>
+      <ul>
+        <li>Provide a more powerful means for semantic linking.</li>
+        <li>Enable Forrest with a standard configuration override mechanism.</li>
+        <li>decouple the conceptual source space used by Cocoon from
+        the concrete source space, so that a change in the concrete sources
+        does not impact on the sitemap</li>
+      </ul>
+      <p>
+        The syntax of a locationmap resembles that of the sitemap in that it
+        also makes use of Matchers and Selectors to traverse a tree of nodes
+        towards a leaf. In the case of the locationmap however the leaf does not
+        identify a pipeline but instead identifies a location string.
+      </p>
+    </section>
+    <section id="examples">
+      <title>Locationmap Examples</title>
+      <section>
+        <title>Retrieving an XDoc via HTTP</title>
+        <p>
+          Normally files are generated from
+          <code>{properties:content.xdocs}</code>. Using the Locationmap it is
+          possible to make these files come from elsewhere. This is useful if
+          you want to pull files from different directory structures, oe even
+          remote repositories.
+        </p>
+        <p>
+          The target of "/remote.**.html" is generated from a source retrieved
+          from the Forrest SVN.
+        </p>
+        <note>
+          Because the above URL retrieves the source file from SVN it will only
+          work if you are online. For this reason we have not enabled this link
+          as it would stop you building this site offline. However, if you are
+          online you can enter the URL into the browser and it will work
+          (however, note the issue described below, regarding the site: and ext:
+          protocols).
+        </note>
+        <p>
+          Go to <code>http://localhost:8888/remote.index.html</code> which will
+          virtually re-load this page. However, rather than use the local xml
+          source, the locationamp has retrieved the up-to-date source directly
+          from the svn server. Similarly
+          <code>http://localhost:8888/remote.samples/index.html</code>
+        </p>
+        <p>
+          The match in src/documentation/content/locationmap.xml for this demo
+          is ...
+        </p>
+        <source>
+ &lt;match pattern="project.remote.**.xml"&gt;
+   &lt;location src="http://svn.apache.org/repos/asf/forrest/trunk/main/fresh-site/src/documentation/content/xdocs/{1}.xml" /&gt;
+ &lt;/match&gt;
+        </source>
+        <p>
+          Since we are using the locationmap naming convention, our new match
+          get resolved via the core forrest.xmap and we do not have to change
+          any other files.
+        </p>
+        <source>
+<![CDATA[
+<map:match pattern="**.xml">
+  <map:generate src="{lm:project.{0}}"/>
+  <map:serialize type="xml"/>
+</map:match>
+]]>
+        </source>
+        <p>
+          Note that because this is a wildcard matcher you can request any page
+          from SVN simply by requesting
+          <code>/remote.PATH/TO/FILE/FILENAME.html</code>. In addition, we can
+          request any other output format available via Forrest plugins.
+        </p>
+        <p>
+          When including resources from remote repositories one has to be
+          careful about things like <code>site:</code> and <code>ext:</code>
+          linking. If the targets are not defined in the local
+          <code>site.xml</code> file then these links will be broken, which is
+          the normal situation.
+        </p>
+      </section>
+      <section>
+        <title>Link Rewriting</title>
+        <p>
+          The locationmap can be used to rewrite URLs when the page is
+          generated. For example, when the locationmap has:
+        </p>
+        <source>
+ &lt;match pattern="project.rewrite.**"&gt;
+   &lt;location src="http://cocoon.apache.org/{1}.html" /&gt;
+ &lt;/match&gt;
+        </source>
+        <p>
+          <a href="lm:rewrite.index">This link is rewritten to an offsite
+          address</a> not specified in the link, which has
+          <code>href="lm:rewrite.index"</code>.
+        </p>
+      </section>
+    </section>
+  </body>
+</document>

Propchange: forrest/trunk/main/fresh-site/src/documentation/content/xdocs/samples1/locationmap/index.xml
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message