From: William Victor Mote Date: Tue, 25 Mar 2003 17:01:51 +0000 (+0000) Subject: Rewrote with instructions for using forrestbot. Added more detail. X-Git-Tag: Root_Temp_KnuthStylePageBreaking~1733 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=b666132ce4288d6389049da402cc750d3c778f7d;p=xmlgraphics-fop.git Rewrote with instructions for using forrestbot. Added more detail. git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@196140 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/src/documentation/README b/src/documentation/README index c3ccc1166..7431ffd35 100644 --- a/src/documentation/README +++ b/src/documentation/README @@ -1,59 +1,102 @@ $Id$ -To update the FOP website: + HOW TO UPDATE THE FOP WEBSITE Background -------------- - 1. The documentation is generated using forrest + 1. The FOP web site & documentation are 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 + 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. This script is maintained by Sam Ruby. + +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) - 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 + 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) - 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 + 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. -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. + (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$ \ No newline at end of file