HOW TO UPDATE THE FOP WEBSITE

Background
--------------
 1. The FOP web site & documentation are generated using forrest
    (http://xml.apache.org/forrest/).
 2. There are two general ways to update the FOP web repository, each described
    in more detail below:
    a. the forrestbot on the Apache server
    b. a local copy of Forrest
 3. Files related to the web site reside in the following places:
    a. FOP source repository (cvs):
       icarus.apache.org/home/cvs/xml-fop
    b. interim web site (html, pdf, etc.)
       1) if forrestbot is used:
          Location is unknown & unimportant to us.
          Content can be viewed, refreshed, and published at:
          http://forrestbot.cocoondev.org
       2) if local Forrest is used:
          Files will be generated on your local machine.
    c. FOP web repository (cvs):
       icarus.apache.org/home/cvs/xml-site/targets/fop
    d. FOP live web site:
       somewhere on daedalus.apache.org
 3. The flow of data from our project committers to the actual web site is as
    follows:
    a. Source code changes are committed to the cvs repository by developers.
    b. An interim web site is built using one of two methods: manual/local or
       forrestbot.
    c. The interim web site is committed to the FOP web repository, again using
       one of two methods: manual/local or forrestbot.
    d. Every six hours (midnight, 6am, noon, 6pm Pacific time), a script copies
       the contents of the web site repository to the server for the FOP live
       web site. For support on this process:
       1) The CVS update logs can be viewed at
          http://www.apache.org/~rubys/updatesite.logx, where "x" is a number
          from 1-4, these four files being the updates done over the past 24
          hours. Review the most recent log file for clues.
       2) the script is maintained by Sam Ruby (rubys@apache.org). Contact him
          for further help.

Forrestbot or Local Forrest?
----------------------------
By far, the easiest way to generate an interim web site and to update the FOP
web repository is to use the forrestbot on the Apache servers.

Advantages:
1. Easy to use.
2. Always using the "approved" versions of Forrest and supporting
   infrastructure.
3. No manual steps with attendant human error.

Disadvantages:
1. Ties up server resources.
2. Requires a server login (see http://forrestbot.cocoondev.org for instructions
   about how to obtain one).

For minor or pure documentation changes, use the forrestbot. For major changes,
such as sitemap building, that will require many edit/build/test/debug cycles,
use a local Forrest instead. Also, even for major changes, it is probably better
to do the final build and commit using the forrestbot, after all of the
debugging has been completed on your local machine.

Updating the Web Site Repository using the Forrestbot
-----------------------------------------------------
To use the forrestbot, simply follow these steps:
1. Make sure your changes are committed to the FOP source repository.
2. Open http://forrestbot.cocoondev.org in your browser.
3. Login.
4. In the "Select a module" box, select "xml-fop".
5. Click the "refresh" button to have the interim site built. On-screen
   instructions tell you how to view the log as the build progresses.
6. After the build has completed, click "xml-fop" in the list of preview sites.
   The interim site will be displayed in a frame.
7. After you are satisfied with the interim site, commit it to the FOP web
   repository by first making sure that "xml-fop" is still selected in the
   "Select a module" box, then clicking "publish". Again, you can watch the
   log as it is built.
8. Wait for the next 6-hour update cycle and check the live web site.

Updating the Web Site Repository using a Manual/Local Forrest
-------------------------------------------------------------
 1. Note: 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).
 2. checkout the xml-forrest module (same repository as xml-fop).
 3. checkout the xml-site/targets/fop module (same repository as xml-fop).
 4. you will also need access to a current xml-fop sandbox (you probably already
    have one)
 5. cd to xml-forrest
 6. run: build.sh(bat) dist to build forrest
 7. 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)
 8. set environment variable PATH=$PATH:$FORREST_HOME/bin
 9. cd to xml-fop directory
10. run forrest(.bat), which will build the web-site documents in
    xml-fop/build/site.
11. To update the actual website, copy the generated documents
    (in xml-fop/build/site) to xml-site/targets/fop on your local machine.
    (This could also be done by sym-linking this destination before the build.)
12. Consider whether your final build and publish should be done using the
    forrestbot on the Apache servers (see discussion above). Otherwise, commit
    xml-site/targets/fop.

Last Line of $RCSfile$