==== 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 * CVS Check out the PHP manual anonymously: cvs -d :pserver:cvsread@cvs.php.net:/repository login (password is "phpfi") cvs -d :pserver:cvsread@cvs.php.net:/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 phpdoc@lists.php.net 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.