PHP_CodeSniffer DocBook documentation

I started writing the documentation for PHP_CodeSniffer today. Before I can release a stable version, I have to make sure there is some documentation in the PEAR manual (peardoc).

The catch? The PEAR manual is written in DocBook XML and is pretty hard to get working, at least on OS X. Chapter 21 of the PEAR manual describes how to write documentation and the software you need to install to get it working. The section Required software reads:

Unfortunately, installing that software can be difficult under some circumstances. If you are unable to get it working, don't use that as an excuse for not writing documentation. There are two test servers that automatically download peardoc from CVS and build the manual. Any parsing errors your changes cause will show up in the logs the next time the build happens:

That didn't fill me with confidence.

Checking out peardoc from CVS was easy, but of course, my first attempt at trying to compile the manual failed; peardoc couldn't find my DSSSL stylesheets. I was not prepared to commit any documentation unless I could test it locally.

Luckily for me, I started playing around with peardoc 12 months ago, when work was a little less busy. Apparently, I had been successful in installing OpenJade and the DSSSL stylesheets. The one thing missing was the command to tell peardoc where those stylesheets were.

The Testing documentation section of the PEAR manual says that the following commands will build peardoc on your local machine:

peardoc$ autoconf
peardoc$ ./configure --with-lang=en
peardoc$ make html

I'll describe that as mostly right. If peardoc doesn't know where your stylesheets are, you'll need to tell it, like this:

peardoc$ autoconf
peardoc$ ./configure --with-lang=en --with-dsssl=/path/to/docbook-dsssl/
peardoc$ make html

I got the DSSSL stylesheets from a Fink package called docbook-dsssl-nwalsh, so my stylesheet path is /sw/share/sgml/dsssl/docbook-dsssl-nwalsh/.

After several minutes, the PEAR manual was finally mine.

I started by porting over the docs about PHP_CodeSniffer that I had put up on the MySource Matrix website. This was my first real attempt at writing in DocBook format. I'll post about my impressions when I've finished writing all the docs, but first impressions are pretty good.

So now my first set of docs have been committed to peardoc. Now to wait for the next test manual generation to see if I did things correctly. It's a nervous wait!

UPDATE: the docs generated correctly and are now available in the PEAR manual.