Andy Chase

Back when I started this site, my intention (aside from trying to keep up daily entries and seeing how much traffic I can generate) was to build out a personal blog system that would give people a simpler alternative to Slash or PhpNuke.

Well, at the end of this month it'll be three months since I started the site. I've done a lot of tinkering, but I have to confess I haven't kept other hypothetical blog administrators in mind. I'm guilty of a couple of kluges here and there, and documentation is poor at best.

An e-mail from a friend yesterday got me thinking about cleaning this thing up for public consumption once I get around to finishing the photo thumbnail indices. For one thing, I had an OOP epiphany a couple of weeks ago - I've been using PHP classes for some time now, and I've written a few of my own, but I was still thinking of them in terms of clumps of functions (which they are) as opposed to properties and methods of an "object".

I've been struggling with the whole "object" thing since I picked up a "Teach Yourself Java in 21 Days" book about 5 years ago, when the most recent language I had programmed in was C64 Basic. I read the examples and understood them on a basic level, but it wasn't until this year with PHP that I stopped wondering "Why would I want to write a program to turn a motorcycle on and off?" Such is the life of a self-taught programmer.

Even after that, the classes I wrote myself weren't really very useful in OOP terms; object methods would depend on global variables rather than object states, or they would be so specific as to limit the class' usefulness in future projects.

But, I think I get it now, and I should probably go back over the scripts that make up this page and see if I can't simplify things a bit with a nice blog class.

The other thing I've been kicking ass with lately is authoring in DocBook, which you may recognize from HowTos of the Linux Documentation Project. DocBook itself is a piece of cake to learn, actually; Norm Walsh's O'Reilly book on the subject (including complete tag reference) is freely available in its entirety online, and if you learned to code HTML by hand, jumping into a text editor and using the DocBook XML spec is no big deal.

Where things get hairy is when you go to set up a processing environment to transform DocBook into HTML, LaTeX, RTF, or whatever. I wound up using Jade, and it took me the better part of a day to get Jade, the DocBook DTD, and the DocBook DSSSL stylesheets to play nicely together... and I still don't fully understand what's going on. But I do love that whole XML separation of content from presentation thing.

So, at work I've been writing a new PHP class for some database operations, and doing it properly this time; the class will be easily reusable by future projects, and make code easier to follow. At the same time, I've been documenting the class in DocBook as I go. So far this seems to be a much better methodology than trying to pound out documentation after the script itself is finished. When the next big project is looming around the corner, documentation tends to get the short end of the stick. By documenting as I go I can be a little more thorough, and sometimes the act of thinking a function through will help me see a better way it can be implemented.

Anyway, I'm thinking maybe I should take a similar approach to this blog system... put commonly performed tasks into a properly formed class, and document it so that people can use the API (wow, am I actually talking about designing an API?) to easily extend its capabilities if they want to. And of course release it to the public.

Should be interesting.