The Apache FOP Project

The Apache™ FOP Project

Apache™ FOP Development: Managing Documentation

This page is obsolete. Do not follow this to make FOP documentation.

General Information

All raw documentation content is managed in the Apache™ 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 src/documentation/content/xdocs.

All documentation is maintained on the trunk.

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.



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).



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 in SVN
Developer builds and uploads documentation using ForrestBot. /www/ on sync-ready n/a
Cron job runs rsync to synchronize the website with the real web server (runs every few hours). Infrastructure knows. :-) web-ready FOP Web Site

Server-side ForrestBot is currently not available for website publishing. We use it locally and with manual invocation.

ForrestBot "publish" Step-by-Step

We're using ForrestBot for build and deploy the FOP website. ForrestBot comes with Apache Forrest 0.8. The root directory of your FOP checkout contains the file "publish.xml" which is an Ant build file that manages the build and the deployment of the FOP website. Please look into this file for further instructions to set up ForrestBot on your machine. Basically, we're simply running ForrestBot manually by typing "ant -f publish.xml" once we're happy with our changes to the site. Step-by-step instructions for the deployment process again:

Please make sure you use Forrest from the Trunk (revision 632959 or later) for the time being. You will need to download it directly from SVN:

The reason for putting the generated website in the SVN repository: The infrastructure people want to be able to restore the websites themselves in case of a crash.

Using a Local Forrest

To use a local Forrest (during website development, not for deployment):

You can use "forrest run" to start a local web server. That improves development speed as you can simply refresh in the browser after a change.

Updating Distribution Files

The Apache distribution system mirrors distributions around the world. Since it uses Apache httpd Module mod_autoindex you also need to manually update the HEADER.html & READER.html files on in /www/

Please be careful when doing stuff like that.

Deleting Documentation Files

ForrestBot simply uploads the whole generated site. It doesn't delete obsolete files. You can do that manually in the /www/ folder on Be careful when doing stuff like that.

Please make sure you always have group rw permissions on all files under the /www directory!