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-beta

... downloading

$ phd --version
PhD Version: 1.0.0-dev
Copyright(c) 2007-2009 The PHP Documentation Group

Installing the PhD Packages:

$ pear install doc.php.net/phd_php-beta
downloading PhD_PHP-0.9.0.tgz ...
Starting to download PhD_PHP-0.9.0.tgz (17,064 bytes)
......done: 17,064 bytes

$ pear install doc.php.net/phd_pear-beta
downloading PhD_PEAR-0.9.0.tgz ...
Starting to download PhD_PEAR-0.9.0.tgz (13,991 bytes)
.....done: 13,991 bytes

That's it!

Installation from SVN

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

$ svn checkout http://svn.php.net:/repository/phd/trunk phd
... output

$ pear install -f package.xml
... install ok: channel://doc.php.net/PhD-1.0.0
... install ok: channel://doc.php.net/PhD_Generic-0.9.0

$ pear install -f package_php.xml
... install ok: channel://doc.php.net/PhD_PHP-0.9.0

$ pear install -f package_pear.xml
... install ok: channel://doc.php.net/PhD_PEAR-0.9.0

$ phd --version
PhD version: 1.0.0-dev
Copyright (c) 2008-2009 The PHP Documentation Group

And now you're done.

Using PhD to render documentation

Table of Contents

Rendering the PHP Documentation Sources

Getting the PHP Documentation Sources

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

$ cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc
... output

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

$ php 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 .manual.xml
... status messages

After a running for a few moments, PhD will generate PHP-web and HTML output into build/en/. The HTML output includes an html directory and bightml.html, which is the documentation rendered as one very large HTML file. The PHP-web sources are the documentation prepared for use on php.net or a mirror.

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.0.0-dev                                                                                        
Copyright (c) 2007-2009 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)
  -d <filename>
  --docbook <filename>       The Docbook file to render from
  -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: .)
  -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: false)
  -g <classname>
  --highlighter <classname>  Use custom source code highlighting php class
  -V
  --version                  Print the PhD version information
  -h
  --help                     This help

Most options can be passed multiple times for greater affect.

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:
        Default
                xhtml
                bigxhtml
                php
        IDE
                functions
                funclist
        PHP
                xhtml
                bigxhtml
                php
                howto
                manpage
                pdf
                bigpdf
                kdevelop
                chm
        Pear
                xhtml
                bigxhtml
                php
                chm

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.

Compile the PhD guide

The PhD guide is this manual you are reading currently. It lives in PhD's SVN repository under docs/phd-guide/phd-guide.xml. If you installed PhD from SVN, 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.

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

  1. <?xml version="1.0" encoding="utf-8"?>
  2. <preface xmlns="http://docbook.org/ns/docbook"
  3.  xmlns:phd="http://www.php.net/ns/phd"
  4.  xml:id="preface"
  5.  phd:chunk="false"
  6. >
  7.  <info>
  8.   <title>Preface</title>
  9.  ..
  10.  </info>
  11.  ..
  12. </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:

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

Class links

Class name as phd:linkend attribute value.

  1. <phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element"/>
  2. <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.

  1. <phd:pearapi phd:package="HTML_QuickForm" phd:linkend="HTML_QuickForm_element::setName"/>
  2. <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.

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