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!
