The Forrest Primer

Return-Path: Delivered-To: apmail-xml-forrest-dev-archive@xml.apache.org Received: (qmail 88079 invoked by uid 500); 12 Nov 2002 12:47:50 -0000 Mailing-List: contact forrest-cvs-help@xml.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: list-post: Reply-To: forrest-dev@xml.apache.org Delivered-To: mailing list forrest-cvs@xml.apache.org Received: (qmail 88053 invoked from network); 12 Nov 2002 12:47:42 -0000 Received: from icarus.apache.org (63.251.56.143) by daedalus.apache.org with SMTP; 12 Nov 2002 12:47:42 -0000 Received: (qmail 82019 invoked by uid 1352); 12 Nov 2002 12:47:39 -0000 Date: 12 Nov 2002 12:47:39 -0000 Message-ID: <20021112124739.82018.qmail@icarus.apache.org> From: jefft@apache.org To: xml-forrest-cvs@apache.org Subject: cvs commit: xml-forrest/src/documentation/content/xdocs primer.xml X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N jefft 2002/11/12 04:47:39 Modified: src/documentation/content/xdocs primer.xml Log: Reindent. Sorry.. if I don't my editor does a half job on the fly. Revision Changes Path 1.17 +140 -140 xml-forrest/src/documentation/content/xdocs/primer.xml Index: primer.xml =================================================================== RCS file: /home/cvs/xml-forrest/src/documentation/content/xdocs/primer.xml,v retrieving revision 1.16 retrieving revision 1.17 diff -u -r1.16 -r1.17 --- primer.xml 12 Nov 2002 12:36:58 -0000 1.16 +++ primer.xml 12 Nov 2002 12:47:39 -0000 1.17 @@ -4,12 +4,12 @@

The Forrest Primer Don't panic! + name="Steven Noels" email="stevenn@apache.org"/> Forrest is a so-called fledgling + href="http://www.dictionary.com/cgi-bin/dict.pl?term=fledgling">fledgling project that will have a broad impact on xml.apache.org projects. This document + href="http://xml.apache.org/">xml.apache.org 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. @@ -20,31 +20,31 @@ restructured and edited to provide an accessible entry point for new Forresteers. Please send all comments, patches and suggestions to the Forrest - developers. + developers.

History

Forrest has come into existence because of the abysmal state of the xml.apache.org 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 - Gump 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.

+ 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 + Gump 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.

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 contributors 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.

+ href="who.html">contributors 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.

What is Forrest @@ -62,20 +62,20 @@ format.

Forrest is currently based on an Ant-based project build - system called Centipede - that drives a Cocoon-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.

+ system called Centipede + that drives a Cocoon-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.

The primary mode of operations for Forrest will be as follows:

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 docs target when invoking the build script. Add a use.skin property when invoking the build script to experience Forrest skins:

build{.bat|.sh}
  -        -Duse.skin=<thenameoftheskintouse> docs

. Read our CVS crash course to get hold of the current codebase and + -Duse.skin=<thenameoftheskintouse> docs. Read our CVS crash course to get hold of the current codebase and start playing with it.

Forrest will harvest documentation and related source files from @@ -117,7 +117,7 @@ the Forrest CVS repository and become an Apache committer. The first stage towards becoming a contributor is to join the forrest dev mailing list, the second is to download - Forrest and start playing with it (see below).

Depending on your role, your potential area of interest in Forrest will vary:

Download a recent release of WinCVS (homepage is http://www.wincvs.org/);
Install it;
Start it;
Click on Admin->Preferences;
In "Enter the CVSROOT:" enter - ":pserver:anoncvs@cvs.apache.org:/home/cvspublic" (without - quotes);
In "Authentication:" choose "passwd file on the cvs server";
Click "Ok";
Click Admin->Login;
When asked for the password: answer "anoncvs" - (without quotes);
Click "Create->Checkout module";
Module name and path on the server is "xml-forrest" - (no quotes);
Choose a dir to put the source code in;
Click "Ok";
If everything goes well, messages will start to appear in the log - window;
Wait until you see "*****CVS exited normally with code - 0*****" in the log window;
The Forrest source is now on your harddrive.
Install it;
Start it;
Click on Admin->Preferences;
In "Enter the CVSROOT:" enter + ":pserver:anoncvs@cvs.apache.org:/home/cvspublic" (without + quotes);
In "Authentication:" choose "passwd file on the cvs server";
Click "Ok";
Click Admin->Login;
When asked for the password: answer "anoncvs" + (without quotes);
Click "Create->Checkout module";
Module name and path on the server is "xml-forrest" + (no quotes);
Choose a dir to put the source code in;
Click "Ok";
If everything goes well, messages will start to appear in the log + window;
Wait until you see "*****CVS exited normally with code + 0*****" in the log window;
The Forrest source is now on your harddrive.

@@ -193,11 +193,11 @@ system.

Start the shell of your choice.

Enter "

cvs -d
  -            :pserver:anoncvs@cvs.apache.org:/home/cvspublic login

+ :pserver:anoncvs@cvs.apache.org:/home/cvspublic login".

When asked for the password: answer "anoncvs".

Enter "

cvs -d
  -            :pserver:anoncvs@cvs.apache.org:/home/cvspublic -z3 checkout
  -            xml-forrest

". This will create a directory called + :pserver:anoncvs@cvs.apache.org:/home/cvspublic -z3 checkout + xml-forrest". This will create a directory called "xml-forrest" where the Forrest source will be stored.

Wait until cvs has finished.

The Forrest source is now on your harddrive.

@@ -255,7 +255,7 @@ +---tools Tools used to build Forrest +---ant Ant 1.6-dev scripts and jars +---stylesheets Stylesheets used for project root XML files - ]]> +]]>

The xml-forrest home directory consists of the main Ant build script (build.xml) and platform-specific batch files/shell scripts to invoke it. Forrest comes with Ant included, so you do not need to @@ -285,12 +285,12 @@ DTDs. Special care is taken to provide a set of modular, extensible and well-maintained DTDs for project documentation purposes. This modularity is ensured using the OASIS catalog - mechanism, extensive use of external parameter entities and an entity resolver - capable of resolving entities through the aforementioned catalog mechanism. For - the docheads amongst us, this means we adhere to the strict use of - PUBLIC entity identifiers both in document instances and DTD - modules.

+ href="http://www.oasis-open.org/committees/entity/">OASIS catalog + mechanism, extensive use of external parameter entities and an entity resolver + capable of resolving entities through the aforementioned catalog mechanism. For + the docheads amongst us, this means we adhere to the strict use of + PUBLIC entity identifiers both in document instances and DTD + modules.

We have currently identified the following document types:

General documents (document-v11.dtd),

... -]]> + ]]>

The exact local location of the DTD for validation purposes is obtained by the entity resolver evaluating the mapping scheme as defined in the catalog file. This makes sure that you can move and re-arrange @@ -328,7 +328,7 @@ project's documentation. It is not within the scope of this document to explain the Cocoon internals, please read its own documentation to fully - understand the power of Cocoon.

+ understand the power of Cocoon.

Cocoon's site rendition behaviour is configured in a so-called sitemap, a switchboard that binds URLs to an XML processing pipeline. This pipeline typically consists of a Generator, one or more Transformers and a @@ -380,20 +380,20 @@ values of the first wildcard in the matching pattern above. These 'sub-requests' are passed through the cocoon pipeline just like any other request. This results in the following flow: -

The first 'sub-request' (for book-index.xml is matched - by the **book-**.xml pattern. This results in the file - content/xdocs/book.xml being read. This document is then run - through the book2menu stylesheet (which produces an HTML fragment - comprising the site navigation, the red area in the image above.
The second 'sub-request' is matched by the body-**.xml - pattern. This results in the file index.xml being transformed - using the document2html stylesheet, the yellow area in the - screenshot.

The aggregation result is then transformed using the - site2xhtml stylesheet which adds the cherries to the cake. The - grey zone.

The first 'sub-request' (for book-index.xml is matched + by the **book-**.xml pattern. This results in the file + content/xdocs/book.xml being read. This document is then run + through the book2menu stylesheet (which produces an HTML fragment + comprising the site navigation, the red area in the image above.
The second 'sub-request' is matched by the body-**.xml + pattern. This results in the file index.xml being transformed + using the document2html stylesheet, the yellow area in the + screenshot.

The aggregation result is then transformed using the + site2xhtml stylesheet which adds the cherries to the cake. The + grey zone.

These skin-specific stylesheets are located in src/documentation/skins/<nameoftheskin>/xslt/html, so if you @@ -437,67 +437,67 @@ Forrest will offer access to a broad set of information resources using durable URIs: please review Tim Berners-Lee's - and Jakob - Nielsen's opinion on this. We need a unified URI Namespace management - approach, bearing in mind mirroring and 'hackable' URIs. - - - Skins - We currently have a nice set of skins which should be solidified. - Furthermore, we need some serious finetuning of the forrest-site - skin that will become the new xml.apache.org look&feel. - - - Aggregation
and Syndication - 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 RSS. - - - Build Management - Fool-proof automation of Forrest runs and site publication using - secure transfer methods and cron jobs. - - - Document Types - Expanding the collection of DTDs, documenting them using formal - How-Tos and example documents. - - - xml.apache.org - Formation of an editorial team for the main xml.apache.org website, - working in close collaboration with the - PMC and the different - sub-project leads. - - - Integration - Forrest needs to coexist with existing cross-project collaboration - tools such as Gump, - Scarab and - Eyebrowse and provide - integrated access to them. - - - Authoring support - Supporting document authors with preconfigured XML editing - solutions. - - - Content Management - Establish an efficient content management practice, supporting - versioning, remote access and work flow, presumably supported by a CMS such as - Slide. - - - Information Accessibility - We need to be accessible using a wide range of browsing devices - operating on different platforms. Special care should be taken to support the - WAI guidelines. - + and Jakob + Nielsen's opinion on this. We need a unified URI Namespace management + approach, bearing in mind mirroring and 'hackable' URIs. + + + Skins + We currently have a nice set of skins which should be solidified. + Furthermore, we need some serious finetuning of the forrest-site + skin that will become the new xml.apache.org look&feel. + + + Aggregation
and Syndication + 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 RSS. + + + Build Management + Fool-proof automation of Forrest runs and site publication using + secure transfer methods and cron jobs. + + + Document Types + Expanding the collection of DTDs, documenting them using formal + How-Tos and example documents. + + + xml.apache.org + Formation of an editorial team for the main xml.apache.org website, + working in close collaboration with the + PMC and the different + sub-project leads. + + + Integration + Forrest needs to coexist with existing cross-project collaboration + tools such as Gump, + Scarab and + Eyebrowse and provide + integrated access to them. + + + Authoring support + Supporting document authors with preconfigured XML editing + solutions. + + + Content Management + Establish an efficient content management practice, supporting + versioning, remote access and work flow, presumably supported by a CMS such as + Slide. + + + Information Accessibility + We need to be accessible using a wide range of browsing devices + operating on different platforms. Special care should be taken to support the + WAI guidelines. +

@@ -520,8 +520,8 @@

Unix shell scripting / CVS / cron gurus, preferably bearded

Just drop us a line at forrest-dev@xml.apache.org.

- + href="mailto:forrest-dev@xml.apache.org">forrest-dev@xml.apache.org.

That is all, folks.