There are now two different build systems for the php-gtk-doc module; the standard one, used on the server and having several different build options, and the alternative one, which currently offers only the English version of the multiple HTML file build.

The chief advantage of the alternative build is that it makes it possible to compile the PHP-GTK manual under Windows without installing a Linux emulator such as cygwin. You will, however, need to install several native versions of Unix tools in order to set up the build environment for it. Installing these simply means unzipping them into your root directory, so this is an easy option if you don't have good enough connectivity or are otherwise precluded from installing cygwin on your local box.

Whichever build option you use, you will need to have xsltproc installed to process the XSL stylesheets. On a Linux system, you can install this with your package manager. If you are working under the cygwin environment, you can add it via the cygwin install mechanism. If you're using plain Windows, you can download the xsltproc binaries (you'll need the iconv, zlib, libxml2 and libxslt packages) from xmlsoft.org contributor Igor Zlatkovic's project site and unzip them into your root directory.

Before we can start changing or even compiling the manual, we need to get a copy from CVS. To accomplish this, you will need a CVS client. On nearly every Linux system, the command line cvs tool is installed. This is also available via cygwin. Under Windows, there are native point-and-click CVS clients available, such as Tortoise CVS.

To get a copy of the docs using the cvs command line tool, type: cvs -d :pserver:cvsread@cvs.php.net:/repository co -P php-gtk-doc

If you already have a copy, you can update it via: cvs -d :pserver:cvsread@cvs.php.net:/repository update -Pd php-gtk-doc (if you are inside the php-gtk-doc directory, you can (have to) omit the php-gtk-doc part.

To obtain a copy of the docs module using TortoiseCVS: go to File/CVS checkout and fill out the form. The protocol is the Password server (:pserver) option; the server is cvs.php.net, and the repository folder is /repository. If you have a CVS account, please use your own user name; otherwise, use cvsread; and the module, of course, is php-gtk-doc. Under the current version of TortoiseCVS, the line endings are converted to Windows by default; we don't want this anywhere in the php.net repository, so if you're intending to commit any of your changes you should go to Options and tick the box that says Use UNIX line endings.

From the commandline, move into the php-gtk-doc directory via the command cd php-gtk-doc. Type autoconf to set up the configuration file.

There is full internationalisation (i18n) support in this build system, with the default configuration being English (en). If you are compiling for any language other than English, you will need to supply the configure line with the language code for that language, e.g. ./configure --with-lang=de. Note that this will only work if the base files for the German translation happen to exist!

Another configure option you may need to use is --with-php=PATH, where PATH is the full path to the PHP binary executable you intend to use. In most cases, the PHP 4 or PHP 5 binary found automatically by autoconf will be fine - but occasionally people have strange setups on their systems. You really should be using CLI for building, by the way, but CGI will generally cope.

You can prevent the chunked builds (html, phpweb, test) from telling you every time they write a file by using --disable-output. In theory at least, this should speed up the build time for those versions.

There is one last configuration option, --with-history, which you may or may not fall across. It's used to define the path to an external directory containing only manual/* (a snapshot of php-gtk-doc/manual). This is only used during the make updates option, which is primarily there to generate the updated documentation lists on the server. You won't need it.

Finally, there is a choice of output style. Choosing make bigmanual.html will give you a single, huge HTML file in less than five minutes; make text will do the same, but will also produce a copy of the manual as a single text file at the end of the build run. make html will eventually produce multiple HTML files in split directories alongside a copy of the images directory; make phpweb will result in a copy of the manual as it appears on gtk.php.net. By popular demand, there is now also make test id=ID, where ID is the manual id for a component, e.g. tutorials.helloadvanced or gtk.gtkwindow. This will build the relevant file - and anything below it in the hierarchy - into a toplevel directory named testbuild rather than into build.

There are two output types you are very unlikely to need at all: make mtoc, which generates a machine-readable table of contents in XML, and make updates, which is used on the build server to generate the manual updates list for the home page at http://gtk.php.net/.

Further output formats are likely to become available in the near future.

From the commandline, change into the php-gtk-doc directory via the command cd php-gtk-doc. Now set up some basic files: ./runfirst.sh (or sh ./runfirst.sh if you are working under Windows). The runfirst-script has only to be called again if completely new files have been added to the manual, or if the build date needs to be updated. So if you want to compile the manual on a daily basis, you should do that every time.

Let's generate the manual itself: At first you must understand that the php-gtk manual exists in different languages, in addition to the different formats mentioned earlier. So when compiling, you need to know which manual you want to compile. The language is determined as two-letter code, such as en for English, de for German and so on. The type is one of html for the normal html documentation you can download from gtk.php.net, phpweb to generate the files like the online docs at the PHP-GTK site, or test if you want to compile a part of the files only.

So we call ./gen_manual.sh <language> <type>, for example ./gen_manual.sh en html. You will see the lines flowing over the terminal; go somewhere and come back in ten minutes - it will take some time. The files will be generated in the build directory build/<language>/<type>/, in our case build/en/html/

If you are an editor and just want to test if the section you just wrote is correct and renders as intended in html, you can call ./gen_manual.sh <language> test <id>, as in ./gen_manual.sh en test gtk.gtkiconview. This will enable a special mode in which the manual will be stripped down to a minimal version containing only the most necessary things to compile this special page (id). However, the script is not perfect and can (currently) generate reference files only, and in this many links just won't work.

If you have an Apache webserver with PHP installed, you can use livedocs: Open the live.php in your browser (on the webserver, not the local directory itself!) and browse through the manual - the pages are created on demand, most times as fast as 1 to 2 seconds.