stevenn 02/05/23 12:00:26
Modified: targets/forrest primer.html
Log:
various clarifications thanks to [EMAIL PROTECTED]
Revision Changes Path
1.2 +315 -292 xml-site/targets/forrest/primer.html
Index: primer.html
===================================================================
RCS file: /home/cvs/xml-site/targets/forrest/primer.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- primer.html 23 May 2002 11:48:50 -0000 1.1
+++ primer.html 23 May 2002 19:00:25 -0000 1.2
@@ -111,38 +111,38 @@
<a href="#N10079">Forrest roles</a>
</li>
<li>
-<a href="#N100CF">Getting your local copy of Forrest through CVS</a>
+<a href="#N100D3">Getting your local copy of Forrest through CVS</a>
<ul class="minitoc">
<li>
-<a href="#N100D3">System requirements</a>
+<a href="#N100D7">System requirements</a>
</li>
<li>
-<a href="#N100E2">Getting Forrest</a>
+<a href="#N100E6">Getting Forrest</a>
</li>
<li>
-<a href="#N100E9">Step-by-step cvs instructions for Windows</a>
+<a href="#N100ED">Step-by-step cvs instructions for Windows</a>
</li>
<li>
-<a href="#N10130">Step-by-step cvs instructions for Unix</a>
+<a href="#N10134">Step-by-step cvs instructions for Unix</a>
</li>
</ul>
</li>
<li>
-<a href="#N10162">Forrest distribution</a>
+<a href="#N10166">Forrest distribution</a>
</li>
<li>
-<a href="#N101AC">The Forrest DTDs</a>
+<a href="#N101B0">The Forrest DTDs</a>
</li>
<li>
-<a href="#N101FA">Forrest site generation using Cocoon</a>
+<a href="#N101FE">Forrest site generation using Cocoon</a>
</li>
<li>
-<a href="#N10297">Where we are heading to</a>
+<a href="#N102AA">Where we are heading to</a>
</li>
<li>
-<a href="#N1035C">Where you can help</a>
+<a href="#N1036F">Where you can help</a>
</li>
-</ul>
+</ul>
<div class="frame note">
<div class="label">Note</div>
@@ -152,10 +152,10 @@
Forresteers. Please send all comments, patches and suggestions to
<a href="mailto:[EMAIL PROTECTED]">the Forrest
developers</a>.</div>
-</div>
+</div>
<a name="N10025"></a>
-<h3>History</h3>
+<h3>History</h3>
<p>Forrest has come into existence because of the abysmal state of the
<a href="http://xml.apache.org/";>xml.apache.org</a> website in
comparison
@@ -171,261 +171,266 @@
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>
+ 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 <a
href="who.html">contributors</a> 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>
-
+ development.</p>
+
<a name="N1003B"></a>
-<h3>What is Forrest</h3>
+<h3>What is Forrest</h3>
<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>
+ 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
<a href="http://jakarta.apache.org/ant/";>Ant</a>-based project build
system called <a
href="http://www.krysalis.org/centipede/";>Centipede</a>
that drives a <a href="http://xml.apache.org/cocoon/";>Cocoon</a>-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>
+ 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>
+<p>The primary mode of operations for Forrest will be as follows:</p>
<div class="frame note">
<div class="label">Note</div>
-<div class="content">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>use.skin</code> property when invoking the build
script to
- experience Forrest skins: <code>build{.bat|.sh}
+<div class="content">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>use.skin</code> property when
invoking
+ the build script to experience Forrest skins: <code>build{.bat|.sh}
-Duse.skin=<thenameoftheskintouse> docs</code>. Read our <a
href="#cvs">CVS crash course</a> to get hold of the current codebase and
start playing with it.</div>
-</div>
+</div>
-<ol>
+<ol>
<li>Forrest will harvest documentation and related source files from
- the different projects that use Forrest for their website,
presumably using
- CVS, configured by a project descriptor file. It will do so on an
automated
- basis, several times a day.</li>
-
-<li>Forrest uses Cocoon to generate an HTML rendition of each project's
- website, configured by a generic sitemap. This process will be
static, the
- result of a Forrest run is a collection of HTML documents and
related images or
- stylesheets comprising the project's website. The impact Forrest
has on the
- participating projects should be minimal, i.e. one should simply
author reliable 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>
+ 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>
+ times day.</li>
-</ol>
+</ol>
<p>The Forrest website and the overall xml.apache.org website are
- maintained and published using the same mechanism.</p>
-
+ maintained and published using the same mechanism.</p>
+
<a name="N10079"></a>
-<h3>Forrest roles</h3>
+<h3>Forrest roles</h3>
<p>Depending on your interests, your involvement with Forrest may vary,
- hence your <em>role</em>. We currently envision three different
roles:</p>
+ hence your <em>role</em>. We currently envision three different
roles:</p>
-<ul>
+<ul>
<li>
<strong>User</strong> you want or need to use Forrest for your
- project because it uses Forrest to manage its documentation.</li>
+ 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>
+ 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.</li>
+ the Forrest CVS repository and become an Apache committer. The
first stage
+ towards becoming a contributor is to join the forrest dev
+ <a href="mail-lists.html">mailing list</a>, the second is to
download
+ Forrest and start playing with it (see below).</li>
-</ul>
+</ul>
<p>Depending on your role, your potential area of interest in Forrest
- will vary:</p>
+ will vary:</p>
-<table cellspacing="1" cellpadding="4" class="table">
+<table cellspacing="1" cellpadding="4" class="table">
-<tr>
+<tr>
-<th colspan="1" rowspan="1">Role</th>
- <th colspan="1" rowspan="1">Interests</th>
+<th colspan="1" rowspan="1">Role</th>
+ <th colspan="1" rowspan="1">Interests</th>
-</tr>
+</tr>
-<tr>
+<tr>
-<td colspan="1" rowspan="1">User</td>
+<td colspan="1" rowspan="1">User</td>
<td colspan="1" rowspan="1">Forrest DTDs and documentation
filesystem hierarchy (Cocoon
- sitemap)</td>
+ sitemap)</td>
-</tr>
+</tr>
-<tr>
+<tr>
-<td colspan="1" rowspan="1">Adaptor</td>
- <td colspan="1" rowspan="1">+ skin system and build
environment</td>
+<td colspan="1" rowspan="1">Adaptor</td>
+ <td colspan="1" rowspan="1">+ skin system and build
environment</td>
-</tr>
+</tr>
-<tr>
+<tr>
-<td colspan="1" rowspan="1">Contributor</td>
- <td colspan="1" rowspan="1">+ the Forrest codebase and runtime
environment</td>
+<td colspan="1" rowspan="1">Contributor</td>
+ <td colspan="1" rowspan="1">+ the Forrest codebase and runtime
environment</td>
-</tr>
+</tr>
-</table>
+</table>
+
-
-<a name="N100CF"></a><a name="cvs"></a>
-<h3>Getting your local copy of Forrest through CVS</h3>
+<a name="N100D3"></a><a name="cvs"></a>
+<h3>Getting your local copy of Forrest through CVS</h3>
-<a name="N100D3"></a>
-<h4>System requirements</h4>
+<a name="N100D7"></a>
+<h4>System requirements</h4>
<p>Forrest requires the following systems to be already installed on
- your system:</p>
+ your system:</p>
-<ul>
+<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>
+ present. Forrest has been tested against the latest Sun 1.3
JDK.</li>
-</ul>
+</ul>
+
-
-<a name="N100E2"></a>
-<h4>Getting Forrest</h4>
+<a name="N100E6"></a>
+<h4>Getting Forrest</h4>
<p>You need to retrieve Forrest from its CVS repository - there are no
- binary, nor source, nor snapshot distributions yet. Some help with
- CVS follows (courtesy of our friends of the Cocoon project).</p>
-
+ binary, nor source, nor snapshot distributions yet. Some help with
CVS follows
+ (courtesy of our friends of the Cocoon project).</p>
+
-<a name="N100E9"></a>
-<h4>Step-by-step cvs instructions for Windows</h4>
+<a name="N100ED"></a>
+<h4>Step-by-step cvs instructions for Windows</h4>
-<ol>
+<ol>
<li>Download a recent release of WinCVS (homepage is
- <a href="http://www.wincvs.org/";>http://www.wincvs.org/</a>);
</li>
+ <a href="http://www.wincvs.org/";>http://www.wincvs.org/</a>);
</li>
-<li>Install it;</li>
+<li>Install it;</li>
-<li>Start it;</li>
+<li>Start it;</li>
-<li>Click on Admin->Preferences;</li>
+<li>Click on Admin->Preferences;</li>
<li> In "Enter the CVSROOT:" enter
"<code>:pserver:[EMAIL PROTECTED]:/home/cvspublic</code>" (without
- quotes);</li>
+ quotes);</li>
-<li>In "Authentication:" choose "passwd file on the cvs server";</li>
+<li>In "Authentication:" choose "passwd file on the cvs server";</li>
-<li>Click "Ok";</li>
+<li>Click "Ok";</li>
-<li>Click Admin->Login;</li>
+<li>Click Admin->Login;</li>
<li> When asked for the password: answer "<code>anoncvs</code>"
- (without quotes);</li>
+ (without quotes);</li>
-<li> Click "Create->Checkout module";</li>
+<li> Click "Create->Checkout module";</li>
<li>Module name and path on the server is "<code>xml-forrest</code>"
- (no quotes);</li>
+ (no quotes);</li>
-<li>Choose a dir to put the source code in;</li>
+<li>Choose a dir to put the source code in;</li>
-<li>Click "Ok";</li>
+<li>Click "Ok";</li>
<li>If everything goes well, messages will start to appear in the log
- window;</li>
+ window;</li>
<li>Wait until you see "<code>*****CVS exited normally with code
- 0*****</code>" in the log window;</li>
+ 0*****</code>" in the log window;</li>
-<li>The Forrest source is now on your harddrive.</li>
+<li>The Forrest source is now on your harddrive.</li>
-</ol>
+</ol>
+
-
-<a name="N10130"></a>
-<h4>Step-by-step cvs instructions for Unix</h4>
+<a name="N10134"></a>
+<h4>Step-by-step cvs instructions for Unix</h4>
-<ol>
+<ol>
<li>Make sure you have a CVS client package installed on your Unix
- system.</li>
+ system.</li>
-<li>Start the shell of your choice.</li>
+<li>Start the shell of your choice.</li>
<li>Enter "<code>cvs -d
- :pserver:[EMAIL PROTECTED]:/home/cvspublic login</code>".</li>
+ :pserver:[EMAIL PROTECTED]:/home/cvspublic login</code>".</li>
-<li>When asked for the password: answer "<code>anoncvs</code>".</li>
+<li>When asked for the password: answer "<code>anoncvs</code>".</li>
<li>Enter "<code>cvs -d
:pserver:[EMAIL PROTECTED]:/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>
+ "<code>xml-forrest</code>" where the Forrest source will be
stored.</li>
-<li>Wait until cvs has finished.</li>
+<li>Wait until cvs has finished.</li>
-<li>The Forrest source is now on your harddrive.</li>
+<li>The Forrest source is now on your harddrive.</li>
-</ol>
+</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>
-
-
-
-<a name="N10162"></a>
-<h3>Forrest distribution</h3>
-
-<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>
+ "<code>cvs -z3 update -d -P</code>".</p>
+
+
+
+<a name="N10166"></a>
+<h3>Forrest distribution</h3>
+
+<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>
<div class="frame warning">
<div class="label">Warning</div>
<div class="content">This is highly volatile information!</div>
-</div>
+</div>
<pre class="code">+---legal various licenses for
projects included with Forrest
+---lib jar library
@@ -465,45 +470,44 @@
| +---testcases unused
+---tools Forrest build environment (Centipede)
+---ant
- +---centipede</pre>
+ +---centipede</pre>
<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>
+ install Ant separately.</p>
<p>Running Forrest is a batch operation you can start using the provided
<code>build.{sh|bat} <targetname></code>. The current main
targets
- are:</p>
+ are:</p>
-<ul>
+<ul>
<li>
<strong><code>docs</code></strong> - generates an HTML rendition of
- the Forrest website using the default <code>forrest-site</code>
skin</li>
+ 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>
+ <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>
+ <code>xml-forrest</code>.</li>
-</ul>
+</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>
+ 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>
+
-
-<a name="N101AC"></a>
-<h3>The Forrest DTDs</h3>
+<a name="N101B0"></a>
+<h3>The Forrest DTDs</h3>
<p>Forrest is the reference repository for the XML Apache documentation
DTDs. Special care is taken to provide a set of modular, extensible
and
@@ -513,74 +517,74 @@
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>
+ modules.</p>
-<p>We have currently identified the following document types:</p>
+<p>We have currently identified the following document types:</p>
-<ul>
+<ul>
-<li>General documents (<code>document-v11.dtd</code>),</li>
+<li>General documents (<code>document-v11.dtd</code>),</li>
-<li>How-Tos (<code>howto-v10.dtd</code>),</li>
+<li>How-Tos (<code>howto-v10.dtd</code>),</li>
-<li>Collections of FAQs (<code>faq-v11.dtd)</code>.</li>
+<li>Collections of FAQs (<code>faq-v11.dtd)</code>.</li>
-</ul>
+</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>
+ 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>
+<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>
<pre class="code"><?xml version="1.0"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
...
-</pre>
+</pre>
-<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
+<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>
+ web-accessible from the Forrest website for your perusal.</p>
+
-
-<a name="N101FA"></a>
-<h3>Forrest site generation using Cocoon</h3>
+<a name="N101FE"></a>
+<h3>Forrest site generation using Cocoon</h3>
<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 the its own
<a href="http://xml.apache.org/cocoon/";>documentation</a> to fully
- understand the power of Cocoon.</p>
+ 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>
+ merge multiple pipelines into one resulting output document.</p>
<p>A typical page generated using Forrest looks like this:</p>
<div align="center">
-<img class="figure" alt="Pages areas" src="images/page-areas.png"
height="291" width="336"></div>
+<img class="figure" alt="Pages areas" src="images/page-areas.png"
height="291" width="336"></div>
-<p>As you might see, 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-and-feel.
+<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
& feel.
This simple example is handled by the following <em>sitemap</em>
snippets
- (<code>src/documentation/conf/sitemap.xmap</code>):</p>
+ (<code>src/documentation/conf/sitemap.xmap</code>):</p>
<pre class="code"><map:match pattern="*.html">
<map:aggregate element="site">
@@ -590,258 +594,277 @@
<map:call resource="skinit">
<map:parameter name="type" value="site2xhtml"/>
</map:call>
-</map:match></pre>
+</map:match></pre>
<pre class="code"><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></pre>
+</map:match></pre>
<pre class="code"><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></pre>
+</map:match></pre>
<pre class="code"><map:resource name="skinit">
<map:transform src="skins/forrest-site/xslt/html/{type}.xsl">
<map:parameter name="isfaq" value="{isfaq}"/>
</map:transform>
<map:serialize/>
-</map:resource></pre>
-
-<p>The pipeline flow basically is:</p>
-
-<ol>
-
-<li>A URL matched by the <code>*.html</code> pattern is fetched.</li>
-
-<li>The response will be the result of aggregating two
- 'sub-requests':</li>
+</map:resource></pre>
-<ol>
-
-<li>A URL matching the <code>**book-**.xml</code> pattern, which is the
- result of reading the <code>book.xml</code> document and running
that through
- the <code>book2menu</code> stylesheet (which produces an HTML
fragment
- comprising the site navigation, the red area in the image.</li>
-
-<li>A URL matching the <code>body-**.xml</code> pattern, corresponding
- to <code>*.xml</code> transformed using the
<code>document2html</code>
- stylesheet, the yellow area in the screenshot.</li>
+<p>When an URL (e.g.
+ <code>http://xml.apache.org/forrest/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
+ valuse 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>
+</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>
+ <code>site2xhtml</code> stylesheet which adds the cherries to the
cake. The
+ grey zone.</li>
-</ol>
+</ol>
<p>These <em>skin-specific</em> stylesheets are located in
<code>src/documentation/skins/<nameoftheskin>/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>
+ <code>src/documentation/library/xslt</code> and more
importantly:</p>
-<ul>
+<ul>
<li>
<code>faq2document</code>: transforms documents following the
- <code>faq-v11</code> DTD to <code>document-v11</code> grammar</li>
+ <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>
+ <code>howto-v10</code> DTD to <code>document-v11</code>
grammar</li>
-<li>and some others.</li>
+<li>and some others.</li>
-</ul>
+</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>
+ <code>site2xhtml</code>.</p>
+
-
-<a name="N10297"></a>
-<h3>Where we are heading to</h3>
+<a name="N102AA"></a>
+<h3>Where we are heading to</h3>
<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
- <a href="dreams.html">dream list</a> that lists most of them.</p>
+ <a href="dreams.html">dream list</a> that lists most of them.</p>
-<ul>
+<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>
+ 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>
+ practice. We have however compiled a number of functional work
areas:</li>
-</ul>
+</ul>
-<table cellspacing="1" cellpadding="4" class="table">
+<table cellspacing="1" cellpadding="4" class="table">
-<tr>
+<tr>
-<th colspan="1" rowspan="1">URI Namespace Management</th>
+<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
<a href="http://www.w3.org/Provider/Style/URI.html";>Tim
Berners-Lee</a>'s
and <a href="http://www.useit.com/alertbox/990321.html";>Jakob
Nielsen</a>'s opinion on this. We need a unified URI Namespace
management
- approach, bearing in mind mirroring and 'hackable' URIs.</td>
+ approach, bearing in mind mirroring and 'hackable' URIs.</td>
-</tr>
+</tr>
-<tr>
+<tr>
-<th colspan="1" rowspan="1">Skins</th>
+<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&feel.</td>
+ skin that will become the new xml.apache.org look&feel.</td>
-</tr>
+</tr>
-<tr>
+<tr>
-<th colspan="1" rowspan="1">Aggregation<br>and Syndication</th>
+<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 <a
href="http://blogspace.com/rss/";>RSS</a>.</td>
+ syndication methods such as <a
href="http://blogspace.com/rss/";>RSS</a>.</td>
-</tr>
+</tr>
-<tr>
+<tr>
-<th colspan="1" rowspan="1">Build Management</th>
+<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>
+ secure transfer methods and <code>cron</code> jobs.</td>
-</tr>
+</tr>
-<tr>
+<tr>
-<th colspan="1" rowspan="1">Document Types</th>
+<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>
+ How-Tos and example documents.</td>
-</tr>
+</tr>
-<tr>
+<tr>
-<th colspan="1" rowspan="1">xml.apache.org</th>
+<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
<a href="http://xml.apache.org/whoweare.html";>PMC</a> and the
different
- sub-project leads.</td>
+ sub-project leads.</td>
-</tr>
+</tr>
-<tr>
+<tr>
-<th colspan="1" rowspan="1">Integration</th>
+<th colspan="1" rowspan="1">Integration</th>
<td colspan="1" rowspan="1"> Forrest needs to coexist with existing
cross-project collaboration
tools such as <a href="http://jakarta.apache.org/gump/";>Gump</a>,
<a href="http://scarab.tigris.org/";>Scarab</a> and
<a href="http://eyebrowse.tigris.org/";>Eyebrowse</a> and provide
- integrated access to them.</td>
+ integrated access to them.</td>
-</tr>
+</tr>
-<tr>
+<tr>
-<th colspan="1" rowspan="1">Authoring support</th>
+<th colspan="1" rowspan="1">Authoring support</th>
<td colspan="1" rowspan="1">Supporting document authors with
preconfigured XML editing
- solutions.</td>
+ solutions.</td>
-</tr>
+</tr>
-<tr>
+<tr>
-<th colspan="1" rowspan="1">Content Management</th>
+<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
- <a href="http://jakarta.apache.org/slide/";>Slide</a>.</td>
+ <a href="http://jakarta.apache.org/slide/";>Slide</a>.</td>
-</tr>
+</tr>
-<tr>
+<tr>
-<th colspan="1" rowspan="1">Information Accessibility</th>
+<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
- <a href="http://www.w3.org/WAI/";>WAI</a> guidelines.</td>
+ <a href="http://www.w3.org/WAI/";>WAI</a> guidelines.</td>
-</tr>
+</tr>
-</table>
+</table>
+
-
-<a name="N1035C"></a>
-<h3>Where you can help</h3>
+<a name="N1036F"></a>
+<h3>Where you can help</h3>
<p>By now, you should have a better understanding of Forrest (if that is
- not the case, consider contributing to this document to start with)
- 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>
+ not the case, consider contributing to this document to start with
+ <strong><code>;-)</code></strong>) 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>
+<ul>
<li>XML docheads with skills for document analysis and DTDs
- development</li>
+ development</li>
<li>Cocoon developers creating custom Cocoon components connecting
- Forrest with external resources</li>
+ Forrest with external resources</li>
<li>Graphical whizzkids for true cross-browser HTML/CSS
- development</li>
+ development</li>
<li>People who believe XSLT will bring peace to earth (it will, but
- keep that quiet)</li>
+ keep that quiet)</li>
-<li>Ant wizards able to compete with Nicola and Stefan</li>
+<li>Ant wizards able to compete with Nicola and Stefan</li>
-<li>Unix shell scripting / CVS / cron gurus, preferably bearded</li>
+<li>Unix shell scripting / CVS / cron gurus, preferably bearded</li>
-</ul>
+</ul>
<p>Just drop us a line at <a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>.</p>
+
+
+<p>That is all, folks.</p>
-<p>That is all, folks.</p>
-
-<table cellspacing="1" cellpadding="4" class="table">
+<table cellspacing="1" cellpadding="4" class="table">
-<tr>
+<tr>
-<th colspan="1" rowspan="1">Revision history</th>
- <th colspan="1" rowspan="1"></th>
+<th colspan="1" rowspan="1">Revision history</th>
+ <th colspan="1" rowspan="1"></th>
+
+</tr>
+
+<tr>
+
+<td colspan="1" rowspan="1">2002-05-22</td>
+ <td colspan="1" rowspan="1">Initial version, Steven Noels, [EMAIL
PROTECTED]</td>
</tr>
<tr>
-<td colspan="1" rowspan="1">2002-05-22</td>
- <td colspan="1" rowspan="1">Initial version, Steven Noels, [EMAIL
PROTECTED]</td>
+<td colspan="1" rowspan="1">2002-05-23</td>
+ <td colspan="1" rowspan="1">Various rephrasings and clarifications
thanks to Ross Gardler,
+ [EMAIL PROTECTED]</td>
-</tr>
+</tr>
-</table>
+</table>
</td>
</tr>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
