Unfortunately we couldn't locate any off-the-shelf system for producing this fairly large manual with some special requirements like automatic inclusion of PHP source that should be highlighted and in addition rendered by running the scripts and automatically include the resulting images in the resulting manual. To solve this we have based our solution around a DocBook5 setup with some custom steps that are described below.
DocBook5
The source for the manual is written as a number of split DocBook5 XML compliant documents using
XInclude to bring them
together into one master document.
The transformation of the XML source files was done by the means of a DocBook XSL
stylesheet using the xsltproc XSL processor. (see libxslt) The DocBook5
style sheets can directly produce either single file HTML or chunked (many files) HTML
(or XHTML).
In addition there is a style sheet to produce FO (Formatted Objects) output which can
be further refined to PDF with the help of the fop processor (see
Apache FOP).
Unfortunately some formatting instructions in the source are lost in the transformation
to PDF output. This means that some aspects of the manual doesn't come out perfect in
the PDF output. For this reason the PDF version of the documentation should only be seen
as a complementary documentation. The master output format is the chunked HTML.
Note
In formatting the chunked output we have prioritized to keep down the number of files to avoid many pages with only a small amount of text on them. Our view is that documentation which breaks the pages down to very low levels are extremely tiresome to read.
Phing based build system
The overall build process is drive by a Phing XML build script.
Phing (See http://phing.info/trac/ ) is most easily described as a PHP version of the
Java build system Ant. It has several advantages compared with a more
traditional make setup, the build files are all written in clear XML
which makes them easy to read and maintain. In addition there are a number of built-in
commands that makes deploying and handling of files extremely easy compared with a
traditional make system which must rely on external tools to do everything.
Syntax highlighting of example code
The syntax highlighting and handling of the numerous example images initially posed a small problem since there are no off-the-shelf good support for handling this. As a basic requirement we needed all PHP scripts to be runnable and kept in the normal example directories and then automatically included when the DocBook source was processed.
What was needed was some easy way by which we could just mark in the DocBook source (and still maintain valid DocBook XML) that we wanted a particular named example included and either show just the image, just the source or both. In addition we required the source to be syntax highlighted.
To handle this we had to write some custom tasks to extend Phing. In principal our build system works as follows.
When a new example have been added or an old one removed a special target in our build file are run which extracts all scripts from the example sections in the *.XML files. The name of each found example script in the XML source corresponds to an existing PHP script in the Example directory in the JpGraph distribution. A batch file is then automatically created which is subsequently run and all generated images stored on disk.
When the normal DocBook XSL processing is done all the special example markups in the XML source is replaced with XML tags to include the image and make sure that the referred script is a proper PHP file name.
After the XSL process has been run all programlisting tags will have a special token, for example "
\#\#example0.php\#\#" this then instructs a custom Phing task to replace the name in the double "#" tags with the corresponding source (in the resulting HTML code). At the same time this source is included it is also passed through the custom syntax highlight filter so that it comes out as proper marked up source which is inserted directly in the resulting HTML file.
The overall build system is illustrated in Figure A.1
The way the special markup works is that whenever we want a full example (source and image) we create a <programlisting> tag with the file name and title within (single) "#" characters. For example to include the very first example in this manual we have the following tags in the docbook XML source
<programlisting>#example0|The very first example#</programlisting>
The first part (before the "|") is the file name without extension that we want to include and the second part (after the "|") is the title we want to use. This markup will include both the source as well as the generated graph/image directly in the resulting HTML.
When new examples have been added the examples target in our build file is run and
that extracts all the example script used in the book (in the above example
"example0.php") and creates a batch file which is then run to create
all the images used in the examples.
The syntax highlighting is handled by a custom written filter extensions to
Phing which internally uses the PEAR package
Pear::Text_Highlight.
Notes:
In the current setup a regular expression in the Phing build script is responsible for replacing the markup in the programlisting with a <figure> tag and a new <programlisting>. This should be done with a custom XSL layer instead and we will update this for the next major revision.
Since the syntax highlighting makes use of HTML markup code for the colors the PDF output does not support syntax highlighting
For the reference manual we still use our old DB based documentation system which stores all the methods and classes in a DB augmented with source documentation. (We actually prefer this in front of adding a lot of end user documentation with PHPDoc comment sin the source which have a tendency of cluttering up the code as well as making it prone to error since the source files have to be modified in order to update a simple typo in the documentations. Our next step is therefor to update that old system to be able to produce DocBook5 compliant XML for further formatting and processing.