Chapter 20. Writing documentation

Table of Contents
The DocBook XML format
Tips for good documentation

This chapter provides a detailed description how to write documentation using one of the supported formats. It is aimed at both PEAR developers that are already maintaining packages in PEAR and at people who are planning to contribute a new package.

The DocBook XML format

DocBook is an XML dialect that is used by a wide range of projects to maintain their documentation. Examples for DocBook usage in OpenSource projects are the documentations of KDE and PHP. PEAR has opted for using DocBook, because we believe that it provides a solid foundation for the technical documentation for PEAR packages.

The trade-off for using DocBook is that it is relatively hard to use. Testing documentation requires a number of tools to be installed and one needs to learn a (not very complicated) XML dialect. Once one is familiar with how DocBook works, they will enjoy writing documentation with it though.

The book [DocBook: The Definitive Guide], written by Norman Walsh and Leonard Muellner and published by O'Reilly & Associates, Inc., is available online and it makes up a great resource for people interested in learning DocBook.

Definitely check out the book's "DocBook Element Reference" section. This portion provides detailed information about each element, including which elements can (and must) be used as parents and children.

Required software

Even if DocBook XML can (like any other XML file) be written using a normal text editor, it is optimal for users to install some software on their machine in order to test the validity of the documenting efforts. A list of the required software and a installation instruction can be found in the PHP Documentation HOWTO. Apart from providing information about the software, this HOWTO also provides a ton of other useful information that goes far beyond this chapter. One is encouraged to completely read it. (Chapter II can be skipped, because it only contains information that is very PHP specific.)

Unfortunately, installing that software can be difficult under some circumstances. If you are unable to get it working, don't use that as an excuse for not writing documentation. There is a test server that every two hours automatically downloads peardoc from CVS and builds the manual. Any parsing errors your changes cause will show up in the logs the next time the build happens:

http://www.appelsiini.net/~tuupola/php/peardoc2/peardoc.txt (time zone: EET = UTC+2, EEST = UTC+3)

This automatic build also gives you an idea of what your changes will look like in the actual manual. This is helpful because the manual on the PEAR website is only built once per week (Sundays ~12:00 UTC).

http://www.appelsiini.net/~tuupola/doc/peardoc/

Warning

The manual on the PEAR website is built only once per week. Any XML validation errors will cause the build to fail. If the main build fails, the old version remains in place, meaning the manual will be out of date. Therefore, always check the test build logs to ensure your changes are valid. More importantly, do not commit updates shortly before the main build happens (Sundays ~12:00 UTC).

Once the necessary software is in place, one has to get the latest version of the XML sources from PEAR's CVS repository:


$ cvs -d :pserver:<user>@cvs.php.net:/repository login
     
     
[password]
     
     
$ cvs -d :pserver:<user>@cvs.php.net:/repository co peardoc
     

If you do not own an account for cvs.php.net, please choose cvsread as the username. When asked for the password, type phpfi.

After that the directory ./peardoc will contain a local copy ("sandbox") of the latest sources. If you are not yet familiar with CVS, then the online book "Open Source Development with CVS" will provide you with all the necessary information.

Writing documentation

Instead of a long and boring description for writing documentation using DocBook, we would like to point you to a bunch of "reference documents", from which you should be able to learn quickly:

  • peardoc/authoring

    The CVS tree has a complete set of DocBook XML templates. These files provide the standard of how PEAR documentation should look.

    The simplest way to utilize them is to copy them to your working directory, rename them accordingly, edit the contents to match the reality of your program and then upload them to your package's directory in the repository.

  • HTTP Request

    The documentation for HTTP_Request, which is a relatively small package, only consists of a bunch of end-user documentation, which describes all of the basic features of the package. Each feature description includes at least one example. For small packages with only a handful of methods this documentation type is absolutely enough.

  • XML Beautifier

    XML_Beautifier is a package that is also relatively compact, but which supports different configuration options. These options are described in the documentation Additionally the documentation gives usage examples and (unlike HTTP_Request) also includes API documentation for its methods.

  • DB

    DB is a large PEAR package and has excellent documentation, including usage examples. The DB docs carefully adhere to the formatting specified in peardoc/authoring. The link above goes to the DocBook source code in the CVS repository. It might be helpful to examine the HTML generated therefrom.

In addition to the examples above, you will find much more documentation examples by browsing the peardoc directory, which contains your local version of the CVS tree. Especially the directory peardoc/en/packages/ should be of interest for you. You can also browse the CVS module using the web interface, including the raw XML for the file you are presently reading.

Testing documentation

Using xmllint

Alternatively one can use the xmllint program that is part of the libxml2 toolkit. This is especially useful for systems where the DSSSL/make setup does not work properly.

In addition to testing the well-formedness of the DocBook sources, xmllint can also check the semantical correctness with the help of RELAX NG schemas. The schema files for DocBook are available as a ZIP package from docbook.org. After unzipping the package into the directory relaxng/ inside the peardoc source folder, one can run xmllint from the root folder of the PEAR documentation as follows:

xmllint --valid --noout --relaxng relaxng/ manual.xml

Partial builds

The build process (not the test builds, which are reasonably quick) actually takes a very long time which makes debugging and testing a very hard task. In order to increase build performance, the script make-partial.php in the root directory of the documentation module may be used. This is an interactive command line script that will enable to you to selectively include the different parts of the manual. In the following example a version of the manual is generated which only contains a certain part of the Developer's Guide and the documentation for the HTTP packages. Using these partial builds reduces the build time dramatically.


peardoc$ ./make-partial.php
Include about-pear? [NO] 
Include guide-newmaint? [NO] 
Include guide-developers? [NO] y
Include guide.developers.intro? [NO] 
Include guide.developers.meaning? [NO] 
Include guide.developers.contributing? [NO] 
Include guide.developers.packagedef? [NO] 
Include guide.developers.release? [NO] 
Include guide.developers.supporting? [NO] 
Include guide.developers.recommendations? [NO] 
Include guide.developers.documentation? [NO] y
Include core? [NO] 
Include packages? [NO] y
Include package.authentication? [NO] 
Include package.benchmarking? [NO] 
Include package.caching? [NO] 
Include package.configuration? [NO] 
Include package.console? [NO] 
Include package.database? [NO] 
Include package.datetime? [NO] 
Include package.encryption? [NO] 
Include package.fileformats? [NO] 
Include package.filesystem? [NO] 
Include package.gtk? [NO] 
Include package.html? [NO] 
Include package.http? [NO] y
Include package.images? [NO] 
Include package.internationalization? [NO] 
Include package.logging? [NO] 
Include package.mail? [NO] 
Include package.math? [NO] 
Include package.networking? [NO] 
Include package.numbers? [NO] 
Include package.payment? [NO] 
Include package.pear? [NO] 
Include package.php? [NO] 
Include package.science? [NO] 
Include package.streams? [NO] 
Include package.structures? [NO] 
Include package.system? [NO] 
Include package.text? [NO] 
Include package.tools? [NO] 
Include package.xml? [NO] 
Include package.webservices? [NO] 
Include pecl? [NO] 
CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
creating manual.xml
/usr/bin/jade -wno-idref  -d html.dsl -V use-output-dir -t sgml ./phpdocxml.dcl manual.xml