xml-general-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From stev...@apache.org
Subject cvs commit: xml-site/targets/forrest primer.html
Date Thu, 23 May 2002 19:00:26 GMT
stevenn     02/05/23 12:00:26

  Modified:    targets/forrest primer.html
  Log:
  various clarifications thanks to ross@saafe.org
  
  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:forrest-dev@xml.apache.org">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=&lt;thenameoftheskintouse&gt; 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-&gt;Preferences;</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>
  +          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-&gt;Login;</li>
  +<li>Click Admin-&gt;Login;</li> 
           
   <li> When asked for the password: answer "<code>anoncvs</code>"
  -          (without quotes);</li>
  +          (without quotes);</li> 
           
  -<li> Click "Create-&gt;Checkout module";</li>
  +<li> Click "Create-&gt;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:anoncvs@cvs.apache.org:/home/cvspublic login</code>".</li>
  +            :pserver:anoncvs@cvs.apache.org:/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: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>
  +            "<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} &lt;targetname&gt;</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">&lt;?xml version="1.0"?&gt;
   &lt;!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd"&gt;
   &lt;document&gt;
     ...
  -</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 &amp; 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">&lt;map:match pattern="*.html"&gt;
     &lt;map:aggregate element="site"&gt;
  @@ -590,258 +594,277 @@
     &lt;map:call resource="skinit"&gt;
       &lt;map:parameter name="type" value="site2xhtml"/&gt;
     &lt;/map:call&gt;
  -&lt;/map:match&gt;</pre>
  +&lt;/map:match&gt;</pre> 
         
   <pre class="code">&lt;map:match pattern="**book-**.xml"&gt;
     &lt;map:generate src="content/xdocs/{1}book.xml"/&gt;
     &lt;map:call resource="skinit"&gt;
       &lt;map:parameter name="type" value="book2menu"/&gt;
     &lt;/map:call&gt;
  -&lt;/map:match&gt;</pre>
  +&lt;/map:match&gt;</pre> 
         
   <pre class="code">&lt;map:match pattern="body-**.xml"&gt;
     &lt;map:generate src="content/xdocs/{1}.xml"/&gt;
     &lt;map:call resource="skinit"&gt;
       &lt;map:parameter name="type" value="document2html"/&gt;
     &lt;/map:call&gt;
  -&lt;/map:match&gt;</pre>
  +&lt;/map:match&gt;</pre> 
         
   <pre class="code">&lt;map:resource name="skinit"&gt;
     &lt;map:transform src="skins/forrest-site/xslt/html/{type}.xsl"&gt;
       &lt;map:parameter name="isfaq" value="{isfaq}"/&gt;
     &lt;/map:transform&gt;
     &lt;map:serialize/&gt;
  -&lt;/map:resource&gt;</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>
  +&lt;/map:resource&gt;</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/&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>
  +        <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&amp;feel.</td>
  +          skin that will become the new xml.apache.org look&amp;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:forrest-dev@xml.apache.org">forrest-dev@xml.apache.org</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, stevenn@apache.org</td> 
         
   </tr>
         
   <tr>
           
  -<td colspan="1" rowspan="1">2002-05-22</td>
  -        <td colspan="1" rowspan="1">Initial version, Steven Noels, stevenn@apache.org</td>
  +<td colspan="1" rowspan="1">2002-05-23</td>
  +        <td colspan="1" rowspan="1">Various rephrasings and clarifications thanks to Ross Gardler,
  +          ross@saafe.org</td>
         
  -</tr>
  +</tr> 
       
  -</table>
  +</table> 
     
   </td>
   </tr>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: general-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: general-cvs-help@xml.apache.org


Mime
View raw message