$Id$

To update the FOP website:

Background
--------------
 1. The documentation is generated using forrest
    (http://xml.apache.org/forrest/).
 2. Forrest needs to be run on a machine with a graphical environment (it will
    fail in a headless environment when it tries to use FOP to generate the PDF
    files). The Apache machine available to xml-fop developers
    (icarus.apache.org) appears to be headless, so you will probably need to run
    this on a local machine with a graphical environment.

Step-by-Step Instructions
-----------------------------
 1. checkout the xml-forrest module (same repository as xml-fop).
 2. checkout the xml-site/targets/fop module (same repository as xml-fop).
 3. you will also need access to a current xml-fop sandbox (you probably already
    have one)
 4. cd to xml-forrest
 5. run: build.sh(bat) dist to build forrest
 6. set environment variable FORREST_HOME=~/xml-forrest/build/dist/shbat
    where ~ is the directory in which xml-forrest is installed
    (see http://xml.apache.org/forrest/your-project.html for details)
 7. set environment variable PATH=$PATH:$FORREST_HOME/bin
 8. cd to xml-fop directory
 9. run forrest(.bat), which will build the web-site documents in
    xml-fop/build/site.
10. NOTE: the compliance.html currently does not work, it can be fixed by
    adding the dtd ref to: build/tmp/context/resources/schema/catalog
    and placing the dtd in: build/tmp/context/resources/schema/dtd/
11. To update the actual website, copy the generated documents
    (in xml-fop/build/site) to xml-site/targets/fop. (This could also be done by
    sym-linking this destination before the build.)
12. commit xml-site/targets/fop.

Notes
---------
 1. Per information from Jeff Turner & Christian Geisert, the downstream
    process of publishing our web site is as follows:
    - Committers commit generated docs to xml-site/targets/fop
    - Every 6 hours (midnight, 6am, noon, 6pm Pacific time), a script (which is
      maintained by Sam Ruby) updates the FOP website:
      - soucre: icarus (cvs.apache.org), specifically from
        /home/cvs/xml-site/targets/fop.
      - target: daedalus (xml.apache.org)
 2. Per Jeff Turner, the contents of the FOP website (but not the web site
    itself) are being regenerated by Forrest every hour.
    This process actually checks out the contents of xml-fop/src/documentation
    from CVS and builds the web-site contents with the latest Forrest.
    This process has no relation to what is in xml-site/targets/fop.
    See http://forrestbot.cocoondev.org/site/xml-fop for the contents.
    Although we found this interesting (especially wondering how they got around
    the headless server problem), it doesn't change our workflow above, because
    we don't know where, at the filesystem level, these files exist, so we have
    no way of copying them to xml-site/targets/fop.

Last Line of $RCSfile$