Docbook 5.0 in 5.0 minutes

I quite like Docbook. The syntax is simple enough to pick up quickly, which means I can churn out documents without much effort, and more importantly, without having to fire up a bloated office suite. Furthermore, the documents that it produces look great, which is far more than I can say for anything I’ve put together with a wysiwyg word processor – I will freely admit that I have no artistic skills, whatsoever.

The biggest problem with Docbook, however, is the tools needed to convert it from xml to other formats (eg, pdf, html, etc) – or rather – the documentation of the tools, ironically enough. Most of the information out there seems to have been written to be so platform independent that it’s next to useless for any real-world situation.

So, in the interests of hopefully saving someone the hours that I’ve spent trying to get this working for my specific case, here’s a quick guide to writing and publishing a Docbook 5.0 document, on Debian sid.

Firstly, get the Debian package source to xmlto and apply the patch attached to Debian bug 416622; this gives xmlto support for dblatex, as it currently expects to use passivetex and it has been removed from Debian. Hopefully the patch will be applied upstream and this step won’t be needed in the future.

Install the following Debian packages: docbook, docbook-xml, docbook-dsssl, docbook-xsl, dblatex, xsltproc. Build and install the patched version of xmlto, and install any dependencies it requests.

Now, a simple docbook document. Write this to index.xml:

<?xml version=”1.0″ standalone=”no”?>

<!DOCTYPE book PUBLIC “-//OASIS//DTD DocBook XML V5.0//EN”
“http://www.oasis-open.org/docbook/xml/5.0b5/dtd/docbook.dtd”>

<book xmlns=”http://docbook.org/ns/docbook” version=”5.0″>

<info>
<title>My book</title>

<author>
<personname>
<firstname>Paul</firstname>
<surname>Dwerryhouse</surname>
</personname>
</author>
</info>

<chapter>
<title>Introduction</title>

<para>This is the first paragraph.</para>
</chapter>

<chapter>
<title>Stuff</title>

<section>
<title>Information</title>
<para>This is the first section.</para>
</section>
</chapter>

<chapter>
<title>Conclusion</title>

<para>This is the last paragraph.</para>
</chapter>

</book>

Note the DOCTYPE line. I can’t tell if Docbook 5.0 has been officially released or not. Wikipedia suggests that it is, but the 5.0 DTD is not available on the OASIS website, only a beta.

You can now convert this to html with:

xmlto html index.xml

…or pdf with:

xmlto –with-dblatex pdf index.xml

If you’re writing a huge document, and want to break it down into multiple files, then you can use XInclude:

<?xml version=”1.0″ standalone=”no”?>

<!DOCTYPE book PUBLIC “-//OASIS//DTD DocBook XML V5.0//EN”
“http://www.oasis-open.org/docbook/xml/5.0b5/dtd/docbook.dtd”>

<book xmlns=”http://docbook.org/ns/docbook” version=”5.0″>

<xi:include xmlns:xi=”http://www.w3.org/2001/XInclude” href=”info.xml” />
<xi:include xmlns:xi=”http://www.w3.org/2001/XInclude” href=”ch01.xml” />
<xi:include xmlns:xi=”http://www.w3.org/2001/XInclude” href=”ch02.xml” />
<xi:include xmlns:xi=”http://www.w3.org/2001/XInclude” href=”ch03.xml” />

</book>

The above example will then read in four files, info.xml, ch01.xml, ch02.xml and ch03.xml, which contain the information section and the three chapters from the first example.