AsciiDoc: Text based document generation
Saturday, July 28th, 2007
I write a lot of documentation for various articles and projects. Usually, I’ll use DocBook for writing that documentation. DocBook is an SGML/XML dialect for writing articles, books and other writings. It’s pretty extensive, and it can do a lot. It can export to LaTeX, HTML, PDF and a variety of other formats. But it’s also somewhat tedious to write, with the many and long tag names.
Some time ago I searched for an alternative to DocBook. Something more simple. My wish was for something as simple to write as, say, Wikipedia’s Wiki syntax.
During my quest for the ultimate document markup tool, I came across reStructuredText; a simple text-based format used by (amongst others) Python programs to put document markup in Python source code. Though reStructuredText is pretty good, I found it a bit limiting. It doesn’t seem to support exporting to PDF (unless you want to pass the generated HTML through a HTML2PDF converter) and its syntax is kind of limited. Another problem is the fact that it’s not easy to distinguish different headings because they all use a bunch of ‘=’s, ‘-‘s, ‘~’, etc surrounding the headings.
Just the other day I found AsciiDoc. AsciiDoc is very similar to reStructuredText, but it supports more formats. It can convert to HTML, PDF en DocBook (which in turn can be converted to many other formats). It also supports Wikipedia-like ‘== heading ==’ headings. It’s very readable. It’s also a lot faster than DocBook.
Here’s a little example of a document marked up with AsciiDoc:
PHLite User Guide ================= Ferry Boender v0.1, Jul 2007 About ----- This document serves as the User Guide for PHLite v0.1. Introduction ------------ PHLite is a lightweight, no-nonse, easy to use web development framework for PHP. Most of the currently big frameworks focus on Web2.0, design patterns, REST-fullness, MVC and other 'hip' paradigms. Often, they are too strict in enforcing these methods and therefor restrict the developer. Getting Started --------------- This chapter should help you get started using PHLite. === Requirements === PHLite requires: * PHP 5.1.0 or higher === Basics ===
Very clear, isn’t it? The example above produces this HTML document. And, yes, it can also generate automatic Table of Contents for documents (including HTML), something that seems to be missing from many documentation generators.