You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Nicola Ken Barozzi <ni...@apache.org> on 2002/05/21 15:20:52 UTC
[CROSSPOST] Forrest.cent documentation
Ross D. Gardler has given Centipede this nifty manual on how to use Forrest
to make project documentation.
http://www.krysalis.org/centipede/manual/howTo-documentAProject/index.html
What about moving the relevant parts to Forrest?
It's not only for Forrest, since it also works with the Maven cent.
How do you thing it's better to do?
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [CROSSPOST] Forrest.cent documentation
Posted by Ivelin Ivanov <iv...@apache.org>.
Good stuff.
I feel it won't be long before I deploy this in the office.
BTW, I know that Maven vs Cent has been discussed already.
Can I get a URL to a good thread on the subject.
Thanks,
Ivelin
----- Original Message -----
From: "Nicola Ken Barozzi" <ni...@apache.org>
To: <fo...@xml.apache.org>
Cc: <kr...@lists.sourceforge.net>
Sent: Tuesday, May 21, 2002 8:20 AM
Subject: [CROSSPOST] Forrest.cent documentation
> Ross D. Gardler has given Centipede this nifty manual on how to use
Forrest
> to make project documentation.
>
> http://www.krysalis.org/centipede/manual/howTo-documentAProject/index.html
>
> What about moving the relevant parts to Forrest?
>
> It's not only for Forrest, since it also works with the Maven cent.
>
> How do you thing it's better to do?
>
> --
> Nicola Ken Barozzi nicolaken@apache.org
> - verba volant, scripta manent -
> (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------
>
>
> _______________________________________________________________
>
> Don't miss the 2002 Sprint PCS Application Developer's Conference
> August 25-28 in Las Vegas -- http://devcon.sprintpcs.com/adp/index.cfm
>
> _______________________________________________
> Krysalis-developers mailing list
> Krysalis-developers@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/krysalis-developers
Re: [CROSSPOST] Forrest.cent documentation
Posted by Glen Stampoultzis <gs...@iprimus.com.au>.
I noticed the last link in the nav section is broken. Also, there is a typo
in the index page.
Regards,
Glen Stampoultzis (TriNexus Pty Ltd)
Fixed:+61 3 9753-6850 Mob:+61 (0)402 835 458
ICQ: 62722370 EMail: glens@apache.org
> Ross D. Gardler has given Centipede this nifty manual on how to use
Forrest
> to make project documentation.
>
> http://www.krysalis.org/centipede/manual/howTo-documentAProject/index.html
>
> What about moving the relevant parts to Forrest?
>
> It's not only for Forrest, since it also works with the Maven cent.
>
> How do you thing it's better to do?
>
> --
> Nicola Ken Barozzi nicolaken@apache.org
> - verba volant, scripta manent -
> (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------
>
>
> _______________________________________________________________
>
> Don't miss the 2002 Sprint PCS Application Developer's Conference
> August 25-28 in Las Vegas -- http://devcon.sprintpcs.com/adp/index.cfm
>
> _______________________________________________
> Krysalis-developers mailing list
> Krysalis-developers@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/krysalis-developers
>
RE: [CROSSPOST] Forrest.cent documentation
Posted by Steven Noels <st...@outerthought.org>.
Ross,
I have some slack time currently so I'll finish off what I can before
submitting it to the list (by the end of today). I'd be happy if you are
willing to review it / I'm not a native speaker so that always helps -
it's more of an intro doc however, where you are more task-oriented.
Thanks,
</Steven>
> -----Original Message-----
> From: krysalis-developers-admin@lists.sourceforge.net
> [mailto:krysalis-developers-admin@lists.sourceforge.net]On Behalf Of
> Ross Gardler
> Sent: dinsdag 21 mei 2002 19:45
> To: forrest-dev@xml.apache.org
> Cc: krysalis-developers@lists.sourceforge.net
> Subject: Re: [CROSSPOST] Forrest.cent documentation
>
>
> Steven Noels wrote:
>
> >>From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
> > 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,
> ross@saafe.org) 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.
>
> Ross
Re: [CROSSPOST] Forrest.cent documentation
Posted by Ross Gardler <ro...@wkwyw.net>.
Steven Noels wrote:
>>From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
> 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, ross@saafe.org) 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.
Ross
>
> </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="stevenn@apache.org"/></authors>
> <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>
> <section title="History">
> <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="who.html">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">
> <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 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://xml.apache.org/cocoon/">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>use.skin</code> property when invoking the build script to
> experience Forrest skins: <code>build{.bat|.sh}
> -Duse.skin=<thenameoftheskintouse></code>. Read our <jump href="cvs">CVS
> crash course</jump> to get hold of the current codebase and start playing with
> 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 or
> 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 xml.apache.org 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 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 DTD's 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>
> </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="http://www.wincvs.org/">http://www.wincvs.org/</link>); </li>
> <li>Install it;</li>
> <li>Start it;</li>
> <li>Click on Admin->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->Login;</li>
> <li> When asked for the password: answer "<code>anoncvs</code>"
> (without quotes);</li>
> <li> Click "Create->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
> :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">
> </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 & 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>
>
RE: [CROSSPOST] Forrest.cent documentation
Posted by Steven Noels <st...@outerthought.org>.
> From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
My Forrest Primer (w-i-p) consists of a portion very similar to this
(doc-v11.dtd, XML dource attached).
Ross, how about collaborating? I can steal from yours but maybe we can
split the work. But I want to finish RSN ;-)
</Steven>