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 doc.php.net/phd-beta doc.php.net/phd_pear-beta
...
$ 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
done
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 that 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
done
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 pear.php.net 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:
| 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 |
忘却曲線を使ってこの知識を確実に記憶に残す
