Thursday, January 08, 2009

asciidoc isn't just for small documents anymore

I've used asciidoc for quite a while as a tool to generate small reports for clients. As I've discovered how easy it is, I'm also using it to keep notes. The lightly formatted (perhaps stylized would be a better word) text is better organized visually than simple text, and, if I need to turn it into typeset text, it's pretty easy to convert it into a range of formats: HTML, XHTML, PDF, RTF (and, from there, DOC), ODT, and more. I've tested its ability to create (LaTeX) beamer presentations and might use that regularly if I didn't stretch beamer a bit more than the asciidoc beamer translator supported at the time.

Yet I had fallen for the idea that asciidoc was for small documents, at least until I read Noah Slater's posting on the asciidoc mailing list saying he was using it to write a book that will be published by a professional publisher using their DocBook backend processes.

What do you need to use asciidoc successfully? I started using it on Windows with Emacs as my editor. I now use it on GNU Linux (Ubuntu, to be specific). Both work just fine. It seems easier to set up any backend processes on Linux, but your organization can set those up once and then users don't need to do that configuration themselves.

To get from asciidoc to PDF or RTF requires you have a DocBook toolchain. That's fairly straightforward on Linux; the main challenge is figuring out which alternatives you like. That's more of a challenge on Windows, but I have found the e-novative DocBook Environment (eDE) to be extremely easy to use.

Those of you who like HTML documents but struggle with the problem of distributing them by email (you have to attach any images as separate files and then rely on the recipient to manage them properly) might like asciidoc's ability to use data URIs. That means you can embed images inside the HTML file, so you only have the one file to distribute.

While you're looking at asciidoc, check out their examples using asciidoc to produce diagrams with graphviz, to typeset musical notation, and to create Web sites, in addition to simply creating articles and books.

Labels: , ,


Post a Comment

<< Home