vmote       2002/12/11 11:06:38

  Modified:    src/documentation README
  Log:
  Expand with more details, and add some comments from Jeff Turner.
  
  Revision  Changes    Path
  1.2       +48 -23    xml-fop/src/documentation/README
  
  Index: README
  ===================================================================
  RCS file: /home/cvs/xml-fop/src/documentation/README,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- README    3 Dec 2002 10:06:10 -0000       1.1
  +++ README    11 Dec 2002 19:06:38 -0000      1.2
  @@ -1,24 +1,49 @@
  -To update the docs:
  -
  -The documentation is generated using forrest (http://xml.apache.org/forrest/).
  -
  -The current procedure is:
  -
  -- checkout xml-forrest module
  -- run: build.sh(bat) dist
  -- follow instructions to set FORREST_HOME and path
  -- go to xml-fop directory
  -- run forrest(.bat)
  -
  -The documents will then be placed in build/site/
  -
  -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/
  -
  -To update website
  -- put the generated docs into the xml-site module targets/fop/
  -  this could be done by simlinking the destination to the targets/fop
  -- commit the documents
  -
  +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 Jeff Turner, the downstream process of publishing our web site is as
  +    follows:
  +    - Committers commit generated docs to xml-site/targets/{project}
  +    - Every X hours, a script updates /www/xml.apache.org/ or wherever on
  +      the live site, from CVS.
  + 2. Per Jeff Turner, the FOP website is being regenerated (from the contents
  +    of xml-site/targets/fop) by Forrest every hour.
  +    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.
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]

Reply via email to