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 http://php.net/rar, 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:
- A recent PHP 5.3 is nice
- the PhD tool - follow the instructions on http://wiki.php.net/doc/phd/install
Check out the PHP manual anonymously:
cvs -d :pserver:email@example.com:/repository login
(password is “phpfi”)
cvs -d :pserver:firstname.lastname@example.org:/repository 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 http://doc.php.net/php/dochowto/chapter-configure.php 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 email@example.com 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.