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:

  • Cocoon committers and doc-oriented users who want to participate in the Forrest Trial Run
  • Cocoon committers who want to understand the implications of Forrest adoption on the cvs, docs, web site, etc.

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.
    • Check out latest version of Forrest.
    • Run ./build.sh
    • Add $FORREST_HOME to your environment (points to <path_to_forrest_cvs>xml-forrest-cvs/build/dist/shbat)
    • Copy Cocoon-specific build files to $FORREST_HOME
  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

  • Update your cvs to latest version of 2.0.4-dev (ran out of time to test HEAD)
  • You may want to add $COCOON_HOME (<path_to_xml_cocoon2>) to your environment for the purposes of this How-To)
  • Clean out your build directory: 'build clean'
  • Copy forrest.properties and forrest-targets.ent to $COCOON_HOME
  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
  • Copy status.xml and status-docs.xml to $COCOON_HOME
  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
  • Add to the top of Cocoon's build file:
  <!DOCTYPE project [
    <!ENTITY forrest-targets SYSTEM "file:./forrest-targets.ent">
  ]>
  • Before the closing </project> of Cocoon's build file add:
  &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

  • copies all remaining config files (tabs.xml, skinconf.xml, sitemap.xmap)
  • validates doc-v10 files
  • transforms doc-v10 to doc-v11 files
  • copies all other needed files (e.g. .txt files)

You do this by:

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

You will find the results of this preparation here:
$COCOON_HOME/build/forrest-trial-run

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:

$COCOON_HOME/build/site
$COCOON_HOME/build/webapp

Make sure to check for informative broken links messages in:

$COCOON_HOME/tmp/brokenlinks.txt

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/)

  • sitemap.xml edits
    • Modified Forrest's source sitemap.xmap (found in <forrest_cvs>src/resources/conf/sitemap.xmap)
    • Added matches for docs todo and changes files
    • Modified <map:match pattern="body-doclist.xml"> to include Cocoon's doclist
    • Provisionally added <map:parameter name="nopdf" value="true"/> to all body-**.xml type matchers to speed up static site generation (shaved six minutes off an already lengthy 30-minute build). I'm not advocating we remove them, I just found it better to make the build faster.
    • Added <map:match pattern="**.txt"> for some links to text files within docs.
  • skinconf.xml
    • Simple, obvious edits.
  • tabs.xml
    • Left as is for now. It should probably be discussed with all committers. We need proposals/examples.
  • forrest.build.xml
    • Added targets related to trial-run
    • Added a provisional hack for status-docs.xml (Doc configuration files should be as centralized/visible as those for code.)
  • forrest.antproxy.xml
    • Added trial-run target
  • forrest-targets.ent
    • Added "-F" to existing site, webapp, validate, and war targets to avoid conflicts with Cocoon's existing targets.
    • Added a trial-run-F target
  • forrest.properties
    • Edited based on location of config and transformed files (in build)
    • Increased debug level to INFO

Todo

  • Need target to provide jar info/docs
  • Need to test against HEAD
  • Need to fix broken links
  • Add any more issues to ForrestProposal

Feedback

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

See also

  • No labels