Updating PHP docs to the new markup

Several PHP extensions have documentation for OO-style APIs which is written as if the documentation was a procedural API. A good example of this was ext/soap, but also ext/rar seems to be using the old markup too. So, I'm going to take this as my example. If you go to, and look over the methods of the Rar class, you can see they're documented just the same as the functions rar_close(), rar_entry_get(), etc. This isn't handy and makes the search less useful. There is a new variant of the DocBook markup which makes more sense for OO APIs, and it should be converted. This is basically a copy and paste job.

You will need:

Check out the PHP manual anonymously:

cvs -d login

(password is “phpfi”)

cvs -d checkout phpdoc

Go into phpdoc/scripts/docgen. In there, there's a script called docgen.php, which can use some magic reflection pixies to work out the API for an extension. It will then make a blank set of documentation for all the functions, classes and methods it finds.

/path/to/php5.3 docgen.php -e rar -o myrardocs

You'll end up with a pile of XML files in myrardocs/. These are blank, and you can copy the relevant details from phpdoc/en/reference/rar/ into the appropriate places - it's pretty self-explanatory from this point on. Once you've got going, you can move the original phpdoc/en/reference/rar/ out of the way and put your own in its place, and try compiling the manual to see if it works. Check out for a proper explanation on this part, but it's basically:

cd /path/to/phpdoc
/path/to/php5.3 configure.php

If it complains, then you've got something wrong and it needs fixing. If not, you can go on to compile the actual manual:

/path/to/phd -d .manual.xml

That'll compile the manual in various different formats - the one you're likely interested in will be in phpdoc/html/. You can also compile only part of the manual if you want:

/path/to/phd -d .manual.xml -t chunkedhtml -p book.rar -o ~/phpdocs/output

The -p option specifies the XML ID of the section you're wanting to generate. You can find this in book.xml in the en/reference/rar/ directory, if you're using that extension.

Once you're happy with it, tar it up and post it online somewhere, and send an email to with the link. Someone should then check it out, and if it's all good, you can acquire a CVS account (or karma if you have one) and commit it.

TODO: Describe fixing user notes. TODO: Describe how to deal with old CVS history… links to old files should be in the commit message at least.

doc/articles/updating-markup.txt · Last modified: 2011/04/06 12:59 (external edit)