All in the <head> – Ponderings and code by Drew McLellan –

So That Was 24ways

It feels like a lifetime ago, but that, my dear friends, was 24ways. In a month that taught me the unexpected pressure or a rolling daily release schedule, and forced me to call in pretty much every favour going and then some, we somehow managed to pull it off. I speak no word of a lie when I say my local Starbucks started offering me a discount last month. Tough work, but a whole lot of fun.

So I owe a massive debt of thanks (and a good few beers at SXSW) to all the authors who contributed throughout the month. There’s really no way it would have been possible – or quite so successful – without them.

I based the whole site on Textpattern as my small publishing system of choice, which did a reasonable job. I was able to create custom fields for things like the date graphic on the home page, made use of excepts for the first time, achieved what I needed to with the categories and sections and whatnot and all was good.

The two major stumbling blocks for me were Textpattern’s implementation of RSS and ATOM feeds, and hitting the limitations of Textile.

The problems with RSS

A few days into the project, I began to get reports of problems with the RSS feed. To be honest, although I was subscribed to it myself, I’d never bothered to validate it and give it a really thorough check – after all that’s why we rely on software to do this stuff. It turns out that my aggregator is rather forgiving of errors, and the RSS feed that Textpattern was putting out was invalid. The problem seemed to arise from failing to encode HTML entities correctly – a problem when publishing lots of code examples.

The ATOM feed was fine, so I thought no problem, I’ll just find the inconsistency between the RSS and the ATOM scripts, fix the problem and submit a patch back. Unfortunately, the RSS and ATOM scripts appear to be completely disparate, and after 15 minutes of hacking around at it I got absolutely nowhere. I’m grateful for the software and all, but those scripts are an unholy mess. I need to spend some time and see if they can be rewritten and unified. ATOM and RSS are too similar to be two completely different scripts.

My immediate solution? I switched the RSS feed to except-only, which I hated to do, but got the feed working for everyone again.

Textile for technical publishing

Probably the biggest lesson I learned throughout the process was that Textile isn’t so hot for technical publishing. There may be some tricks I’m missing, but I had a real hard time when it came to code samples.

The most time-consuming thing was getting the white-space right. Textile relies heavily on white-space, and it was a constant battle to stop Textile doing stuff like wrapping lines of code in paragraph tags. I had to painstakingly reformat every line of code by hand to prevent any unwanted transformations from white-space alone.

Common problems were:

CSS ID selectors would get turned into single item ordered lists, and Textpattern uses the # symbol to indicate an ordered list item. I guess the fix would be to ignore this rule inside a code block.

Common JavaScript character sequences get transformed into something strange, as Textile uses a lot of character sequences which are highly rare in written English, but not so rare in JavaScript. An example would be the use of the plus sign for inserted text – causes problems when demonstrating string concatenation. Again, this sort of stuff should be ignored within a code block.

The other main issue I had was that no every Textile device allows for the application of an arbitrary class name. Or at least, if they do it’s not properly documented. This was particularly a problem when it came to using Microformats, which rely heavily on classes. This left me mixing and matching Textile formatting with regular HTML, which was fine for my purposes, but would cause problems in situations where you’re not always planning to transform to HTML.

Of course, nothing was compelling me to use Textile – I could have happily continued using Textpattern and formatted everything myself in HTML – but I figured that even with messing around that would take me longer.

Textile is immensely useful for so many things, but having hit some of its limitations, I think that it could really benefit from almost being a project of its own, with people focussing on developing it and maintaining the various releases and applications. Its adoption is becoming so widespread, I think without being actively maintained we’ll end up in a mess in a few years time. And Textile is something the world really needs.

Anyone up for it?