FOP Development: Managing Documentation $Revision$
General Information

All raw documentation content is managed in the FOP SVN repository. Updates should be committed to the repository, then the repository files are used to generate usable output. The remaining discussions on this page assume that the SVN repository is the starting place for processing. The path to the documentation is xml-fop/src/documentation/content/xdocs.

All documentation is maintained on the trunk. Although we are currently maintaining two sets of code (trunk and maintenance), there is only one set of documentation. Most of the user and developer doc is common to the two environments, and differences are highlighted where necessary. The major exception to this rule is the design doc, which currently exclusively pertains to the trunk (redesign). Maintenance branch releases either copy the trunk content to the maintenance branch or use the trunk content directly for doc builds.

Basic documents are stored in XML files, and use DTDs provided by Apache Forrest.

Design Principles

These principles are not written in stone, but reflect the current philosophy, and are documented here primarily to help achieve consistency. These principles should be changed if better or more practical ones are found, but they should probably be discussed and changed by common consent.

Where
  • To the extent possible, keep user content separate from developer content, primarily so the user doesn't have to filter out technical information.
  • To the extent possible, try to document a topic exactly once, in the place the user is most likely to look for it, then link to that from other locations as appropriate. This is somewhat contrary to the principle above, which should be applied as a higher priority.
When

The documentation and the product are in a constant state of change, and there is some difficulty in deciding what product state the website content should reflect. The current thinking is that the website should reflect the current state of the repository code branch from which releases are made. Features or other documentation that applies to unreleased code should be marked in such a way within the content that the user can determine whether and how it applies to the version they are using. For example, "Feature xyz is first available in Release n.nn.n".

Other approaches were considered, but all seemed to have significantly higher costs both to the users and the developers. From the user's standpoint, the choice is either that they potentially have to look multiple places to get the information they need (which was rejected), or they have to filter out an occasional feature that is in code available subsequent to their release (which was accepted).

Website
Background

The FOP web site and documentation are generated using Apache Forrest.

The following table summarizes the flow of data to the FOP website in chronological order:

Process Output State View(s)
Developer commits code to FOP repository. FOP repository (SVN) Raw XML and other content ViewCVS
Developer builds documentation and commits it to xml-site. xml-site repository (cvs) at cvs.apache.org/home/cvs/xml-site web-ready ViewCVS
Developer publishes website. FOP live web site, /www/xml.apache.org/fop on www.apache.org web-ready FOP Web Site
Forrestbot is currently not available for website publishing.
Using a Local Forrest

To use a local Forrest:

  • download latest the Forrest release
  • checkout the xml-site/targets/fop module (same repository as xml-fop)
  • set environment variable FORREST_HOME=~/apache-forrest-0.6/src/core where ~ is the directory where Forrest is installed (see http://forrest.apache.org/docs/your-project.html for details)
  • set environment variable PATH=$PATH:$FORREST_HOME/bin
  • cd to xml-fop directory
  • run forrest(.bat), which will build the web-site documents in xml-fop/build/site.
Updating the FOP Web Repository Manually
  • Copy (or sym-link) the documents generated by Forrest (in xml-fop/build/site) to xml-site/targets/fop on your local machine.
  • Commit xml-site/targets/fop.
Deleting Documentation Files

The one place where manual updates of the web cvs repository are required is when a document is retired. At this point, it will no longer be generated. However, it will still exist in the web cvs repository. You will need to use a cvs client to remove the files, then commit the changes to keep them from continuing to exist on the live site.

Publish the Website
  • ssh to www.apache.org
  • cd /www/xml.apache.org/fop
  • make sure your umask is 0002 (to make the files group writeable)
  • cvs up -Pd