PhD: The definitive guide to PHP's DocBook Rendering System

Table of Contents

About PhD

PhD is PHP's very own DocBook 5 rendering system. It is used to convert the PHP Manual and PEAR Documentation into different output formats like XHTML, PDF, Man pages and CHM.

The goal of PhD is to become a fast, general DocBook rendering system. At the moment of writing, PhD is already very fast: It can create the chunked version of PEAR's manual (some 3000 files) in less than a minute on a 2GHz system. It also renders the PHP and PEAR manual flawlessly. It does not support every DocBook 5 tag yet, and using it to render own DocBook files may need some tweaks.

Getting PhD

Table of Contents

You might find some other tutorials in the links section.

Installation

PhD is distributed via an own PEAR channel, doc.php.net. Using it is also the most easy way to get it.

Installation via PEAR

Note:

You need a working » PEAR installation.

To install the latest version of PhD:

$ pear install doc.php.net/phd

... downloading

$ phd --version
PhD Version: 1.0.0-stable
PHP Version: 5.3.3
Copyright(c) 2007-2010 The PHP Documentation Group

Installing the PhD Packages:

$ pear install doc.php.net/phd_php
Starting to download PhD_PHP-1.0.0.tgz (18,948 bytes)
[...]
install ok: channel://doc.php.net/PhD_PHP-1.0.0

$ pear install doc.php.net/phd_pear
downloading PhD_PEAR-1.0.0.tgz ...
[...]
install ok: channel://doc.php.net/PhD_PEAR-1.0.0

That's it!

Installation from Git

To get the latest and greatest features that have not been released yet, you can use PhD from Git.

$ git clone https://github.com/php/phd.git
... output

pear install package.xml package_generic.xml package_php.xml package_pear.xml
[...]
install ok: channel://doc.php.net/PhD-1.0.1
install ok: channel://doc.php.net/PhD_Generic-1.0.1
install ok: channel://doc.php.net/PhD_PHP-1.0.1
install ok: channel://doc.php.net/PhD_PEAR-1.0.1
bjori@jessica:/usr/src/php/svn/phd/trunk$

$ phd --version
PhD Version: phd-from-svn
PHP Version: 5.3.3-dev
Copyright(c) 2007-2010 The PHP Documentation Group

And now you're done.

Using PhD to render documentation

Table of Contents

Rendering the PHP Documentation Sources

Note:

Getting the PHP Documentation Sources

To get the PHP documentation sources, simply » check them out from SVN with the following command.

$ svn co http://svn.php.net/repository/phpdoc/modules/doc-en phpdoc
... output

To prepare the documentation, cd to the phpdoc directory, and run configure.php.

$ php doc-base/configure.php

This process will generate a .manual.xml file in the current directory, which is what we need for building the docs. Now we're ready to proceed with running PhD to generate the PHP docs.

To quickly become familiar with using PhD, you can download the PHP documentation sources and render those.Running PhD to render the docs is surprisingly simple, so we'll start with that.

$ phd -d doc-base/.manual.xml -P PHP
... status messages

After a running for a few moments, PhD will generate all the output formats of the PHP Package into output/.

So now that you've seen the fruits of your labor, let's take a closer look at PhD and see what capabilities are available to us.

$ phd --help
PhD version: 1.1.6
Copyright(c) 2007-2013 The PHP Documentation Group

  -v
  --verbose <int>            Adjusts the verbosity level
  -f <formatname>
  --format <formatname>      The build format to use
  -P <packagename>
  --package <packagename>    The package to use
  -I
  --noindex                  Do not index before rendering but load from cache
                             (default: false)
  -M
  --memoryindex              Do not save indexing into a file, store it in memory.
                             (default: false)
  -r
  --forceindex               Force re-indexing under all circumstances
                             (default: false)
  -t
  --notoc                    Do not rewrite TOC before rendering but load from
                             cache (default: false)
  -d <filename>
  --docbook <filename>       The Docbook file to render from
  -x
  --xinclude                 Process XML Inclusions (XInclude)
                             (default: false)
  -p <id[=bool]>
  --partial <id[=bool]>      The ID to render, optionally skipping its children
                             chunks (default to true; render children)
  -s <id[=bool]>
  --skip <id[=bool]>         The ID to skip, optionally skipping its children
                             chunks (default to true; skip children)
  -l
  --list                     Print out the supported packages and formats
  -o <directory>
  --output <directory>       The output directory (default: .)
  -F filename
  --outputfilename filename  Filename to use when writing standalone formats
                             (default: <packagename>-<formatname>.<formatext>)
  -L <language>
  --lang <language>          The language of the source file (used by the CHM
                             theme). (default: en)
  -c <bool>
  --color <bool>             Enable color output when output is to a terminal
                             (default: true)
  -C <filename>
  --css <filename>           Link for an external CSS file.
  -g <classname>
  --highlighter <classname>  Use custom source code highlighting php class
  -V
  --version                  Print the PhD version information
  -h
  --help                     This help
  -e <extension>
  --ext <extension>          The alternative filename extension to use,
                             including the dot. Use 'false' for no extension.
  -S <bool>
  --saveconfig <bool>        Save the generated config (default: false).

  -Q
  --quit                     Don't run the build. Use with --saveconfig to
                             just save the config.
  -k
  --packagedir               Use an external package directory.


Most options can be passed multiple times for greater effect.

As you can see, there are plenty of options to look into in PhD. The most important options are those which allow you to select a format and package to output your documentation to.

$ phd --list
Supported packages:
        Generic
                xhtml
                bigxhtml
                manpage
        IDE
                xml
                funclist
                json
                php
                phpstub
        PEAR
                xhtml
                bigxhtml
                php
                chm
                tocfeed
        PHP
                xhtml
                bigxhtml
                php
                howto
                manpage
                pdf
                bigpdf
                kdevelop
                chm
                tocfeed
                epub
                enhancedchm

Note:

The format packages are provided by separate PEAR packages (doc.php.net/PhD_Generic, doc.php.net/PhD_IDE, doc.php.net/PhD_PEAR and doc.php.net/PhD_PHP) where only the Generic is installed by default.

You can tell by the output of the --list option that PhD can also be used to render the docs as a PDF file, or as Unix Man Pages.

To select a format and package, you must use the -f [formatName] and -P [packageName] options.

$ phd -f manpage -P PHP -d .manual.xml

This command will output the documentation for PHP functions in the Unix Man page format.

Compiling the PhD guide

The PhD guide is this manual you are reading currently. It lives in PhD's Git repository under docs/phd-guide/phd-guide.xml. If you installed PhD from Git, you already have it. Otherwise, get it:

$ svn checkout http://svn.php.net:/repository/phd/trunk/docs/phd-guide
U phd/docs/phd-guide/phd-guide.xml

Now you have everything you need. Just type

$ cd phd/docs/phd-guide/
$ phd -f bigxhtml -d phd-guide.xml

There should be an .html file in the directory now. View it with a browser!

That's all to say. This way you can render your own docbook files, too.

Customizing the rendering results

PhD lets you specify a number of options to customize the generated documentation files. The following sections describe some of them.

Source code highlighter

Part of the documentation of programming languages is source code examples. PhD is able to colorize the source code of many types of source code with the help of highlighters.

To utilize syntax highlighting, your opening <programlisting> tags need a role attribute describing the type of source code. Examples are php, html and python.

Note:

PhD currently only highlights the code if it is embedded in a CDATA section.

Example #1 A programlisting tag with a role

<programlisting role="php"><![CDATA[
<?php
echo "Hello world!";
?>
]]></programlisting>

By default, PhD uses the source code highlighter that is built into PHP itself. It is only able to highlight PHP code and nothing else.

If your documentation contains other types of source code or markup, like XML, HTML, Javascript or any other language, you should try the » GeSHi highlighter that is shipped with PhD:

  1. Install GeSHi from the MediaWiki PEAR channel: 

    $ pear channel-discover mediawiki.googlecode.com/svn
$ pear install mediawiki/geshi

  2. Use the GeSHi syntax highlighting class when rendering your documentation: 

    $ phd -g 'phpdotnet\phd\Highlighter_GeSHi' -d phd-guide.xml

If you have GeSHi version 1.1.x installed, you should use the phpdotnet\phd\Highlighter_GeSHi11x highlighter, which is adapted to GeSHi's new API.

Apart from using the highlighter shipped with PhD, you can build your own highlighters.

DocBook extensions

Table of Contents

PhD has been tailored for PHP and PEAR manuals. To make writing documentation as easy as possible, some own tags have been added to the DTD.

All extensions live in their own XML namespace "phd:" which resolves to http://www.php.net/ns/phd. When using one of the attributes or tags described here, remember to set the namespace:

xmlns:phd="http://www.php.net/ns/phd"

General DocBook extensions

The extensions listed here are available in all PhD themes and formats.

Manual chunking with "phd:chunk" (Attribute)

PhD automatically chooses which sections, chapters or other tags get their own file (chunk) when using a chunked theme. Sometimes the result of this automatism is not optimal and you want to fine-tune it. The attribute "phd:chunk" is offered as solution by PhD.

Allowed values

phd:chunk may have values true and false. They force the element to be chunked or not.

Allowed in

phd:chunk may be used in every tag that accepts » db.common.attributes.

Example

<?xml version="1.0" encoding="utf-8"?>
<preface xmlns="http://docbook.org/ns/docbook"
 xmlns:phd="http://www.php.net/ns/phd"
 xml:id="preface"
 phd:chunk="false"
>
 <info>
  <title>Preface</title>
 ..
 </info>
 ..
</preface>

Generating Table Of Contents: <phd:toc> (Tag)

To manually insert a Table Of Contents (TOC) that creates a list of links to children elements of a specified tag.

phd:toc-depth

Allowed in

<phd:toc> is can be used everywhere <para> is allowed.

Children

You can add a title with <title>.

Attributes

Attributes for <phd:toc>
Attribute name Description Default value
phd:element ID of the element whose children shall be linked none
phd:toc-depth Depth of the TOC/Number of levels 1

PEAR specific DocBook extensions

The DocBook extensions listed here are only available when using a PEAR theme.

Linking to PEAR API documentation: <phd:pearapi> (Tag)

A large part of the PEAR manual is about packages and how to use them. Package authors often find they need to link to the API documentation of a specific method, variable or class of their package. To ease the linking process, the <phd:pearapi> tag was introduced.

You can let PhD automatically create the link text by just closing the tag, or specify the tag text via the tag's content.

Package links

phd:package name is put into the attribute, any text:

<phd:pearapi phd:package="HTML_QuickForm"/>
<phd:pearapi phd:package="HTML_QuickForm">some text</phd:pearapi>
» HTML_QuickForm » some text

Class links

Class name as phd:linkend attribute value.

<phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element"/>
<phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element">some text</phd:pearapi>
» HTML_QuickForm_element » some text

Class method links

Class and method name as phd:linkend text, separated by a double colon.

<phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element::setName"/>
<phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element::setName">some text</phd:pearapi>
» HTML_QuickForm_element::setName() » some text

Class variable links

Class and variable name as phd:linkend text, separated by a double colon and a dollar sign before the variable name.

<phd:pearapi phd:package="Net_Geo" phd:linkend="Net_Geo::$cache_ttl"/>
<phd:pearapi phd:package="Net_Geo" phd:linkend="Net_Geo::$cache_ttl">some text</phd:pearapi>
» Net_Geo::$cache_ttl » some text

Extending PhD

Table of Contents

Written in PHP, PhD is easy to hack on and easy to extend. It provides command line parameters to use custom code without changing PhD internals, like source code highlighters.

Writing an own syntax highlighter

A syntax highlighter for PhD is nothing more than a simple PHP class that has two methods, a factory and highlight.

factory is static and takes the format name (i.e. pdf, xhtml, troff) as only parameter. It returns the highlighter instance object for the given format. The method is called for each output format the documentation is rendered to.

highlight takes three parameters, text, role and format. It is called whenever a piece of source code needs to be highlighted and expects the highlighted source code to be returned in whatever format the current rendering format is expected to be.

Take a look at the provided highlighters, phpdotnet\phd\Highlighter, phpdotnet\phd\Highlighter_GeSHi and phpdotnet\phd\Highlighter_GeSHi11x. They will serve as good examples how to implement your own highlighter.

Once you wrote your custom source code highlighting class, it's time to try it out.