6 PPW Documentation

It is important for both users and developers that PPW include a wide variety of documentation in appropriate formats.

6.1 Documentation Requirements

Here are some basic requirements for PPW documentation:

1. Store/represent user documentation in one primary “canonical” form
2. Provide user documentation in the following formats:
   • Single-page and multi-page HTML (nicely formatted via CSS, etc.)
   • Printable PDF
   • man pages (properly formatted)
   • GNU info
   • Plaintext (nicely readable; somewhat marked up)
   • “Online” docs in the PPW GUI (simplified HTML)
3. Have “reasonable” developer docs (including source-code docs)

6.2 Format and Organization

The “canonical” format chosen for PPW documentation is GNU Texinfo. This choice was made because we can ultimately generate all of formats we need and achieve high-quality output.

PPW's documentation, which resides within the docs directory inside the PPW source tree, has been incorporated into the build system used by PPW. See the docs/Makefile.am file and the various Perl scripts within the docs directory to understand how the various documentation is generated.

Where needed, the PPW documentation incorporates screenshots and other images; these are stored in PNG form within the docs/images directory. Any other image formats (such as PDF) that are needed are generated (automatically) by way of Perl scripts within docs.

6.3 Source-Code Documentation

The source-code documentation for PPW is maintained as Doxygen markup within both the C and Java codebases. The Doxygen configuration file for PPW is docs/Doxyfile, which is generated from docs/Doxyfile.in. The Doxyfile specifies what source code Doxygen processes (essentially everything within src, javasrc, and codegen), along with various options. Doing a basic Google search for “Doxygen” should unveil sufficient information on the Doxygen documentation system and related utility.