forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <>
Subject Re: [CROSSPOST] Forrest.cent documentation
Date Tue, 21 May 2002 17:45:27 GMT
Steven Noels wrote:

>>From: Nicola Ken Barozzi []
> Ross, how about collaborating? I can steal from yours but maybe we can
> split the work. But I want to finish RSN ;-)

I will be glad to lend a hand. I can spend a little time this week on 
any of the empty sections in your document, then I am tied up for a week 
or so. I can assist again after that.

If you want to contact me (off list if preferred, with a 
pointer as to where you would like me to focus my efforts that would be 
good to ensure we don't duplicate work.


> </Steven>
> ------------------------------------------------------------------------
> <?xml version="1.0"?>
> <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
> <document> 
>   <header> 
>     <title>Forrest primer</title><authors><person name="Steven Noels"
>       email=""/></authors> 
>     <abstract>Forrest is a so-called
>       <link
>        href="">fledgling</link>
>       project that will have a broad impact on <link
>       href=""></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> 
>     <section title="History"> 
>       <p>Forrest has come into existence because of the abysmal state of the
>         <link href=""></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="">Gump</link> project, we
>       having a single application responsible for the management of the
> 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 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="who.html">contributors</link> as well, after a headstart by Nicola
>       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"> 
>       <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 open source developers daily depend upon: 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
>         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="">Ant</link>-based project
>       system called <link href="">Centipede</link>
>       that drives a <link href="">Cocoon</link>-based
>       document publication system. It contains a set of standard XML document type
>       declarations (DTD's) for project documentation, and different 'skins'
>       consisting of XSLT stylesheets that produce HTML renditions of XML documents
>       using these DTD's.</p> 
>       <p>The primary mode of operations for Forrest will be as follows:</p>

>       <note>This process isn't quite ready for prime time yet, but it gives you
>         an idea where we are heading at. Website generation with skins currently work,
>         try using the <code>docs</code> target when invoking the <code>build</code>
>         script. Add a <code></code> property when invoking the build
script to
>         experience Forrest skins: <code>build{.bat|.sh}
>;thenameoftheskintouse&gt;</code>. Read our <jump
>         crash course</jump> to get hold of the current codebase and start playing
>         it.</note> 
>       <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
>           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 provided 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 website are
>         maintained and published using the same mechanism.</p> 
>     </section> 
>     <section title="Forrest roles"> 
>       <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
>           project because it uses Forrest to manage its documentation.</li> 
>         <li><strong>Adaptor</strong> you want to adapt Forrest to support
>           individual project needs, presumably outside the XML Apache context, building
>           your own skins or DTD's and the like.</li> 
>         <li><strong>Contributor</strong> you are a fledgling Forresteer
>           want to contribute to the further development of it. If your contributions
>           valuable and in true community spirit, you can possibly gain commit access
>           the Forrest CVS repository and become an Apache committer.</li> 
>       </ul> 
>       <p>Depending on your role, your potential area of interest in Forrest
>         will vary:</p> 
>       <table> 
>         <tr> 
>           <th>Role</th> 
>           <th>Interests</th> 
>         </tr> 
>         <tr> 
>           <td>User</td> 
>           <td>Forrest DTD's and documentation filesystem hierarchy (Cocoon
>             sitemap)</td> 
>         </tr> 
>         <tr> 
>           <td>Adaptor</td> 
>           <td>+ skin system and build environment</td> 
>         </tr> 
>         <tr> 
>           <td>Contributor</td> 
>           <td>+ the Forrest codebase and runtime environment</td> 
>         </tr> 
>       </table> 
>     </section> 
>     <section title="Getting hold of Forrest through CVS" id="cvs"> 
>       <section title="System requirements"> 
>         <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"> 
>         <p>You have to retrieve Forrest from its CVS repository - there are no
>           binary, nor source, nor snapshot distributions yet. Some help, courtesy our
>           friends of the Cocoon project:</p> 
>       </section> 
>       <section title="Step-by-step cvs instructions for Windows"> 
>         <ol> 
>           <li>Download a recent release of WinCVS (homepage is
>             <link href=""></link>);
>         <li>Install it;</li> 
>         <li>Start it;</li> 
>         <li>Click on Admin-&gt;Preferences;</li> 
>         <li> In "Enter the CVSROOT:" enter
>           "<code></code>"
>           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"> 
>         <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
>    login</code>".</li>

>           <li>When asked for the password: answer "<code>anoncvs</code>".</li>

>           <li>Enter "<code>cvs -d
>    -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
>           "<code>cvs -z3 update -d -P</code>".</p> 
>       </section> 
>     </section> 
>     <section title="Forrest distribution">
>     </section>
>     <p>Once you retrieved Forrest from its CVS repository, you end up with a
>       filesystem hierarchy similar to this:</p>
>     <table>
>       <tr>
>         <td><img src="../../resources/images/dirlayout.png" height="735"
>           width="189" alt="Forrest directory hierarchy"/></td>
>         <td>legal<br/>rrrrr</td>
>       </tr>
>     </table>
>     <section title="dtds"> 
>     </section> 
>     <section title="the sitemap &amp; skin system"> 
>     </section> 
>     <section title="what works and doesn't"> 
>     </section> 
>     <section title="your valuable input"> 
>       <ul> 
>         <li>document analysis, DTD's</li> 
>         <li>Cocoon developer</li> 
>         <li>CSS/HTML</li> 
>         <li>XSLT coding skills</li> 
>         <li>Ant wizardry</li> 
>         <li>unix shell scripting / CVS / cron</li> 
>       </ul> 
>     </section> 
>   </body>
> </document>

View raw message