Justin Martin

All of my recent blog posts seem to start with “For some time”, or similar. I suppose the reason for this is that I’m always writing posts in retrospect, having worked on an issue long enough that I find it interesting enough to blog about. I’m forced to do the same with this post, because the project I’ll be discussing is one I’ve been working on for over a year now, with very little success until now.

For some time, I’ve been working on updating the documentation for PHP-GTK, which is horrendously out-of-date. Initially, I was trying to simply update the existing documentation, but it quickly became clear that a complete rewrite was in order.

Now, I realize that wanting to scrap a body of work is all-too-common for new developers, who think a different approach would be better, or that the existing work is a pile of hacks upon hacks. I’d be lying if I said that wasn’t my thought process now, but it goes so far beyond “hacks upon hacks” that I feel I’m justified in this position.

Love at First Sight

When I first encountered the PHP-GTK project, I thought it was fantastic. It was love at first sight, really. I’m a big fan of PHP, for obvious reasons, and had always wished I could use my existing skillset to develop graphical desktop applications. I’d messed about with CLI applications, and even played with ncurses for a time, but when I found that I could develop full-fledged GUIs using a mature toolkit, I was ecstatic.

Let’s just say that learning wasn’t easy. I suppose it never is, but in this case it was exceptionally difficult. When learning to develop in PHP, I suppose I was spoiled by the outstanding level of quality that the main PHP manual has. When you need to learn something, you needn’t bother with third-party tutorials most of the time; all you need do is pull up the manual page for that extension, and you’re off. There’re full-fledged introductions for most extensions, and a plethora of examples for every class and function. The notes section of each page is also a fantastic thing; if it’s not explicitly documented, you can be sure it’s in the notes.

So, when I started to use PHP-GTK, you can imagine I was stunted a bit by the lack of comprehensive and up-to-date documentation. Now, I don’t want to be overly harsh, as I’m sure that when it was being worked on, it was a great manual. However, because it fell so far out of sync with the main manual, in terms of format and style, nobody really wants to maintain it. There are updates to specific classes every now and then, but for the most part it’s unmaintained.

Patches are Welcomed

Naturally, nothing will get done about the problem unless someone takes the initiative to make it happen. In this case, I decided to be that person. I was familiar enough with PHP-GTK and its back-end to reasonably document it, so I took a stab at doing so.

At first, I thought it would be a simple matter of updating the existing documentation. However, because the main PHP manual had drastically changed its format, – if I recall correctly, this was an upgrade to Docbook 5 – I found that updating PHP-GTK’s existing documentation would simply not suffice. Sure, there are ways to hack together a migration from the old format to the new, but it would result in old, ugly markup being carried over, and would probably be more work than it’s worth. In any case, the existing documentation is out of date in a number of areas, and hasn’t kept up with the major changes to PHP-GTK’s infrastructure.

My initial efforts were rather weak, in retrospect. I wasn’t familiar enough with the Docbook format to really generate a new set of documentation. Granted, I did have Michael Maclean‘s help for a time, but our efforts fell flat fairly quickly.

After becoming rather fed up with the project, due to a general lack of progress, I dropped my work into a repository – which was oddly linked to by a couple of people – and set about other projects.

Interest Anew

A couple of weeks ago, I decided to take a stab at helping with the main documentation. My interest was largely borne of wanting to contribute back to a project which I have so heavily used, but also because I knew that gaining some experience and “karma” with the documentation team could help me in reviving my PHP-GTK project.

In the days prior to sending a message to the php.doc list, I had discussed with the doc team, in #php.doc on EFnet, the possibility of integrating the PHP-GTK documentation into the main manual. Most other extensions that are developed under the umbrella of PHP.net are documented in the main manual, so why not PHP-GTK? Doing so would not only reduce the work involved in bringing the documentation up-to-date, but would also bring with it an infusion of interest in the PHP-GTK project itself.

Getting the Ball Rolling

So, as per my mailing list message, I’ve created two branches in the phpdoc repository. One, at http://svn.php.net/repository/phpdoc/doc-base/branches/gtk-docgen/, which will house the temporary modification to the docgen script, to accommodate PHP-GTK’s current Reflection idiosyncrasies. Another at http://svn.php.net/repository/phpdoc/en/branches/php-gtk/, which will eventually contain the book for PHP-GTK.

A Note: If you would like to check out PHP-GTK’s documentation branches, please check out the doc-gtk module, which contains the appropriate externals.

Mark Skilbeck has graciously offered to assist in the documentation process, which is fantastic, because he’s apparently familiar with PHP-GTK from an internals point-of-view.

If anyone would like to assist in this effort, please feel free to join us in either the PHP-GTK channel on Freenode (#php-gtk) or the php.gtk.doc mailing list. I’m sure that once the skeletons are finished for the documentation, there’ll be lots of room for assistance with the documentation process.