PHP_CodeSnifer coding standard tutorial updated

In my last post, I mentioned that the current PHP_CodeSniffer manual doesn't have any information about using an external standard. The manual, and coding standard tutorial, assume that the standard you are writing and testing with is located within the main PHP_CodeSniffer directory structure. This is not normally the case, so I have updated the manual to be a little more realistic.

The coding standard tutorial now takes you through the process of creating an externally managed coding standard rather than instructing you to create your standard within PHP_CodeSniffer's Standards directory. This not only documents the usage of external standards, but also makes it much easier for would-be standard developers to get started.

The updated tutorial wont be available on the PEAR site until Sunday/Monday, but you can view it on Brett Bieber's build right now. From next week, you can view it at the normal place.

As a side note, creating and compiling the manual (peardoc) on Linux is a lot easier than on OS X. I am now using a Fedora 8 VM for all my PHP_CodeSniffer development and documentation work and I highly recommend this setup.

Screen capture with PHP: Useful for documentation

Pierre-Alain Joye has posted about a couple of new functions he has added to GD (to be released in 5.2.2) that will allow a script running on Windows to capture the entire screen or a single window. He includes some sample code to capture an IE window after navigating to a specific URL.

These new functions got me thinking about documentation for MySource 4.0. We've made it a priority to be able to customise a large number of interfaces in the system, as well as removing entire pieces of functionality all together. This obviously makes documentation hard as every user may be looking at a different interface with different functionality.

While we haven't sat down and tackled this problem yet (it's a bit too early at the moment) we have thought about possible solutions in the past. One of the things discussed was generating documentation by putting together different parts of manuals depending on what functionality is present in a system. We could also read XML files that define the interfaces to determine, for example, the creation wizards that are in use and what functionality they implement.

Even if we can get the words together to describe a system, we still only have a generic set of screenshots to use in a manual. I'm hoping that this new functionality in GD will allow us to generate custom screenshots, leading to customised manuals for each system or each standard configuration of MySource 4.0.

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.