forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r376128 [21/34] - in /forrest/site: ./ docs_0_60/ docs_0_60/howto/ docs_0_60/howto/bugzilla-patch/ docs_0_60/howto/multi/ docs_0_70/ docs_0_70/howto/ docs_0_70/howto/cvs-ssh/ docs_0_70/howto/multi/ docs_0_80/ docs_0_80/howto/ docs_0_80/howt...
Date Thu, 09 Feb 2006 00:26:32 GMT
Added: forrest/site/docs_0_80/primer.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/primer.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/primer.source.xml (added)
+++ forrest/site/docs_0_80/primer.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,558 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  Copyright 2002-2005 The Apache Software Foundation or its licensors,
+  as applicable.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document> 
+  <header> 
+    <title>The Forrest Primer</title> 
+    <subtitle>Don't panic!</subtitle> 
+    <abstract>Forrest is a so-called
+      <link href="http://www.dictionary.com/cgi-bin/dict.pl?term=fledgling">fledgling</link>
+      project that will have a broad impact on
+      <link href="http://xml.apache.org/">xml.apache.org</link> projects. This document
+      helps you to better understand the vision and scope of Forrest, so that you
+      learn what to expect (or not) from it, and eventually will help you discovering
+      places where your contribution could be valuable to all of us.</abstract> 
+  </header> 
+  <body> 
+    <warning>This document is <em>very</em> out of date. There is a lot of good
+      information here, but the focus of the project has shifted away from the
+      Sourceforge-like project management system described here, towards being a
+      simpler project-centric documentation tool -- JT</warning> 
+    <section>
+      <title>History</title> 
+      <p>Forrest has come into existence because of the abysmal state of the
+        <link href="http://xml.apache.org/">xml.apache.org</link> website in comparison
+        with other open source community sites such as Sourceforge. The old site had no
+        consistent visual look and feel, which was largely due to each and every
+        sub-project managing its own site. Furthermore, much information which could
+        potentially support community-based open source development was hidden inside
+        CVS repositories, mailing lists or word of mouth. Once we experienced the
+        usefullness of cross-project collaboration supported by the Jakarta
+        <link href="http://jakarta.apache.org/gump">Gump</link> project, we reckoned
+        having a single application responsible for the management of the
+        xml.apache.org site could be of benefit to our visitors. And if we added
+        aggregated access to other available resources such as download stats or
+        mailing list archives, the new xml.apache.org website could be a true
+        information clearinghouse for interested parties, both users and contributors
+        alike.</p> 
+      <p>The Forrest vision was articulated by Stefano Mazzocchi and Sam Ruby,
+        both long-time contributors to Apache projects, in the beginning of 2002, and
+        was rapidly picked up by a bunch of other 
+        <link href="site:who">contributors</link> as well, after a headstart by Nicola Ken
+        Barozzi. So here we are, plenty of work-in-progress to erect what eventually
+        will become a true community website infrastructure for Apache open source
+        development.</p> 
+    </section> 
+    <section>
+      <title>What is Forrest</title>
+      <p>Forrest is a framework that supports the cross-project generation and
+        management of development project websites using Cocoon as its XML publishing
+        framework. It not only provides access to project documentation, but also to
+        other types of information that open source developers depend upon daily:
+        source code repositories, mailing lists, contact info and the like. It
+        aggregates all these resources and publishes them on a regular basis to a
+        website, ensuring a consistent look and feel using skins implemented with XSLT
+        stylesheets. While Forrest's primary focus is XML Apache project websites, it
+        can be adapted to other community development projects as well, as long as they
+        are willing to commit to proven best practices such as Ant for build
+        automation, CVS for source code control and XML as a documentation source
+        format.</p> 
+      <p>Forrest is currently based on an
+        <link href="http://jakarta.apache.org/ant/">Ant</link>-based project build
+        system called <link href="http://www.krysalis.org/centipede/">Centipede</link>
+        that drives a <link href="http://cocoon.apache.org/">Cocoon</link>-based
+        document publication system. It contains a set of standard XML document type
+        declarations (DTDs) for project documentation, and different 'skins' consisting
+        of XSLT stylesheets that produce HTML renditions of XML documents using these
+        DTDs.</p> 
+      <p>The primary mode of operations for Forrest will be as follows:</p> 
+      <note>This process is not quite ready for prime time yet, but it gives
+        you an idea where we are heading to. Website generation with skins currently
+        works, try using the <code>docs</code> target when invoking the
+        <code>build</code> script. Add a <code>project.skin</code> property when invoking
+        the build script to experience Forrest skins: <code>build{.bat|.sh}
+          -Dproject.skin=&lt;thenameoftheskintouse&gt; docs</code>. Read our
+        <link href="#cvs">CVS crash course</link> to get hold of the current codebase and
+        start playing with it.</note> 
+      <ol> 
+        <li>Forrest will harvest documentation and related source files from
+          each of the projects within the community that uses Forrest for their website,
+          usually direct from the CVS repository. Which projects are included, and how
+          they are retrieved is configured by a project descriptor file. This is an
+          automated process that occurs several times a day to ensure Forrest has the
+          latest information available.</li>
+        <li>Forrest then uses Cocoon to generate an HTML rendition of each
+          project's website, configured by a generic sitemap. The result is a static
+          collection of HTML documents and related images and stylesheets comprising the
+          project's website. The impact Forrest has on the participating projects should
+          be minimal, i.e. one should simply author XML documents, put them in a
+          well-specified filesystem hierarchy, and Forrest will do its work.</li> 
+        <li>Forrest will enrich the documentation source files with common
+          information: a cross-project navigation structure (and rendition, of course),
+          and useful 'community indicators' such as download statistics, number of
+          contributors with commit access, ...</li> 
+        <li>If the individual project build runs are successful, the project's
+          website is automagically (re-)published to the (Apache) website, also several
+          times day.</li> 
+      </ol> 
+      <p>The Forrest website and the overall xml.apache.org website are
+        maintained and published using the same mechanism.</p> 
+    </section> 
+    <section>
+      <title>Forrest roles</title>
+      <p>Depending on your interests, your involvement with Forrest may vary,
+        hence your <em>role</em>. We currently envision three different roles:</p> 
+      <ul> 
+        <li><strong>User</strong> you want or need to use Forrest for your
+          project because it uses Forrest to manage its documentation.</li> 
+        <li><strong>Adaptor</strong> you want to adapt Forrest to support your
+          individual project needs, presumably outside the XML Apache context, building
+          your own skins or DTDs and the like.</li> 
+        <li><strong>Contributor</strong> you are a fledgling Forresteer and
+          want to contribute to the further development of it. If your contributions are
+          valuable and in true community spirit, you can possibly gain commit access to
+          the Forrest CVS repository and become an Apache committer. The first stage
+          towards becoming a contributor is to join the forrest dev
+          <link href="site:mail-lists">mailing list</link>, the second is to download
+          Forrest and start playing with it (see below).</li> 
+      </ul> 
+      <p>Depending on your role, your potential area of interest in Forrest
+        will vary:</p> 
+      <table> 
+        <tr> 
+          <th colspan="1" rowspan="1">Role</th> 
+          <th colspan="1" rowspan="1">Interests</th> 
+        </tr> 
+        <tr> 
+          <td colspan="1" rowspan="1">User</td> 
+          <td colspan="1" rowspan="1">Forrest DTDs and documentation filesystem hierarchy (Cocoon
+            sitemap)</td> 
+        </tr> 
+        <tr> 
+          <td colspan="1" rowspan="1">Adaptor</td> 
+          <td colspan="1" rowspan="1">+ skin system and build environment</td> 
+        </tr> 
+        <tr> 
+          <td colspan="1" rowspan="1">Contributor</td> 
+          <td colspan="1" rowspan="1">+ the Forrest codebase and runtime environment</td> 
+        </tr> 
+      </table> 
+    </section> 
+    <section id="cvs">
+      <title>Getting your local copy of Forrest through CVS</title> 
+      <section>
+        <title>System requirements</title>
+        <p>Forrest requires the following systems to be already installed on
+          your system:</p> 
+        <ul> 
+          <li><em>Java Virtual Machine</em> A Java virtual machine must be
+            present. Forrest has been tested against the latest Sun 1.3 JDK.</li> 
+        </ul> 
+      </section> 
+      <section>
+        <title>Getting Forrest</title>
+        <p>You can retrieve Forrest from its CVS repository or download
+         <link href="http://www.apache.org/dyn/closer.cgi/xml/forrest/">here</link>.
+          <br/>Some help with CVS follows (courtesy of our friends of the Cocoon project).</p> 
+      </section> 
+      <section>
+        <title>Step-by-step cvs instructions for Windows</title>
+        <ol> 
+          <li>Download a recent release of WinCVS (homepage is
+            <link href="http://www.wincvs.org/">http://www.wincvs.org/</link>); </li> 
+          <li>Install it;</li> 
+          <li>Start it;</li> 
+          <li>Click on Admin-&gt;Preferences;</li> 
+          <li> In "Enter the CVSROOT:" enter
+            "<code>:pserver:anoncvs@cvs.apache.org:/home/cvspublic</code>" (without
+            quotes);</li> 
+          <li>In "Authentication:" choose "passwd file on the cvs server";</li> 
+          <li>Click "Ok";</li> 
+          <li>Click Admin-&gt;Login;</li> 
+          <li> When asked for the password: answer "<code>anoncvs</code>"
+            (without quotes);</li> 
+          <li> Click "Create-&gt;Checkout module";</li> 
+          <li>Module name and path on the server is "<code>xml-forrest</code>"
+            (no quotes);</li> 
+          <li>Choose a dir to put the source code in;</li> 
+          <li>Click "Ok";</li> 
+          <li>If everything goes well, messages will start to appear in the log
+            window;</li> 
+          <li>Wait until you see "<code>*****CVS exited normally with code
+              0*****</code>" in the log window;</li> 
+          <li>The Forrest source is now on your harddrive.</li> 
+        </ol> 
+      </section> 
+      <section>
+        <title>Step-by-step cvs instructions for Unix</title>
+        <ol> 
+          <li>Make sure you have a CVS client package installed on your Unix
+            system.</li> 
+          <li>Start the shell of your choice.</li> 
+          <li>Enter "<code>cvs -d
+              :pserver:anoncvs@cvs.apache.org:/home/cvspublic login</code>".</li> 
+          <li>When asked for the password: answer "<code>anoncvs</code>".</li> 
+          <li>Enter "<code>cvs -d
+              :pserver:anoncvs@cvs.apache.org:/home/cvspublic -z3 checkout
+              xml-forrest</code>". This will create a directory called
+            "<code>xml-forrest</code>" where the Forrest source will be stored.</li> 
+          <li>Wait until cvs has finished.</li> 
+          <li>The Forrest source is now on your harddrive.</li> 
+        </ol> 
+        <p>In case you want to update your Forrest source tree to the current
+          version, change to the "<code>xml-forrest</code>" directory and invoke
+          "<code>cvs -z3 update -d -P</code>".</p> 
+      </section> 
+    </section> 
+    <section>
+      <title>Forrest distribution</title>
+      <p>Once you retrieved Forrest from its CVS repository, you will end up
+        with a filesystem hierarchy similar to this inside the <code>xml-forrest</code>
+        home directory:</p> 
+      <warning>This is highly volatile information!</warning> 
+      <source xml:space="preserve"><![CDATA[+---legal                             various licenses for included projects
++---lib                               jar library
++---src
+|   +---documentation               Forrest's documentation (not generally reusable)
+|   |   +---content                 content of the Forrest website
+|   |   |   +---xdocs               Forrest website XML documents
+|   |   +---resources               Forrest-specific doc resources
+|   |   |   +---images
+|   +---resources                   Generic resources for any Forrest-using project.
+|   |   +---conf                    Default (overridable) Forrest config files
+|   |   +---library                 common components (not skin-specific)
+|   |   |   +---xslt                document format transformers e.g. faq->xdoc
+|   |   +---convert                 XSLTs for aiding a transition to Forrest
+|   |   +---skins                   Forrest skins
+|   |       +---basic
+|   |       +---forrest-site        the future xml.apache.org skin
+|   |       |   +---css             Cascading Stylesheets
+|   |       |   +---images          skin-specific images
+|   |       |   +---xslt            the skin stylesheets (per medium)
+|   |       |       +---fo
+|   |       |       +---html        html rendering skins
+|   |       +---jakarta-site
+|   |       +---scarab-site
+|   |       +---xml-apache-site
+|   |   +---schema                  Generic Forrest DTDs
+|   |       +---dtd
+|   |       +---relaxng
+|   |       +---entity
+|   |   +---images                  Reusable skin-agnostic images 
+|   |   +---fresh-site              A template project structure
+|   |   +---forrest-shbat           'shbat' Forrest distribution files
+|   |   +---forrestbot              Ant-based Forrest deployment tool
+|   |   +---forrestbar              Mozilla Forrest toolbar
+|   |   +---charts                  charting trials
+|   |   +---layout                  HTML page mock-ups
+|   |   |   +---resources
+|   |   |   +---xml.apache.org
+|   |   |       +---images
+|
++---tools                           Tools used to build Forrest
+    +---ant                         Ant 1.6-dev scripts and jars
++---stylesheets                     Stylesheets used for project root XML files
+]]></source> 
+      <p>The <code>xml-forrest</code> home directory consists of the main Ant
+        build script (<code>build.xml</code>) and platform-specific batch files/shell
+        scripts to invoke it. Forrest comes with Ant included, so you do not need to
+        install Ant separately.</p> 
+      <p>Running Forrest is a batch operation you can start using the provided
+        <code>build.{sh|bat} &lt;targetname&gt;</code>. The current main targets
+        are:</p> 
+      <ul> 
+        <li><strong><code>docs</code></strong> - generates an HTML rendition of
+          the Forrest website using the default <code>forrest-site</code> skin</li> 
+        <li><strong><code>clean</code></strong> - cleans out the
+          <code>build</code> directory</li> 
+        <li><strong><code>webapp</code></strong> - for those who cannot resist
+          running Forrest live instead of its commandline invocation, this target builds
+          a WAR file you can deploy in your servlet container (currently only tested for
+          Tomcat 4.0.1). Mount-point of the web application will be
+          <code>xml-forrest</code>.</li> 
+      </ul> 
+      <p>After a build run, Forrest creates a <code>build</code> directory. You
+        can find the generated website in the <code>build/xml-forrest/docs/</code>
+        directory. Forrest also creates a <code>tools/tmp/anttasks/</code> upon its
+        first invocation. These are Centipede-specific compiled Ant tasks.</p> 
+    </section> 
+    <section>
+      <title>The Forrest DTDs</title>
+      <p>Forrest is the reference repository for the XML Apache documentation
+        DTDs. Special care is taken to provide a set of modular, extensible and
+        well-maintained DTDs for project documentation purposes. This modularity is
+        ensured using the
+        <link href="http://www.oasis-open.org/committees/entity/">OASIS catalog</link>
+        mechanism, extensive use of external parameter entities and an entity resolver
+        capable of resolving entities through the aforementioned catalog mechanism. For
+        the docheads amongst us, this means we adhere to the strict use of
+        <code>PUBLIC</code> entity identifiers both in document instances and DTD
+        modules.</p> 
+      <p>We have currently identified the following document types:</p> 
+      <ul> 
+        <li>General documents (<code>document-v11.dtd</code>),</li> 
+        <li>How-Tos (<code>howto-v10.dtd</code>),</li> 
+        <li>Collections of FAQs (<code>faq-v11.dtd)</code>.</li> 
+      </ul> 
+      <p>Some work is also under its way for other document types, in close
+        collaboration with the Cocoon project. You will also find some older document
+        types such as <code>changes</code>, <code>javadoc</code>,
+        <code>specification</code> and <code>todo</code>, which are currently under
+        consideration for automatic generation and maintenance using Gump or Centipede
+        descriptors and the like. DTDs will be subject of serious version management as
+        soon as Forrest has a 1.0 release: they are made to depend upon.</p> 
+      <p>The DTDs are located in <code>src/resources/schema/dtd</code> and also
+        refer to some character entity collections stored in the
+        <code>src/resources/schema/entity</code> directory. These are referred to by
+        the declarations found in the <code>src/resources/schema/catalog</code> OASIS
+        Catalog file. Take special care using the correct <code>PUBLIC</code>
+        identifiers in the DTD declaration of your instances:</p> 
+      <source xml:space="preserve"><![CDATA[<?xml version="1.0"?>
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://apache.org/forrest/dtd/document-v12.dtd">
+<document>
+  ...
+  ]]></source> 
+      <p>The exact local location of the DTD for validation purposes is
+        obtained by the entity resolver evaluating the mapping scheme as defined in the
+        <code>catalog</code> file. This makes sure that you can move and re-arrange
+        your document instances apart from your DTD files. Later on, the DTDs will be
+        web-accessible from the Forrest website for your perusal.</p> 
+    </section> 
+    <section id="sitemap">
+      <title>Forrest site generation using Cocoon</title>
+      <p>The <code>docs</code> target of the Forrest build environment invokes
+        Cocoon as a command-line application to generate an HTML rendition of the
+        project's documentation. It is not within the scope of this document to explain
+        the Cocoon internals, please read its own
+        <link href="http://cocoon.apache.org/">documentation</link> to fully
+        understand the power of Cocoon.</p> 
+      <p>Cocoon's site rendition behaviour is configured in a so-called
+        <em>sitemap</em>, a switchboard that binds URLs to an XML processing pipeline.
+        This pipeline typically consists of a Generator, one or more Transformers and a
+        Serializer. Forrest also makes use of Cocoon's aggregation capabilities that
+        merge multiple pipelines into one resulting output document.</p> 
+      <p>A typical page generated using Forrest looks like this:</p>
+      <figure src="images/page-areas.png" height="291" width="336" alt="Pages areas"/> 
+      <p>This page is currently composed of two XML sources which are
+        transformed by a different XSLT stylesheet, aggregated by Cocoon with a
+        post-aggregation stylesheet adding the overall page grid and look &amp; feel.
+        This simple example is handled by the following <em>sitemap</em> snippets
+        (<code>src/documentation/conf/sitemap.xmap</code>):</p> 
+      <source xml:space="preserve"><![CDATA[<map:match pattern="*.html">
+  <map:aggregate element="site">
+    <map:part src="cocoon:/book-{1}.xml"/>
+    <map:part src="cocoon:/body-{1}.xml" label="content"/>
+  </map:aggregate>
+  <map:call resource="skinit">
+    <map:parameter name="type" value="site2xhtml"/>
+  </map:call>
+</map:match>]]></source> 
+      <source xml:space="preserve"><![CDATA[<map:match pattern="**book-**.xml">
+  <map:generate src="content/xdocs/{1}book.xml"/>
+  <map:call resource="skinit">
+    <map:parameter name="type" value="book2menu"/>
+  </map:call>
+</map:match>]]></source> 
+      <source xml:space="preserve"><![CDATA[<map:match pattern="body-**.xml">
+  <map:generate src="content/xdocs/{1}.xml"/>
+  <map:call resource="skinit">
+    <map:parameter name="type" value="document2html"/>
+  </map:call>
+</map:match>]]></source> 
+      <source xml:space="preserve"><![CDATA[<map:resource name="skinit">
+  <map:transform src="skins/@skin@/xslt/html/{type}.xsl">
+    <map:parameter name="isfaq" value="{isfaq}"/>
+  </map:transform>
+  <map:serialize/>
+</map:resource>]]></source> 
+      <p>When an URL (e.g.
+        <code>http://forrest.apache.org/index.html</code>) is passed through the
+        Cocoon system to generate the required page, the pipeline flow is basically as
+        follows:</p> 
+      <ol> 
+        <li>The URL is matched by the <code>*.html</code> pattern</li> 
+        <li>Cocoon responds by aggregating two 'sub-requests'. The first is for
+          the resource <code>book-{1}.xml</code>, the second is for the resource
+          <code>body-{1}.xml</code>. The <code>{1}</code> parameter is replaced by the
+          values of the first wildcard in the matching pattern above. These
+          'sub-requests' are passed through the Cocoon pipeline just like any other
+          request. This results in the following flow:</li> 
+        <ol> 
+          <li>The first 'sub-request' (for <code>book-index.xml</code> is matched
+            by the <code>**book-**.xml</code> pattern. This results in the file
+            <code>content/xdocs/book.xml</code> being read. This document is then run
+            through the <code>book2menu</code> stylesheet (which produces an HTML fragment
+            comprising the site navigation, the red area in the image above.</li> 
+          <li>The second 'sub-request' is matched by the <code>body-**.xml</code>
+            pattern. This results in the file <code>index.xml</code> being transformed
+            using the <code>document2html</code> stylesheet, the yellow area in the
+            screenshot.</li> 
+        </ol> 
+        <li>The aggregation result is then transformed using the
+          <code>site2xhtml</code> stylesheet which adds the cherries to the cake. The
+          grey zone.</li> 
+      </ol> 
+      <p>These <em>skin-specific</em> stylesheets are located in
+        <code>src/documentation/skins/&lt;nameoftheskin&gt;/xslt/html</code>, so if you
+        want to add your own skin, this is the place to be. Apart from these, there
+        exist a number of other stylesheets located in
+        <code>src/documentation/library/xslt</code> and more importantly:</p> 
+      <ul> 
+        <li><code>faq2document</code>: transforms documents following the
+          <code>faq-v11</code> DTD to <code>document-v11</code> grammar</li> 
+        <li><code>howto2document</code>: transforms documents following the
+          <code>howto-v10</code> DTD to <code>document-v11</code> grammar</li> 
+        <li>and some others.</li> 
+      </ul> 
+      <p>As you see, all documents, regardless of their original DTD, are
+        transformed to the <code>document</code> DTD prior to rendition. This
+        alleviates the burden of adding new skins to implementing 3 simple stylesheets:
+        <code>book2menu</code>, <code>document2html</code> and
+        <code>site2xhtml</code>.</p> 
+    </section> 
+    <section>
+      <title>Where we are heading to</title>
+      <p>We have been explaining so far where we are now and what already
+        works. The purpose of this document however is to attract newcomers and entice
+        them to start contributing to Forrest. We have a decent generation system for
+        static project documentation, a nice set of skins and some simple but effective
+        DTDs. Our goals however are much more ambitious: we have compiled a
+        <link href="site:v0.80//dreams">dream list</link> that lists most of them.</p> 
+      <ul> 
+        <li>Our first ambition is to support the project site generation and
+          maintenance of other Apache projects in an automated manner, starting with our
+          own website as a showcase. We are in the process of setting up the shell
+          scripts and Ant tasks for this and will assist projects transitioning to
+          Forrest.</li> 
+        <li>As it is often the case with collaborative open source development,
+          there is no formal planning nor task assignments, and we will stick to that
+          practice. We have however compiled a number of functional work areas:</li> 
+      </ul> 
+      <table> 
+        <tr> 
+          <th colspan="1" rowspan="1">URI Namespace Management</th> 
+          <td colspan="1" rowspan="1">Forrest will offer access to a broad set of information resources
+            using durable URIs: please review
+            <link href="ext:cool-uris">Tim Berners-Lee</link>'s
+            and <link href="http://www.useit.com/alertbox/990321.html">Jakob
+              Nielsen</link>'s opinion on this. We need a unified URI Namespace management
+            approach, bearing in mind mirroring and 'hackable' URIs.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Skins</th> 
+          <td colspan="1" rowspan="1">We currently have a nice set of skins which should be solidified.
+            Furthermore, we need some serious finetuning of the <code>forrest-site</code>
+            skin that will become the new xml.apache.org look&amp;feel.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Aggregation<br/>and Syndication</th> 
+          <td colspan="1" rowspan="1">We plan to aggregate on a per-project basis a number of relevant
+            developer resources, such as project-related news, download statistics,
+            committer bio pages (with photos!), navigable source code listings and the
+            like. Some of these resources need to be made available across content
+            syndication methods such as 
+            <link href="http://blogspace.com/rss/">RSS</link>.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Build Management</th> 
+          <td colspan="1" rowspan="1">Fool-proof automation of Forrest runs and site publication using
+            secure transfer methods and <code>cron</code> jobs.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Document Types</th> 
+          <td colspan="1" rowspan="1">Expanding the collection of DTDs, documenting them using formal
+            How-Tos and example documents.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">xml.apache.org</th> 
+          <td colspan="1" rowspan="1">Formation of an editorial team for the main xml.apache.org website,
+            working in close collaboration with the
+            <link href="http://xml.apache.org/whoweare.html">PMC</link> and the different
+            sub-project leads.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Integration</th> 
+          <td colspan="1" rowspan="1"> Forrest needs to coexist with existing cross-project collaboration
+            tools such as <link href="ext:gump">Gump</link>,
+            <link href="http://scarab.tigris.org/">Scarab</link> and
+            <link href="http://eyebrowse.tigris.org/">Eyebrowse</link> and provide
+            integrated access to them.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Authoring support</th> 
+          <td colspan="1" rowspan="1">Supporting document authors with preconfigured XML editing
+            solutions.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Content Management</th> 
+          <td colspan="1" rowspan="1">Establish an efficient content management practice, supporting
+            versioning, remote access and work flow, presumably supported by a CMS such as
+            <link href="http://jakarta.apache.org/slide/">Slide</link>.</td> 
+        </tr> 
+        <tr> 
+          <th colspan="1" rowspan="1">Information Accessibility</th> 
+          <td colspan="1" rowspan="1">We need to be accessible using a wide range of browsing devices
+            operating on different platforms. Special care should be taken to support the
+            <link href="http://www.w3.org/WAI/">WAI</link> guidelines.</td> 
+        </tr> 
+      </table> 
+    </section> 
+    <section>
+      <title>Where you can help</title> 
+      <p>By now, you should have a better understanding of Forrest (if that is
+        not the case, consider contributing clarifications to this document).
+        We need more people to get the job done.
+        Forrest is a fun project to work on, and there is something in it for
+        all of us:</p> 
+      <ul> 
+        <li>XML docheads with skills for document analysis and DTDs
+          development</li> 
+        <li>Cocoon developers creating custom Cocoon components connecting
+          Forrest with external resources</li> 
+        <li>Graphical whizzkids for true cross-browser HTML/CSS
+          development</li> 
+        <li>People who believe XSLT will bring peace to earth (it will, but
+          keep that quiet)</li> 
+        <li>Ant wizards able to compete with Nicola and Stefan</li> 
+        <li>Unix shell scripting / CVS / cron gurus, preferably bearded</li> 
+      </ul> 
+      <p>Just drop us a line at 
+       the forrest-dev <link href="site:mail-lists">mail list</link>.
+      </p>
+
+    </section> 
+    <p>That is all, folks.</p> 
+    <table> 
+      <tr> 
+        <th colspan="1" rowspan="1">Revision history</th> 
+        <th colspan="1" rowspan="1"/> 
+      </tr> 
+      <tr> 
+        <td colspan="1" rowspan="1">2002-05-22</td> 
+        <td colspan="1" rowspan="1">Initial version, Steven Noels, stevenn.at.apache.org</td> 
+      </tr>
+      <tr>
+        <td colspan="1" rowspan="1">2002-05-23</td>
+        <td colspan="1" rowspan="1">Various rephrasings and clarifications thanks to Ross Gardler,
+          ross.at.saafe.org</td>
+      </tr> 
+      <tr>
+        <td colspan="1" rowspan="1">2002-09-23</td>
+        <td colspan="1" rowspan="1">Updated the directory outline (jefft.at.apache.org)</td>
+      </tr> 
+    </table> 
+  </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_80/primer.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/project-sitemap.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/project-sitemap.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/project-sitemap.source.xml (added)
+++ forrest/site/docs_0_80/project-sitemap.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  Copyright 2002-2005 The Apache Software Foundation or its licensors,
+  as applicable.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document> 
+  <header> 
+    <title>Using project sitemaps</title> 
+  </header> 
+  <body> 
+    <section id="introduction">
+      <title>Introduction</title>
+
+      <p>After Forrest 0.6 it is now possible for projects to intercept
+      the core sitemaps, without needing to copy the main sitemaps and keep
+      them synchonised. This will enable hassle-free update to
+      future Forrest versions.</p>
+
+      <note>
+        We advise you to spend time to understand the Apache Cocoon sitemap.
+        See <link href="ext:cocoon/sitemap">Cocoon sitemap</link>
+        and <link href="ext:cocoon/concepts">Cocoon concepts</link>
+        and related component documentation.
+        The Forrest sitemap is broken into multiple files. The main one is
+        <strong>sitemap.xmap</strong> which delegates to others.  See the
+         <link href="site:v0.80//sitemap-ref">Sitemap Reference</link> for a tour of the
+        default sitemap.
+      </note>
+    </section>
+
+    <section id="how">
+      <title>How does it work?</title>
+
+      <p>If a project has a <code>sitemap.xmap</code> file in it's 
+      documentation dir, that gets mounted automatically by Forrest and 
+      becomes part of the processing: it is a preprocessing step, and 
+      is the first one to handle the request. Because of this it can 
+      serve any file directly. If it does not want to 
+      serve a file, it can simply not match the URL and Forrest will take 
+      care of it as usual.</p>
+
+      <p>The cool thing is that if that pipeline serves an xml representation, 
+      Forrest will provide a skinned version of it.</p>
+
+      <p>So if the project sitemap matches test.xml and transforms that to a
+      correctly structured Forrest intermediate "document-v*",
+      then the user will see test.html fully rendered by Forrest.</p>
+
+      <p>Of course, to resolve the directories in your sitemap it is important 
+      to use the 'project:' and 'forrest:' variables to prevent any possible 
+      issue in the future.</p>
+    </section>
+
+    <section id="examples">
+      <title>Example uses of this technique</title>
+
+      <section id="download">
+        <title>Adding a new content type</title>
+        <p>
+          See the section "Advanced customizations: sitemap.xmap" in
+          the <link href="site:v0.80//your-project">Using Forrest</link> document
+          and then follow the
+          <link href="site:v0.80//your-project/new_content_type">Example:
+          Adding a new content type</link>.
+        </p>
+      </section>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_80/project-sitemap.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/searching.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/searching.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/searching.source.xml (added)
+++ forrest/site/docs_0_80/searching.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,124 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  Copyright 2002-2005 The Apache Software Foundation or its licensors,
+  as applicable.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document>
+  <header>
+    <title>Searching Forrest-built documentation</title>
+  </header>
+  <body>
+    <p>Forrest provides you with two distinct options for making your
+      documentation available through full-text search:</p>
+    <ul>
+      <li>Google SiteSearch,</li>
+      <li>Built-in search using Apache Lucene.</li>
+    </ul>
+    <p>Both options have their advantages and disadvantages. The
+      purpose of this document is to outline them, and to help you
+      make a choice. This document also tells you how to disable
+      full-text search completely, if you so choose.</p>
+    <section>
+      <title>Google SiteSearch</title>
+      <p>Forrest provides a simple interface to the Google search
+	engine. It invokes Google Advanced Search and limits the search
+	scope to the domain of your choice. Since the actual search
+	functionality is implemented on Google's end, you do not need
+	any additional capability on your Forrest server (which may
+	well be a simple static web server serving content generated
+	with <code>forrest site</code>).</p>
+      <p>To use Google SiteSearch in your Forrest application, open
+	your <code>skinconf.xml</code> file. By default this file is
+	in the <code>src/documentation</code> subdirectory of your
+	Forrest repository root. Find the <code>&lt;search&gt;</code>
+	element; it should be near the top of the file. If the element
+	does not exist, create it below the
+	<code>&lt;skinconfig&gt;</code> opening tag. If there is any
+	attribute named <code>provider</code>, remove it. The element
+	should look similar to this:</p>
+      <source xml:space="preserve"><![CDATA[<search name="MyProject"
+	domain="myproject.com"/>]]></source>
+      <p>Then, build your Forrest documentation and open it using your
+	favorite web browser. You are now invited to peruse the search
+	box (most skins render this in the top-right corner). Google's
+	search results will be displayed in a new browser window.</p>
+      <p>Needless to say, for this to work your content must be
+	accessible to Google's indexing robot. It can't be stored on a
+	server which is only locally accessible, or which requires
+	authentication. In addition, the content index is created and
+	updated at a time of Google's choosing. However, the search is fast
+	and search precision is usually excellent. So if your
+	Forrest content is placed on a busy, popular public web
+	server, Google search is probably the best choice.</p>
+    </section>
+    <section>
+      <title>Lucene search</title>
+      <p>Lucene is a high-performance, full-text search engine built
+	entirely in Java. To use Lucene-based search with your Forrest
+	documentation, you will need to run Forrest in a Java servlet
+	environment (such as Tomcat or Jetty). Lucene-based searching
+	will not work in a static site generated with the '<code>forrest
+	  site</code>' command.</p>
+      <p>In order to enable Lucene-based full-text search in your
+	Forrest application, you must first edit your
+	<code>skinconf.xml</code> file. Locate the
+	<code>&lt;search&gt;</code> element. If the element does not
+	exist, insert it right underneath the
+	<code>&lt;skinconfig&gt;</code> opening tag. Add an attribute
+	named <code>provider</code> with a value of
+	<code>lucene</code>, so that the element looks similar to
+	this:</p>
+      <source xml:space="preserve"><![CDATA[<search name="MyProject" domain="myproject.com"
+	provider="lucene"/>]]></source>
+      <p>Next, create and run your Forrest webapp. This may mean
+	simply invoking <code>forrest run</code>, or building and
+	bundling a servlet webapp (with <code>forrest webapp</code>),
+	and then deploying it to your servlet container.</p>
+      <p>You can now build a Lucene search index by pointing your web
+	browser at
+	<code>http://localhost:8888/lucene-update.html</code>. This
+	generates the search index and provides some information about
+	the index generation process.</p>
+      <note>You may have to substitute a different hostname, port, or
+	path, depending on your configuration. The path mentioned here
+	reflects Forrest's default settings when invoked as
+	<code>forrest run</code>.</note>
+      <p>Now you can utilize the full-text search box, located in the
+	top-right corner of the rendered Forrest pages. Search results
+	will be displayed in the same browser window and will look
+	remarkably similar to the rest of your Forrest documents.</p>
+      <p>Unlike with Google SiteSearch, the indexing information
+	retrieved by Lucene is stored on your own server, access to
+	which you may limit to users in your own organization.
+	Likewise, you may update or recreate the Lucene index at any
+	time and at your own discretion. So if you aren't making your
+	Forrest-built documentation publicly available, and you're
+	able to run Forrest on a Java-enabled web server, Lucene
+	search is probably right for you.</p>
+    </section>
+    <section>
+      <title>Disabling full-text search</title>
+      <p>If you are convinced your users don't need any full-text
+	search capability whatsoever, you may disallow displaying the
+	search box entirely. You may also wish to do so if you're
+	keeping Forrest-built content on a restricted server (meaning
+	you can't use Google), while at the same time not having any
+	usable servlet-capable web server at your disposal (meaning
+	you can't use Lucene, either).</p>
+      <p>To disable full-text search completely, open the
+	<code>skinconf.xml</code> file and remove (or comment out) the
+	entire <code>&lt;search&gt;</code> element.</p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_80/searching.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/sitemap-ref.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/sitemap-ref.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/sitemap-ref.source.xml (added)
+++ forrest/site/docs_0_80/sitemap-ref.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,765 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  Copyright 2002-2005 The Apache Software Foundation or its licensors,
+  as applicable.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document>
+  <header>
+    <title>Forrest Sitemap Reference</title>
+  </header>
+  <body>
+    <p>
+      Technically, Forrest can be thought of as a 
+      <link href="ext:cocoon">Cocoon</link> distribution that has been stripped down
+      and optimized for people with simple site publishing needs.  Central to
+      Cocoon, and hence Forrest, is the <strong>sitemap</strong>.  The sitemap
+      defines the site's URI space (what pages are available), and how each page
+      is constructed.  Understanding the sitemap is the key to understanding
+      Forrest.
+    </p>
+    <note>
+      We advise you to spend time to understand the Apache Cocoon sitemap.
+      See <link href="ext:cocoon/sitemap">Cocoon sitemap</link>
+      and <link href="ext:cocoon/concepts">Cocoon concepts</link>
+      and related component documentation.
+      The Forrest sitemap is broken into multiple files. The main one is
+      <strong>sitemap.xmap</strong> which delegates to others.
+    </note>
+    <p>
+      This document provides an overview of the special sitemap which
+      is used at the core of Apache Forrest.
+    </p>
+
+    <section id="getting_started">
+      <title>Getting started</title>
+      <p>
+        Forrest's sitemap comprises the $FORREST_HOME/main/webapp/*.xmap files.
+      </p>
+
+      <p>
+        You can add pre-processing sitemaps to your project
+        <code>src/documentation</code> directory (or wherever
+        <code>${project.sitemap-dir}</code> points to). Any match that
+        is not handled, passes through to be handled by the default Forrest
+        sitemaps - obviously extremely powerful. The capability is described
+        in 
+        "<link href="site:v0.80//project-sitemap">Using project sitemaps</link>".
+      </p>
+
+      <p>
+        Another way to experiment with the sitemap is to do '<code>forrest
+        run</code>' on a Forrest-using site.  Changes to the core
+        <code>*.xmap</code> files will now be immediately visible
+        at <code>&gt;http://localhost:8888/</code>
+      </p>
+    </section>
+
+    <section id="overview">
+      <title>Sitemap Overview</title>
+      <p>
+        Forrest's sitemap is divided both physically and logically.  The most
+        obvious is the physical separation.  There are a number of separate
+        *.xmap files, each defining pipelines for a functional area.  Each *.xmap
+        file has its purpose documented in comments at the top.  Here is a brief
+        overview of the files, in order of importance.
+      </p>
+      <table>
+        <tr>
+          <th colspan="1" rowspan="1"><strong>sitemap.xmap</strong></th>
+          <td colspan="1" rowspan="1">Primary sitemap file, which delegates responsibility for serving
+            certain URIs to the others (technically called sub-sitemaps).  More
+            about the structure of this file later.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">forrest.xmap</th>
+          <td colspan="1" rowspan="1">Sitemap defining Source pipelines, which generate the body section
+            of Forrest pages. All pipelines here deliver XML in Forrest's
+            intermediate "document-v13" format, regardless of originating source
+            or format.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">menu.xmap</th>
+          <td colspan="1" rowspan="1">Pipelines defining the XML that becomes the menu.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">linkmap.xmap</th>
+          <td colspan="1" rowspan="1">Defines a mapping from abstract ("site:index") to physical
+            ("index.html") links for the current page.  See 
+            <link href="site:v0.80//linking">Menus and Linking</link> for a conceptual
+            overview, and the <link href="#linkrewriting_impl">Link
+              rewriting</link> section for technical details.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">resources.xmap</th>
+          <td colspan="1" rowspan="1">Serves "resource" files (images, CSS, Javascript).</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">raw.xmap</th>
+          <td colspan="1" rowspan="1">Serves files located in <code>src/documentation/content/xdocs</code>
+            that are not to be modified by Forrest.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">aggregate.xmap</th>
+          <td colspan="1" rowspan="1">Generates a single page (HTML or PDF) containing all the content
+            for the site.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">faq.xmap</th>
+          <td colspan="1" rowspan="1">Processes FAQ documents.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">status.xmap</th>
+          <td colspan="1" rowspan="1">Generates <link href="site:v0.80//changes">changes</link> and 
+          <link href="site:v0.80//todo">todo</link> pages from a single
+            <code>status.xml</code> in the project root.
+          </td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">issues.xmap</th>
+          <td colspan="1" rowspan="1">Generates a page of content from an RSS feed.  Used in Forrest to
+            generate a "current issues" list from JIRA.</td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">revisions.xmap</th>
+          <td colspan="1" rowspan="1">
+            Support for HOWTO documents that want "revisions".  Revisions are
+            XML snippets containing comments on the main XML file.  The main
+            pipeline here automatically appends a page's revisions to the
+            bottom.
+          </td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">dtd.xmap</th>
+          <td colspan="1" rowspan="1">A Source pipeline that generates XML from a DTD, using Andy
+            Clark's 
+            <link href="http://www.apache.org/~andyc/neko/doc/dtd/index.html">DTD
+              Parser</link>.  Useful for documenting DTD-based XML schemas, such
+            as <link href="site:v0.80//dtd-docs">Forrest's own DTDs</link>.
+          </td>
+        </tr>
+        <tr>
+          <th colspan="1" rowspan="1">profiler.xmap</th>
+          <td colspan="1" rowspan="1">Defines the "profiler" pipeline. allowing pipelines to be benchmarked.</td>
+        </tr>
+      </table>
+    </section>
+
+    <!--
+    <section>
+      <title>Logical structure</title>
+      <p>There are a few major groups of sitemap pipelines</p>
+      <dl>
+        <dt>Content pipelines</dt>
+        <dd>These define the body (without menu and header) for HTML pages, and all the content of PDFs.</dd>
+        <dt>Menu pileines.
+      </dl>
+    </section>
+    -->
+
+    <section id="source_pipelines">
+      <title>Source pipelines (**.xml)</title>
+      <p>
+        Most *.xmap files (forrest, aggregate, faq, status, issues, revisions,
+        dtd) define Source pipelines.  Source pipelines define the content
+        (body) XML for site pages.  The input XML format can be any format
+        (document-v13, Docbook, RSS, FAQ, Howto) and from any source (local or
+        remote).  The output format is always Forrest's intermediate "document-v13"
+        format.
+      </p>
+      <p>
+        Source pipelines always have a "<code>.xml</code>" extension.
+        Thus, 
+        <link href="index.xml">index.xml</link> gives you the XML source for the
+        index page.  Likewise, <link href="faq.xml">faq.xml</link> gives you XML
+        for the FAQ (transformed from FAQ syntax), and 
+        <link href="changes.xml">changes.xml</link> returns XML from the status.xml file.
+        Take any page, and replace its extension (<code>.html</code> or
+        <code>.pdf</code>) with <code>.xml</code> and you'll have the Source
+        XML.
+      </p>
+      <p>
+        This is quite powerful, because we now have an abstraction layer, or
+        "virtual filesystem", on which the rest of Forrest's sitemap can build.
+        Subsequent layers don't need to care whether the XML was obtained
+        locally or remotely, or from what format.  Wikis, RSS, FAQs and Docbook
+        files are all processed identically from here on.
+      </p>
+      <source xml:space="preserve">
+                   (subsequent Forrest pipelines)
+                                 |
+--------+------------------------^------------------------------------------
+        |          STANDARD FORREST FORMAT (current document-v13)
+        +-----^-------^--------^------------^------^-----^-----^------^-----
+SOURCE        |       |        |            |      |     |     |      |
+FORMATS    doc-v11  doc-v13  doc-v20 ... Docbook  FAQ  Howto  Wiki  RSS  ??
+(*.xml)
+                        (in forrest.xmap, faq.xmap, etc)
+      </source>
+      <section id="forrest_xmap">
+        <title>forrest.xmap</title>
+        <p>
+          Most of the usual Source pipelines are defined in
+          <code>forrest.xmap</code> which is the default (fallback) handler for
+          <code>**.xml</code> pages. The forrest.xmap uses the 
+          <link href="site:v0.80//cap">SourceTypeAction</link> to determine the type of XML
+          it is processing, and converts it to document-v13 if necessary.
+        </p>
+        <p>For instance, say we are rendering <link href="site:v0.80//write-howto">a
+            Howto document</link> called "howto-howto.xml".  It contains this DOCTYPE
+          declaration:</p>
+        <source xml:space="preserve">
+&lt;!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.3//EN"
+  "http://forrest.apache.org/dtd/howto-v13.dtd"&gt;</source>
+        <p>The SourceTypeAction sees this, and applies this transform to get it
+          to document-v13:</p>
+        <source xml:space="preserve"><![CDATA[
+          <map:when test="howto-v13">
+            <map:transform src="{forrest:stylesheets}/howto2document.xsl" />
+          </map:when>
+          ]]></source>
+          <!--
+    if we link to an intermediate .xml file, the CLI crawler tries
+    to fetch the @hrefs from it but they still have site: in them 
+    which causes it to break
+    
+        <p>
+          The intermediate result is visible at the URL 
+          <link href="../howto/howto-howto.xml">howtos/howto-howto.xml</link>.
+        </p>
+    -->
+      </section>
+      <section id="other_source">
+        <title>Other source pipelines</title>
+        <p>As mentioned above, all non-core Source pipelines are distributed in
+          independent <code>*.xmap</code> files.  There is a block of
+          <code>sitemap.xmap</code> which simply delegates certain requests to
+          these subsitemaps:</p>
+        <source xml:space="preserve"><![CDATA[
+      <!-- Body content -->
+      <map:match pattern="**.xml">
+        <map:match pattern="changes.xml">
+          <map:mount uri-prefix="" src="status.xmap" check-reload="yes" />
+        </map:match>
+
+        <map:match pattern="todo.xml">
+          <map:mount uri-prefix="" src="status.xmap" check-reload="yes" />
+        </map:match>
+
+        <map:match pattern="**dtdx.xml">
+          <map:mount uri-prefix="" src="dtd.xmap" check-reload="yes" />
+        </map:match>
+
+        <map:match pattern="forrest-issues.xml">
+          <map:mount uri-prefix="" src="issues.xmap" check-reload="yes" />
+        </map:match>
+
+        <map:match pattern="**faq.xml">
+          <map:mount uri-prefix="" src="faq.xmap" check-reload="yes" />
+        </map:match>
+
+        <map:match pattern="site.xml">
+          <map:mount uri-prefix="" src="aggregate.xmap" check-reload="yes" />
+        </map:match>
+        ....
+        ....]]></source>
+        <section id="late_binding_pipelines">
+          <title>Late-binding pipelines</title>
+          <p>
+            One point of interest here is that the sub-sitemap is often not
+            specific about which URLs it handles, and relies on the caller (the
+            section listed above) to only pass relevant requests to it.  We term
+            this "binding a URL" to a pipeline.</p>
+          <p>For instance, the main pipeline in <code>faq.xmap</code> matches
+            <code>**.xml</code>, but only <code>**faq.xml</code> requests are
+            sent to it.</p>
+          <p>This "late binding" is useful, because the whole URL space is
+            managed in <code>sitemap.xmap</code> and not spread over lots of
+            *.xmap files.  For instance, say you wish all <code>*.xml</code>
+            inside a "<code>faq/</code>" directory to be processed as FAQs.  Just
+            override <code>sitemap.xmap</code> and redefine the relevant source
+            matcher:</p>
+          <source xml:space="preserve"><![CDATA[
+        <map:match pattern="**faq.xml">
+          <map:mount uri-prefix="" src="faq.xmap" check-reload="yes" />
+        </map:match>]]></source>
+        </section>
+      </section>
+    </section>
+
+    <section id="output_pipelines">
+      <title>Output pipelines</title>
+      <p>
+        To recap, we now have a <code>*.xml</code> pipeline defined for each
+        page in the site, emitting standardized XML.  These pipeline definitions
+        are located in various *.xmap files, notably forrest.xmap
+      </p>
+      <p>
+        We now wish to render the XML from these pipelines to output formats
+        like HTML and PDF.
+      </p>
+      <section id="pdf">
+        <title>PDF output</title>
+        <p>
+          Easiest case first; PDFs don't require menus or headers, so we can
+          simply transform our intermediate format into XSL:FO, and from there
+          to PDF.  This is done by the following matcher in
+          <code>sitemap.xmap</code> ...
+        </p>
+        <source xml:space="preserve"><![CDATA[
+1   <map:match type="regexp" pattern="^(.*?)([^/]*).pdf$">
+2     <map:generate src="cocoon:/{1}{2}.xml"/>
+3     <map:transform type="xinclude"/>
+4     <map:transform type="]]>linkrewriter<![CDATA[" src="cocoon://{1}linkmap-{2}.pdf"/>
+5     <map:transform src="skins/{forrest:skin}/xslt/fo/document2fo.xsl">
+6       <map:parameter name="ctxbasedir" value="{realpath:.}/"/>
+7       <map:parameter name="xmlbasedir" value="content/xdocs/{1}"/>
+8     </map:transform>
+9     <map:serialize type="fo2pdf"/>
+10  </map:match>
+        ]]></source>
+        <ol>
+          <li>The first line uses a matching regexp to break the URL into
+            directory <code>(.*?)</code> and filename
+            <code>([^/]*)</code> parts.</li>
+          <li>We then generate XML from a <link href="#source_pipelines">Source
+              pipeline</link>, with the URL <code>cocoon:/{1}{2}.xml</code></li>
+          <li>We then expand any XInclude statements..</li>
+          <li>and <link href="#linkrewriting_impl">rewrite links</link>..</li>
+          <li>and finally apply the document2fo.xsl stylesheet, to generate
+            XSL:FO XML.</li>
+        </ol>
+        <p>Lastly, we generate a PDF using the fo2pdf serializer.</p>
+      </section>
+      <section id="html">
+        <title>HTML output</title>
+        <p>Generating HTML pages is more complicated, because we have to merge
+          the page body with a menu and tabs, and then add a header and footer.
+          Here is the <code>*.html</code> matcher in
+          <code>sitemap.xmap</code> ...</p>
+        <source xml:space="preserve">
+          &lt;map:match pattern="*.html"&gt;
+            &lt;map:aggregate element="site"&gt;
+            &lt;map:part src="<link href="#tab_pipeline">cocoon:/tab-{0}</link>"/&gt;
+            &lt;map:part src="<link href="#menu_pipeline">cocoon:/menu-{0}</link>"/&gt;
+            &lt;map:part src="<link href="#body_pipeline">cocoon:/body-{0}</link>"/&gt;
+            &lt;/map:aggregate&gt;
+            &lt;map:call resource="skinit"&gt;
+              &lt;map:parameter name="type" value="site2xhtml"/&gt;
+              &lt;map:parameter name="path" value="{0}"/&gt;
+            &lt;/map:call&gt;
+          &lt;/map:match&gt;
+        </source>
+        <p>
+          So <link href="index.html">index.html</link> is formed from
+          aggregating <link href="body-index.html">body-index.html</link> and
+          <link href="menu-index.html">menu-index.html</link> and 
+          <link href="tab-index.html">tab-index.html</link> and then applying the
+          <code>site2xhtml.xsl</code> stylesheet to the result.
+        </p>
+        <p>
+          There is a nearly identical matcher for HTML files in subdirectories:
+        </p>
+        <source xml:space="preserve">
+          &lt;map:match pattern="**/*.html"&gt;
+            &lt;map:aggregate element="site"&gt;
+            &lt;map:part src="<link href="#tab_pipeline">cocoon:/{1}/tab-{2}.html</link>"/&gt;
+            &lt;map:part src="<link href="#menu_pipeline">cocoon:/{1}/menu-{2}.html</link>"/&gt;
+            &lt;map:part src="<link href="#body_pipeline">cocoon:/{1}/body-{2}.html</link>"/&gt;
+            &lt;/map:aggregate&gt;
+            &lt;map:call resource="skinit"&gt;
+              &lt;map:parameter name="type"
+                value="site2xhtml"/&gt;
+              &lt;map:parameter name="path"
+                value="{0}"/&gt;
+            &lt;/map:call&gt;
+          &lt;/map:match&gt;
+        </source>
+      </section>
+    </section>
+    <section id="intermediate_pipelines">
+      <title>Intermediate pipelines</title>
+      <section id="body_pipeline">
+        <title>Page body</title>
+        <p>Here is the matcher which generates the page body:</p>
+        <source xml:space="preserve"><![CDATA[
+1   <map:match pattern="**body-*.html">
+2     <map:generate src="cocoon:/{1}{2}.xml"/>
+3     <map:transform type="idgen"/>
+4     <map:transform type="xinclude"/>
+5     <map:transform type="]]>linkrewriter<![CDATA[" src="cocoon:/{1}linkmap-{2}.html"/>
+6     <map:call resource="skinit">
+7       <map:parameter name="type" value="document2html"/>
+8       <map:parameter name="path" value="{1}{2}.html"/>
+9       <map:parameter name="notoc" value="false"/>
+10    </map:call>
+11  </map:match>
+          ]]></source>
+        <ol>
+          <li>In our matcher pattern, {1} will be the directory (if any) and {2}
+            will be the filename.</li>
+          <li>First, we obtain XML content from a source pipeline</li>
+          <li>
+            <p>We then apply a custom-written
+              <code>IdGeneratorTransformer</code>, which ensures that every
+              &lt;section&gt; has an "id" attribute if one is not supplied, by generating one from the
+              &lt;title&gt; if necessary.  For example, &lt;idgen&gt; will
+              transform:</p>
+            <source xml:space="preserve">
+              &lt;section&gt;
+              &lt;title&gt;How to boil eggs&lt;/title&gt;
+              ...
+            </source>
+            <p>into:</p>
+            <source xml:space="preserve">
+              &lt;section id="How+to+boil+eggs"&gt;
+              &lt;title&gt;How to boil eggs&lt;/title&gt;
+              ...
+            </source>
+            <p>Later, the <code>document2html.xsl</code> stylesheet will create
+              an &lt;a name&gt; element for every section, allowing this section to
+              be referred to as <code>index.html#How+to+boil+eggs</code>.</p>
+          </li>
+          <li>We then expand XInclude elements.</li>
+          <li>and <link href="#linkrewriting_impl">rewrite links</link>..</li>
+          <li>and then finally apply the stylesheet that generates a fragment of
+            HTML (minus the outer elements like
+            &lt;html&gt; and &lt;body&gt;) suitable for merging with the menu and tabs.</li>
+        </ol>
+      </section>
+      <section id="menu_pipeline">
+        <title>Page menu</title>
+        <p>In the <code>sitemap.xmap</code> file, the matcher generating HTML for the menu is:</p>
+        <source xml:space="preserve"><![CDATA[
+      <map:match pattern="**menu-*.html">
+        <map:generate src="cocoon:/{1}book-{2}.html"/>
+        <map:transform type="]]>linkrewriter<![CDATA[" src="cocoon:/{1}linkmap-{2}.html"/>
+        <map:call resource="skinit">
+          <map:parameter name="type" value="book2menu"/>
+          <map:parameter name="path" value="{1}{2}.html"/>
+        </map:call>
+      </map:match>
+      ]]></source>
+        <p>We get XML from a "book" pipeline, 
+        <link href="#linkrewriting_impl">rewrite links</link>, and apply the
+          <code>book2menu.xsl</code> stylesheet to generate HTML.</p>
+        <p>How the menu XML is actually generated (the *book-*.html pipeline) is
+          sufficiently complex to require a 
+          <link href="#menu_generation_impl">section of its own</link>.</p>
+      </section>
+
+      <section id="tab_pipeline">
+        <title>Page tabs</title>
+        <p>Tab generation is quite tame compared to menus:</p>
+        <source xml:space="preserve"><![CDATA[
+     <map:match pattern="**tab-*.html">
+       <map:generate src="content/xdocs/tabs.xml" />
+       <map:transform type="]]>linkrewriter<![CDATA[" src="cocoon:/{1}linkmap-{2}.html"/>
+       <map:call resource="skinit">
+         <map:parameter name="type" value="tab2menu"/>
+         <map:parameter name="path" value="{1}{2}.html"/>
+       </map:call>
+     </map:match>
+           ]]></source>
+        <p>All the smarts are in the <code>tab2menu.xsl</code> stylesheet, which
+          needs to choose the correct tab based on the current path.  Currently,
+          a "longest matching path" algorithm is implemented.  See the
+          <code>tab2menu.xsl</code> stylesheet for details.</p>
+      </section>
+    </section>
+
+    <section id="menu_generation_impl">
+      <title>Menu XML generation</title>
+      <p>The "book" pipeline is defined in <code>sitemap.xmap</code>as:</p>
+      <source xml:space="preserve"><![CDATA[
+        <map:match pattern="**book-*.html">
+          <map:mount uri-prefix="" src="menu.xmap" check-reload="yes" />
+        </map:match>
+        ]]></source>
+      <p>Meaning that it is defined in the <code>menu.xmap</code> file.  In there we find
+        the real definition, which is quite complicated, because there are three
+        supported menu systems (see <link href="site:v0.80//linking">menus and
+          linking</link>).  We will not go through the sitemap itself
+        (menu.xmap), but will instead describe the logical steps involved:</p>
+      <ol>
+        <li>Take site.xml and expand hrefs so that they are all
+          root-relative.</li>
+        <li><p>Depending on the <code>forrest.menu-scheme</code> property, we
+            now apply one of the two algorithms for choosing a set of menu links
+            (described in <link href="site:v0.80//menu_generation">menu
+              generation</link>):</p>
+          <ul>
+            <li>
+              <p>
+                For "@tab" menu generation, we first ensure each site.xml node
+                has a tab attribute (inherited from a parent if necessary), and
+                then pass through nodes whose tab attribute matches that of the
+                "current" node.
+              </p>
+              <p>
+                For example, say our current page's path is
+                <code>community/howto/index.html</code>.  In
+                <code>site.xml</code> we look for the node with this
+                "<code>href</code>" and discover its "<code>tab</code>" attribute
+                value is "<code>howtos</code>".  We then prune the
+                <code>site.xml</code>-derived content to contain only nodes with
+                <code>tab="howtos"</code>.
+              </p>
+              <p>
+                All this is done with XSLT, so the sitemap snippet does not
+                reveal this complexity:
+              </p>
+              <source xml:space="preserve"><![CDATA[
+<map:transform src="resources/stylesheets/site2site-normalizetabs.xsl" />
+<map:transform src="resources/stylesheets/site2site-selectnode.xsl">
+  <map:parameter name="path" value="{1}{2}"/>
+</map:transform>
+                ]]></source>
+            </li>
+            <li>
+              <p>For "directory" menu generation, we simply use an
+                <code>XPathTransformer</code> to include only pages in the
+                current page's directory, or below:</p>
+              <source xml:space="preserve"><![CDATA[
+<map:transform type="xpath">
+  <map:parameter name="include" value="//*[@href='{1}']" />
+</map:transform>
+                ]]></source>
+              <p>
+                Here, the "<code>{1}</code>" is the directory part of the current
+                page.  So if our current page is
+                <code>community/howto/index.html</code> then "<code>{1}</code>" will
+                be <code>community/howto/</code> and the transformer will
+                include all nodes in that directory.
+              </p>
+            </li>
+          </ul>
+          <p>We now have a <code>site.xml</code> subset relevant to our current
+            page.</p>
+        </li>
+        <li>The "<code>href</code>" nodes in this are then made relative to the
+          current page.</li>
+        <li>The XML is then transformed into a legacy "<code>book.xml</code>"
+          format, for compatibility with existing stylesheets, and this XML
+          format is returned (hence the name of the matcher:
+          <code>**book-*.html</code>).</li>
+      </ol>
+    </section>
+
+    <section id="linkrewriting_impl">
+      <title>Link rewriting</title>
+      <p>In numerous places in <code>sitemap.xmap</code> you will see the
+        "linkrewriter" transformer in action.  For example:</p>
+      <source xml:space="preserve"><![CDATA[<map:transform type="linkrewriter" src="cocoon:/{1}linkmap-{2}.html"/>]]></source>
+      <p>This statement is Cocoon's linking system in action.  A full
+        description is provided in <link href="site:v0.80//linking">Menus and
+          Linking</link>.  Here we describe the implementation of linking.</p>
+      <section id="input_modules">
+        <title>Cocoon foundations: Input Modules</title>
+        <p>
+          The implementation of <code>site:</code> linking is heavily based on
+          Cocoon <link href="ext:cocoon/input-modules">Input Modules</link>, a
+          little-known but quite powerful aspect of Cocoon.  Input Modules are
+          generic Components which simply allow you to look up a value with a
+          key.  The value is generally dynamically generated, or obtained by
+          querying an underlying data source.
+        </p>
+        <p>
+          In particular, Cocoon contains an <code>XMLFileModule</code>, which
+          lets one look up the value of an XML node, by interpreting the key as
+          an XPath expression.  Cocoon also has a
+          <code>SimpleMappingMetaModule</code>, which allows the key to be
+          rewritten before it is used to look up a value.
+        </p>
+        <p>
+          The idea for putting these together to rewrite "<code>site:</code>"
+          links was described in <link href="ext:inputmoduletransformer">this
+            thread</link>. The idea is to write a Cocoon Transformer that
+          triggers on encountering &lt;link
+          href="<code>scheme:address</code>"&gt;, and interprets the
+          <code>scheme:address</code> internal URI as
+          <code>inputmodule:key</code>.  The transformer then uses the named
+          InputModule to look up the key value. The <code>scheme:address</code>
+          URI is then rewritten with the found value.  This transformer was
+          implemented as 
+          <link href="ext:linkrewritertransformer">LinkRewriterTransformer</link>,
+          currently distributed as a "block" in Cocoon 2.1
+        </p>
+      </section>
+
+      <section id="implement_rewriting">
+        <title>Implementing "<code>site:</code>" rewriting</title>
+        <p>
+          Using the above components, "<code>site:</code>" URI rewriting is
+          accomplished as follows.
+        </p>
+        <section id="cocoon_xconf">
+          <title>cocoon.xconf</title>
+          <p>First, we declare all the input modules we will be needing:</p>
+          <source xml:space="preserve"><![CDATA[
+<!-- For the site: scheme -->
+<component-instance
+  class="org.apache.cocoon.components.modules.input.XMLFileModule"
+  logger="core.modules.xml" name="linkmap"/>
+
+<!-- Links to URIs within the site -->
+<component-instance
+  class="org.apache.cocoon.components.modules.input.SimpleMappingMetaModule"
+  logger="core.modules.mapper" name="site"/>
+
+<!-- Links to external URIs, as distinct from 'site' URIs -->
+<component-instance
+  class="org.apache.cocoon.components.modules.input.SimpleMappingMetaModule"
+  logger="core.modules.mapper" name="ext"/>
+]]></source>
+          <ul>
+            <li><strong>linkmap</strong> will provide access to the contents of
+              site.xml; for example, <code>linkmap:/site/about/index/@href</code>
+              would return the value "index.html".</li>
+            <li><strong>site</strong> provides a "mask" over
+              <strong>linkmap</strong> such that <code>site:index</code> expands
+              to <code>linkmap:/site//index/@href</code>
+            </li>
+            <li><strong>ext</strong> provides another "mask" over
+              <strong>linkmap</strong>, such that <code>ext:ant</code> would
+              expand to <code>linkmap:/site/external-refs//ant/@href</code>
+            </li>
+          </ul>
+          <p>However at the moment, we have only declared the input modules.
+            They will be configured in <code>sitemap.xmap</code> as described in
+            the next section.</p>
+        </section>
+
+        <section id="sitemap">
+          <title>sitemap.xmap</title>
+          <p>
+            Now in the sitemap, we define the LinkRewriterTransformer, and
+            insert it into any pipelines which deal with user-editable XML
+            content:
+          </p>
+          <source xml:space="preserve"><![CDATA[
+....
+<!-- Rewrites links, e.g. transforming
+     href="site:index" to href="../index.html"
+-->
+<map:transformer name="linkrewriter"
+  logger="sitemap.transformer.linkrewriter"
+  src="org.apache.cocoon.transformation.LinkRewriterTransformer">
+  <link-attrs>href src</link-attrs>
+  <schemes>site ext</schemes>
+
+  <input-module name="site">
+    <input-module name="linkmap">
+      <file src="{src}" reloadable="false" />
+    </input-module>
+    <prefix>/site//</prefix>
+    <suffix>/@href</suffix>
+  </input-module>
+  <input-module name="ext">
+    <input-module name="linkmap">
+      <file src="{src}" reloadable="false" />
+    </input-module>
+    <prefix>/site/external-refs//</prefix>
+    <suffix>/@href</suffix>
+  </input-module>
+</map:transformer>
+....
+....
+<map:match pattern="**body-*.html">
+  <map:generate src="cocoon:/{1}{2}.xml"/>
+  <map:transform type="idgen"/>
+  <map:transform type="xinclude"/>
+  <map:transform type="linkrewriter" src="cocoon:/{1}linkmap-{2}.html"/>
+  ...
+</map:match>]]></source>
+          <p>As you can see, our three input modules are configured as part of
+            the LinkRewriterTransformer's configuration.</p>
+          <ul>
+            <li>
+              <p>Most deeply nested, we have:</p>
+              <source xml:space="preserve"><![CDATA[
+                <input-module name="linkmap">
+                  <file src="{src}" reloadable="false" />
+              </input-module>]]></source>
+              <p>The "<code>{src}</code>" text is expanded to the value of the
+                "<code>src</code>" attribute in the "<code>linkrewriter</code>"
+                instance, namely "<code>cocoon:/{1}linkmap-{2}.html</code>"
+                Thus the <code>linkmap</code> module reads dynamically
+                generated XML specific to the current request.</p>
+            </li>
+            <li>
+              <p>One level out, we configure the "<code>site</code>" and
+                "<code>ext</code>" input modules, to map onto our dynamically
+                configured "<code>linkmap</code>" module.</p>
+            </li>
+            <li>
+              <p>Then at the outermost level, we configure the
+                "<code>linkrewriter</code>" transformer.  First we tell it which
+                attributes to consider rewriting:</p>
+              <source xml:space="preserve"><![CDATA[
+                <link-attrs>href src</link-attrs>
+                <schemes>site ext</schemes>]]></source>
+              <p>So, "<code>href</code>" and "<code>src</code>" attributes starting
+                with "<code>site:</code>" or "<code>ext:</code>" are rewritten.</p>
+
+              <p>By nesting the "<code>site</code>" and "<code>ext</code>" input
+                modules in the "<code>linkrewriter</code>" configuration, we tell
+                "<code>linkrewriter</code>" to use these two input modules when
+                rewriting links.</p>
+            </li>
+          </ul>
+
+          <p>
+            The end result is that, for example, the source XML for the
+            <code>community/body-index.html</code> page has its links rewritten
+            by an XMLFileModule reading XML from
+            <code>cocoon:/community/linkmap-index.html</code>
+          </p>
+        </section>
+        <section id="dynamic_linkmap">
+          <title>Dynamically generating a linkmap</title>
+          <p>
+            Why do we need this "linkmap" pipeline generating dynamic XML from
+            site.xml, instead of just using site.xml directly?  The reasons are described
+            in <link href="ext:linkmaps">the linkmap RT</link>: we need to
+            concatenate @hrefs and add dot-dots to the paths, depending on which
+            directory the linkee is in.  This is done with the following
+            pipelines in <code>linkmap.xmap</code> ...
+          </p>
+          <source xml:space="preserve"><![CDATA[
+<!-- site.xml with @href's appended to be context-relative. -->
+<map:match pattern="abs-linkmap">
+  <map:generate src="content/xdocs/site.xml" />
+  <map:transform src="resources/stylesheets/absolutize-linkmap.xsl" />
+  <map:serialize type="xml" />
+</map:match>
+
+<!-- Linkmap for regular pages -->
+<map:match pattern="**linkmap-*">
+  <map:generate src="cocoon://abs-linkmap" />
+  <map:transform src="resources/stylesheets/relativize-linkmap.xsl">
+    <map:parameter name="path" value="{1}{2}" />
+    <map:parameter name="site-root" value="{conf:project-url}" />
+  </map:transform>
+  <map:serialize type="xml" />
+</map:match>
+            ]]></source>
+          <p>You can try these URIs out directly on a live Forrest to see what
+            is going on (for example, Forrest's own 
+            <link href="../abs-linkmap">abs-linkmap</link>).
+          </p>
+        </section>
+      </section>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_80/sitemap-ref.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/skin-package.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/skin-package.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/skin-package.source.xml (added)
+++ forrest/site/docs_0_80/skin-package.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  Copyright 2002-2005 The Apache Software Foundation or its licensors,
+  as applicable.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+--><!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document>
+  <header>
+    <title>Skin packaging, provision, and use</title>
+    <subtitle>Automated distributed skin packages</subtitle>
+  </header>
+
+  <body>
+    <section id="overview">
+      <title>Overview</title>
+      <p>
+Skins are standard zip archives with a *.zip extension.
+This enables them to be unpacked and installed automatically.
+      </p>
+
+      <p>
+To publish a skin:
+      </p>
+
+<source xml:space="preserve">
+1 - forrest package-skin
+The skin package will be made in the skin dir, next to the custom skin.
+2 - place the file in a directory on a web server
+3 - ask forrest-dev to add the url and the skin name to the list of skins
+</source>
+
+
+      <p>
+To use a custom skin with automatic download:
+      </p>
+
+<source xml:space="preserve">
+1 - set the skin property in forrest.properties to the name of the skin
+2 - forrest install-skin
+3 - forrest
+</source>
+
+      <p>
+Currently there are two test skins: "testskin" and "testskin2"
+      </p>
+
+      <p>
+To see the names of the remote skins:
+      </p>
+
+<source xml:space="preserve">forrest available-skins</source>
+    </section>
+
+    <section id="notes">
+      <title>Notes</title>
+      <p>
+The skin will get blown away by the next 'build clean' in forrest.
+But that is okay because it is so quick to go get another copy. Also it
+may be preferable to get a fresh copy. If the user wanted to keep
+the skin and perhaps enhance it, then they can copy it to their project.
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_80/skin-package.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/skins.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/skins.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/skins.source.xml (added)
+++ forrest/site/docs_0_80/skins.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,125 @@
+<?xml version="1.0" encoding="ISO-8859-1"?><!--
+  Copyright 2002-2005 The Apache Software Foundation or its licensors,
+  as applicable.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+--><document>
+  <header>
+    <title>Default skins</title>
+  </header>
+  <body>
+    <section id="introduction">
+      <title>Introduction</title>
+      <p>
+        Forrest supplies a collection of default skins which are configurable
+        and so should meet the needs of most projects. The aim is to provide
+        many capabilities so that extra skins are not needed.
+      </p>
+    </section>
+
+    <section id="names">
+      <title>Convention for choosing skin names</title>
+      <p>
+        The skin names are based on playing with the word "skin". See our
+        technique for
+        <link href="http://svn.apache.org/repos/asf/forrest/trunk/main/webapp/skins/new-skin-names.txt">choosing skin names</link>.
+        A name with "-dev" extension signifies that it is under development.
+        There is no concept of versions of default skins.
+        New skins have new names.
+      </p>
+    </section>
+
+    <section id="skins">
+      <title>Skin descriptions and examples</title>
+
+      <section id="pelt">
+        <title>pelt</title>
+        <p>
+          Uses CSS "div" and no HTML tables.
+        </p>
+        <p>Examples:
+          <link href="site:forrest">Apache Forrest</link> |
+          <link href="ext:lenya">Apache Lenya</link>
+        </p>
+      </section>
+
+      <section id="view">
+        <title>view/viewHelper</title>
+        <p>
+          This is the evolution of the "leather-dev" skin, to have contracts. 
+          It allows the user to provide their own implementations of contracts.
+          The view is controlled by a config file that is easy to understand.
+          It is still in development. Note: you need to have both plugins installed.
+        </p>
+
+        <p>Examples:
+          <link href="images/snapshot-view-viewHelper.png">snapshot</link>
+        </p>
+      </section>
+  
+      <section id="tigris">
+        <title>tigris</title>
+        <p>
+          This skin is based on version 1.1 of the 
+          <link href="http://style.tigris.org/">style.tigris.org</link> project.
+          (It deliberately contravenes our skin naming convention.)
+        </p>
+        <p>Examples:
+          <link href="http://www.core.gen.tr/">Core Computer Security Group</link>
+        </p>
+      </section>
+
+      <section id="plain-dev">
+        <title>plain-dev</title>
+        <p>
+          This is a very minimal skin to produce plain HTML documents.
+          Such capability might be useful to generate a collection of
+          documents for some off-line product's user help system.
+        </p>
+
+        <p>Examples:
+          <link href="images/snapshot-plain-dev.png">snapshot</link>
+        </p>
+      </section>
+    </section>
+
+    <section id="old">
+      <title>Old and deprecated skins</title>
+      <p>
+        The following skins are retained for a little while longer, but are
+        deprecated, so please move to one of the other skins.
+      </p>
+
+      <section id="forrest-site">
+        <title>forrest-site</title>
+        <p>
+          This is the old skin that we have been dragging around since early
+          days. Uses HTML tables.
+        </p>
+        <p>Examples:
+          <link href="ext:xml.apache.org">Apache XML</link>
+        </p>
+      </section>
+
+      <section id="krysalis-site">
+        <title>krysalis-site</title>
+        <p>
+          Uses HTML tables.
+        </p>
+
+        <p>Examples:
+        </p>
+      </section>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_80/skins.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message