Docbook XML made easy

In a slightly crazed moment today I decided to write some documentation. Having used Docbook before for my UML Bridging Tutorial, I thought I’d pay it another visit.

As I was lazy and wanted a quick GUI way to do markup, I found an XML editor from XMLmind. It is written in Java so should run in most places and, except a few quirks, seems really good. An hour later I had a few chapters written in Docbook markup ready to be published.

However, I couldn’t find many sites that gave a quick and easy example of how to convert from XML to PDF or HTML. It seems that for Docbook XML you need a toolchain, which means understanding in a lot of detail what each stage does. With Docbook SGML there were a number of nifty docbook2x programs which did the work and gave HTML, PDF or text output (amongst others).

To duplicate this quickly and easily with Docbook XML, I found that xmlto and dblatex were the solution. To create an HTML document, it couldn’t be easier than:

# Make a one page per chapter HTML book
$ xmlto xhtml MyDocument.xml
# Make a one page HTML document
$ xmlto html-nochunks MyDocument.xml

For PDF, it is as simple as:

# dblatex defaults to PDF
$ dblatex MyDocument.xml

Both of these packages (as well as the Docbook stylesheets) have been available in Ubuntu since 8.04. In order to make (X)HTML output prettier, you might like to look at this page which gives a great tutorial.