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?
Comments
I’m a Markdown man myself. Is Markdown a bit too simplistic for what you were doing with 24 Ways? (Which, by the way, was great: many thanks guys.)
Thanks for all that work Drew… great site and even better resource.
Great advent calendar, I learned some interesting techniques. Thanks for your hard work Drew, and all the contributors as well.
That 24 ways was pretty interesting indeed, both in content and in concept.
Paul already mentioned Markdown, but I want to add that this syntax is a perfect fit for technical documents containing code: it has been created with that exact goal in mind. PHPÂ Markdown (made by me) works reasonably well with TextPattern too.
Being a textile guy myself, I can empathize with you on most of the above issues. But not the class issue – all you need to do is enclose the class name in parens between the tag and it’s closing period, like this:
p(classname). Paragraph text.There are lots of neat bits to textile, But they aren’t all that well documented. The best docs I know of are from _why, who created the RedCloth textile library for ruby.
But what really gets me is there’s no way to create a blockquote with more then one paragraph within it. ++ to getting textile a bit of help.
Over on Clagnut I use Textile integrated into my own CMS. I found I had to hack it quite a lot, especially for code samples, as you pointed out. The most reliable way I found was to convert
@symbols intocodetags right at the beginning of the function and then it seemed to behave much more as expected.For larger code samples I use an excellent plugin called glx_code (direct file download). You can keep all code in separate text files and in the page the code is displayed in an ordered list the way that Dunstan introduced in mid-2004 (scroll down that page a bit).
Andreas – that looks cool. Thanks for the link.
If I would have known so many different types of code were causing problems, I wouldn’t have wrote about something that involved HTML, CSS, JavaScript, and PHP all in the same article.
Nevertheless, you did an excellent job putting everything together. Ever consider project management?
Yea, anyway, I think at SxSW you should never have to pay for your beer. I’ll be looking forward to chillin’ with everyone who contributed.
Regarding your RSS problems: we don’t know about issues like these if people don’t report them. A post on the forum is the best place to start.
I’d be interested in where you’d think the first move in expanding support of textile would be. I’ve hit many of your issues above while using textile, I see that it could use work and more attention both on the documentation end as well as the development end.
Unfortunately I’m not close enough to either project (textpattern or textile) to know what actions would be helpful and what would be harmful and break too much away form the support it currently has.
I had lots of similar problems with textile when putting together my code highlighting plugin for textile. I had to do a fair amount of hacking to get textile to even slightly respect the notextile blocks…
This was all quite a while ago though and I haven’t upgraded to the latest textpattern (and therefore textile) yet so I’m not sure if it’s still useful information or not…
I wonder if Feedburner could have sorted out that feed issue for you? (SmartFeed) maybe?) A bit of a workaround I suppose, but you only needed the feed for a month or two…
Thanks for the daily December fun. Can we expect “24ways 2006”? Maybe answer that when you’ve got some more distance from 2005… I’m sure your immediate answer is “hell, no.”
Has this caused you to go to Starbucks? Give it a break Drew. You’ve suffered enough.