Note: Some parts of this document are not relevant anymore since Cocoon has its docs built by Forrest. The problem areas are now the generation of the docs via the webapp.

Overview
What follows is what I hope to be a minimally invasive (to the Cocoon CVS) way for the Cocoon project to begin a Forrest-Transition trial run of its documentation. All in-process configuration files (that will eventually need to live in the Cocoon CVS) are stored in the Forrest cvs at src/resources/convert/cocoon. All CVS doc files, transformed during this trial run, are stored in Cocoon's build directory.

NOTE: These support files were recently removed from Forrest CVS (2002-06-23). If anyone wants to resurrect this transition then get the stuff from the CVS Attic and enhance it.

Audience
This How-To is directed at:

Purpose
Following this How-To will save you time getting the Forrestized Cocoon up and running. It will also help you understand how to patch any transition-related files for the benefit of all others participating.

Prerequisites
Orient yourself with all the capabilities of Apache Forrest

Steps
Note: This was tested with Cocoon 2.04-dev cvs.

1. Set up Forrest for doc generation capabilities.

  cp $FORREST_HOME/../../../src/resources/convert/cocoon/forrest.build.xml $FORREST_HOME/forrest.build.xml
  cp $FORREST_HOME/../../../src/resources/convert/cocoon/forrest.antproxy.xml $FORREST_HOME/forrest.antproxy.xml

2. Setup Cocoon

  cp $FORREST_HOME/../../../src/resources/convert/cocoon/forrest.properties $COCOON_HOME/forrest.properties
  cp $FORREST_HOME/../../../src/resources/convert/cocoon/forrest-targets.ent $COCOON_HOME/forrest-targets.ent

  cp $FORREST_HOME/../../../src/resources/convert/cocoon/status.xml $COCOON_HOME/status.xml 
  cp $FORREST_HOME/../../../src/resources/convert/cocoon/status-docs.xml $COCOON_HOME/status-docs.xml 

  <!DOCTYPE project [
    <!ENTITY forrest-targets SYSTEM "file:./forrest-targets.ent">
  ]>

  &forrest-targets;

3. Prepare for Transition
In order to utilize Forrest build targets, you need to prepare a set of files in Cocoon's build directory. This next step invokes a build target which

You do this by:

cd $COCOON_HOME
./build.[sh|bat] trial-run-F

You will find the results of this preparation here:

4. Build other targets
Now you're ready to use the full power of Forrest. Type any of the following:

./build.sh site-F
./build.sh webapp-F
./build.sh validate-F

Note: I had to add "-F" to these targets so that they didn't conflict with Cocoon's existing build targets.

You will find the results for site and web:

Make sure to check for informative broken links messages in:

5. Making Changes
So that we can all share in the work related to the transition, please submit all proposed changes as patches to Forrest. This preserves the integrity of the Cocoon cvs until a Transition is officially voted in on cocoon-dev.

Notes on files edited
(found in <forrest_cvs>/src/resources/convert/cocoon/)

Todo

Feedback
Please edit this How-To as necessary. More importantly, please patch the transition files in xml-forrest/src/resources/convert/cocoon.

See also

HowToForrestTransition (last edited 2009-09-20 23:42:08 by localhost)