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 Git 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 Git repository is the starting place for processing. The path to the documentation is src/documentation/content/xdocs.

All documentation is maintained on the main.

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

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

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 people.apache.org in /www/www.apache.org/dist/xmlgraphics/fop/.

Please be careful when doing stuff like that.