==== 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.