This chapter provides a detailed description of 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.
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.
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 installation
instructions 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 read it completely.
(Chapter II can be skipped, because it only
contains information that is very PHP specific.)
Installation on OS X:
The PHP Documentation HOWTO advises users of Mac OS X to use
packages provided by Fink. Alternatively packages from the
MacPorts project can be
used. After installing MacPorts, the toolchain can be
installed using the following command:
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 are two test servers that automatically download peardoc
from CVS and build the manual.
Any parsing errors your changes cause will show up in the logs
the next time the build happens:
These automatic builds also give 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).
| 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.
This chapter will not describe all the details about the directory
structure, because one can find out the essentials about it by
browsing the previously created directory
peardoc.
As a starting point for package
documenters peardoc/en/package/ fits well.
If one has further questions concerning the directory structure, they
can ask on the documentation
mailinglist.
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/en/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.
Creating dozens of files, one for each function in each class of your
package is rather boring. Luckily, we have the PhpDocumentor in PEAR
which has a renderer to generate templates for your classes and methods.
Create a test directory and cd into it. Then, run the following command:
phpdoc -p on -f /path/to/my/package/source/File.php -t .
-o "XML:DocBook/peardoc2:default" -dc myPackageCategory
After creating the files, check if they are all ok and edit them - add
examples, additional documentation and remove unnecessary sections.
Note:
phpdoc generates
documentation templates. The generated docs are
by no means complete, you need to edit them afterwards!
Generating human-readable versions of the DocBook sources requires
the existence of the above-mentioned software.
The PEAR documentation system uses Unix style makefiles:
peardoc$ autoconf
peardoc$ ./configure --with-lang=en
peardoc$ make html
|
If you want to build a language other than English,
change en, above, to
the appropriate language code.
It may be that the DSSSL stylesheets are not found, resulting
in the message
checking for docbook.dsl... defaulting - WARNING!!!
DSSSL NOT FOUND - WON'T WORK THIS WAY |
In this case make sure you've installed the DSSSL packages.
On a Mac using Fink, you might have to specify the location
yourself:
./configure --with-dsssl=/sw/share/sgml/dsssl/docbook-dsssl-nwalsh
On Windows, the easiest way to get the DSSSL sheets is to check out
the phpdoc module on cvs.php.net - they can be
found in the dsssl/ subdirectory.
This will generate a "raw" HTML
version of the whole manual.
The result will be placed in the subdirectory
html/.
The command make test does not generate any
human-readable result, but it can be used to make sure that the
XML is syntactically correct and that the build
runs fine.
And it is much faster than make html.
Numerous developers have reported problems when using the
make html command, namely that the output
was not written to a file but instead dumped on the console.
If you encounter this problem and have checked out the DocBook
sources into e.g. /home/you/cvs/peardoc,
checkout the phpdoc module (using the
procedure described above) into
/home/you/cvs/phpdoc, and run
make html again.
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
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]
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
|
In make-partial.php, takes a long time to
complete all questions. make partial with the correct
parameters is much faster, e.g.
make partial INCLUDE="packages package.database".
The full list of IDs can be obtained by inspecting the output of
make.
Translating documentation is another important task.
Existing translations need to be brought
up to date because the English versions have been changed.
Help on how to perform the translation process is in the Revision Tracking
section of the manual.
