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.
You might find some other tutorials in the links section.
PhD is distributed via an own PEAR channel,
doc.php.net. Using it is also the most easy way to get
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
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 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.
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
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.
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.
PhD lets you specify a number of options to customize the generated documentation files. The following sections describe some of them.
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.
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!"; ?>
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.
Install GeSHi from the MediaWiki PEAR channel:
$ pear channel-discover mediawiki.googlecode.com/svn $ pear install mediawiki/geshi
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.
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:
The extensions listed here are available in all PhD themes and formats.
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.
phd:chunk may have values true and false. They force the element to be chunked or not.
phd:chunk may be used in every tag that accepts » db.common.attributes.
<?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>
To manually insert a Table Of Contents (TOC) that creates a list of links to children elements of a specified tag.
<phd:toc> is can be used everywhere <para> is allowed.
You can add a title with <title>.
|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|
The DocBook extensions listed here are only available when using a PEAR theme.
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.
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>
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>
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>
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>
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.
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.