[prev in list] [next in list] [prev in thread] [next in thread] 

List:       xml-cocoon-docs
Subject:    [how-to] trial run Forrest transition
From:       Diana Shannon <shannon () apache ! org>
Date:       2002-11-20 17:19:34
[Download RAW message or body]

I'm ready to pass the baton.

Once the files are added to the Forrest-CVS, this How-To (included as 
text below) should work. Otherwise, grab the source files attached to my 
recent Forrest email
   http://marc.theaimsgroup.com/?l=forrest-dev&m=103781261716893&w=2
and follow the additional instructions (as to location of the files 
within Forrest).

I still have some problems with broken links, etc. I've only tested this 
against the Cocoon release branch. I used a version of Forrest cvs from 
several days ago, so, something may have changed in the meantime.

I'll add the How-To to wiki.

Thanks for your patience.

Diana



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.

o--------------------------o

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.

o--------------------------o

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.

o--------------------------o

Prerequisites
You will find it helpful to read the
- Forrest Primer (http://xml.apache.org/forrest/primer.html) and
- Using Forrest Tutorial (http://xml.apache.org/forrest/your-
project.html)
to orient yourself with all the capabilities of Forrest.

o--------------------------o

Steps

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

1. Set up Forrest for doc generation capabilities
   a. Check out latest version of Forrest.

   b. Run ./build.[sh|bat]

   c. Add $FORREST_HOME to your environment (points to 
<path_to_forrest_cvs>xml-forrest-cvs/build/dist/shbat)

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

o--------------------------o

2. Setup Cocoon
   a. Update your cvs to latest version of 2.0.4-dev (ran out of time to 
test HEAD)

   b. You may want to add $COCOON_HOME (<path_to_xml_cocoon2>) to your 
environment for the purposes of this How-To)

   c. Clean out your build directory: ./build.[sh|bat] clean

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

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


   e. Edit Cocooon's build.xml as follows:
   -- Add to the top:
   <!DOCTYPE project [
     <!ENTITY forrest-targets SYSTEM "file:./forrest-targets.ent">
   ]>

   -- Before the closing '</project>' added:

   &forrest-targets;

o--------------------------o

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

You do this by:

cd $COCOON_HOME

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

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

o--------------------------o

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

./build.[sh|bat] site-F
./build.[sh|bat] webapp-F
./build.[sh|bat] 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 webb
   $COCOON_HOME/build/site
   $COCOON_HOME/build/webapp

Make sure to check for informative broken links messages in
   $COCOON_HOME/tmp/brokenlinks.txt

o--------------------------o

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.


o--------------------------o

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

sitemap.xml edits
a. Modified Forrest's source sitemap.xmap (found in 
<forrest_cvs>src/resources/conf/sitemap.xmap)
b. Added matches for docs todo and changes files
c. Modified <map:match pattern="body-doclist.xml"> to include Cocoon's 
doclist
d. 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.
e. 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 bug level to INFO
- had to uncomment some default settings, for example 
project.content-dir (even though I didn't change it)

o--------------------------o

Todo

- Need target to provide jar info/docs
- Need to test against HEAD
- Need to fix remaining broken links

o--------------------------o

Feedback
Please edit this How-To as necessary. More importantly, please edit the 
transition files!


[prev in list] [next in list] [prev in thread] [next in thread]