Rendering the manual

The PEAR documentation gets - like the PHP Manual - built using PHP's very own DocBook rendering system called PhD. Installation is a breeze using pear:

$ pear install
$ phd --version
PhD version: phd-from-cvs
Copyright (c) 2007-2009 The PHP Documentation Group

When using PEAR before verson 1.8.0, you need to discover the channel first.

Besides that, one only needs a SVN checkout of the peardoc module.

Preparing the build

Before building, you need to use the configure.php script provided by peardoc. This script serves two purposes:

  • Validate XML

  • Combine all xml files into one large single file to speed up the build process

Just change into your peardoc source folder and run:

$ php configure.php
Generating chapters.ent for en
 3376 xml files
 6 php example files
Loading manual into one giant file
Validating done
Now call phd: phd -L en -P PEAR -f xhtml -o build/en -d .manual.xml

If you see those lines, everything is fine and you can continue compiling the manual.

Like with every proper unix tool, you can use php configure.php --help to get an overview about the supported command line parameters.

In case something goes wrong, the config script will tell you either where it failed, or which commands to execute to find the right spot:

$ php configure.php
Generating chapters.ent for en
 3376 xml files
 6 php example files
Loading manual into one giant file
There were warnings loading the manual Warning:
 DOMDocument::load(): Opening and ending tag mismatch:
 set line 46 and book in
 /home/cweiske/Dev/cvs/pear/peardoc/manual.xml, line: 67 in
 /home/cweiske/Dev/cvs/pear/peardoc/configure.php on line 278
Exception: Failed to load manual.xml

Fix the error and run configure.php again until it tells you everything is ok.

Compiling the manual

Now that you configured everything properly, run the command that configure.php told you. The command will be something along that:

$ phd -L en -P PEAR -f xhtml -o build/en/ -d .manual.xml

configure.php generated a giant manual file named .manual.xml. If you use plain manual.xml your build will take about double as long as with .manual.xml (note the leading dot).

When PhD doesn't report any errors, your generated HTML documentation will be available in build/en/html/.

Partial builds

When writing documentation for a single package, you probably don't always want to compile the whole manual. PhD allows you to compile a small part of the manual which is faster than doing the whole thing. Just pass "-p package.category.packagename" as parameter to PhD, and only the part of the manual below that ID will be created.

At the time of writing, partial rendering in PhD is not noticable faster than creating the whole manual. This will change in the future, though.

In case you didn't change the structure (adding or removing IDs), you can skip PhD index creation (-I) which will save you about 15-20 seconds build time.

Other sources to test your documentation

Several PEAR members regularly build the documentation on their own machine in shorter cycles than the server. When you don't have the chance to test and build your changes, you can use any of this build servers to check everything is fine:

Regular builds provided by PEAR members
PEAR member Build interval Format Build log
Brett Bieber 2 hours Chunked HTML log
Benedikt Hallinger at 06:00 and 18:00 CEST Chunked HTML log