So a few days ago I took another look at Xilize, and man, is it great. We’re preparing a release for Flying Saucer, the XHTML/CSS renderer project, and I needed to update (and write) a bunch of documentation. The last docs were written in plain HTML, and I’ve gotten to the point where I’d rather pull my nose hairs out with a paperclip than code in plain HTML. But I digress. Xilize is a text-markup syntax and an engine that converts the marked up text to clean XHTML. There are Xilize tags for basically all the HTML you need, and if necessary, you can always drop out to HTML syntax when necessary. But the kicker is that for the most part the syntax is very light, meaning you can express your intention to format pages with very little extra visible baggage. I was able to just write what I wanted to say, and have it come out the way I wanted.
The idea follows the Wiki idiom of basing formatting commands on plain-text entry, such that writing a document is similar to writing an email. Paragraphs need no extra tags and lists just need a * or a # mark, and so on. The actual syntax Xilize uses is apparently based on Textile, which I haven’t used myself. Whatever the origin, I was able to get a decent-looking User’s Guide written much effort. Or rather, the effort was in working on the content, which is just plain right.
I then tried creating a PDF for the document. This was interesting because I got to look at a DocBook toolchain once again. Everytime I look that up, man, is it a lot of work to get running. I ended up using the following chain: Xilize formatted text -> XHTML (Xilize) -> DocBook XML (html2db.xsl) -> XSL-FOP -> PDF. The XSL was converted using XSLTPROC. That all worked well, but as you can imagine, it took awhile to figure it out. The downside is that if you don’t like the formatting you end up with, you have to read alot about what formatting is allowed through FOP, which, let me tell you, is a lot. That meant I had a nice PDF but a bunch of work ahead of me before I got a layout that I really liked.
But–shameless plug here–our upcoming release of Flying Saucer now supports rendering to a PDF file, instead of just rendering to a graphics canvas (Java2D), which was our original target. This means I can create XHTML (via Xilize) and let the CSS formatting indicate how the pages should be laid out. We don’t have perfect control over the output, but as CSS was already in my toolkit, it was an easy decision to make. The end result, as PDF is not bad for a few hours writing and a little bit of formatting.
All of this was possible because Xilize is available under the GPL, and what’s more, there are excellent docs for it. I want to stress that the DocBook toolchain is impressive and well-documented, and a lot of people have worked hard on making it work right. jEdit’s docs are written in DocBook, and I think it’s one of the best examples around of how to write documentation for an open-source project. That said, Xilize simply rocks. I’m actually so relieved at not having to struggle with some documentation tool that I’m looking forward to extending our documentation, and seeing where I can help out with other FOSS projects I’m interested in. And, who knows, might be time for a website rewrite of my own…
(originally posted an this JRoller blog entry)