PHP-GTK 2 Documentation

About this Tutorial and the Manual

This tutorial explains how to obtain, compile and write or extend the official PHP-GTK 2 documentation - that is, the manual you are currently reading.

If you simply want to read the manual, this probably isn't of any interest to you.

The source for this documentation, along with the PHP-GTK 2 source and everything else that comes under the PHP project umbrella, resides on the PHP project's SVN server at svn.php.net. It is loosely based on an XML dialect called DocBook, which was designed to be used for books and other forms of technical documentation. The reason the PHP-GTK documentation project can't adhere to strict DocBook syntax is that it has one major weakness: there is no DocBook syntax to support the documentation of object oriented languages. We had to design our own. This, in turn, means that the PHP-GTK Documentation Group also need to adapt other php.net mechanisms - such as livedocs and .chm builds - specifically to work with the php-gtk-doc syntax, whereas we could utilize those tools out of the box if we were able to use pure DocBook XML.

Despite this, there are several benefits in basing the manual on DocBook. The document (i.e. the entire manual) can be distributed over many files, so that the files are in handy pieces and many people can work concurrently on different parts of it. Further, the base XML files can be converted into many formats: plain HTML for offline reading, PHP code (as you can see in the online manual), Windows .chm files, and .pdf files, to name but a few.

A big disadvantage is that you need to compile the XML from the sources into the desired format, which can take quite some time. This manual consists of over 300 single files, and the compiled HTML version has more than 3000 generated files. Compilation takes 10 minutes on a 1.6GHz system; on a 400MHz it's around 40 to 45 minutes. To combat this problem, there is a single-page HTML version of the manual, bigmanual.html, which builds in just a few minutes and which can be used to uncover any syntax errors in the source files.