Kick-starting a DocBook Project

When I started writing XMPP: The Definitive Guide, I switched from LaTeX to DocBook as my writing tool, mainly because DocBook was O’Reilly’s suggested format. After a few months of writing with DocBook, I started getting quite attached to the format: not only does it force you to separate presentation from content, the strict XML format allows you to easily write tools to transform and validate your document. For example, for the XMPP book, we had several short Python scripts that checked whether the stanzas used in the book were well-formed, whether all web URLs were valid, … Today, I use DocBook for practically all of my documents. Because getting a DocBook environment up requires putting together quite a few pieces from different places, I created a “DocBook kit” to be able to start writing a new DocBook project without much hassle.

Starting a DocBook project requires a few elementary tools to be installed:

To use the kit, simply drop it in the directory of your project, and create a minimal Makefile such as the following one:

Besides tools, the kit also provides a customization layer around the standard XSL stylesheets. These customizations change fonts, spacings, and other presentation parameters for the output document. You can use these as an example on how to make your DocBook document look the way you want. Detailed information on using and customizing the DocBook XSL stylesheets can be found in Bob Stayton’s DocBook XSL: The Complete Guide.

The DocBook kit is available from my Git repository (or on GitHub, or as a ZIP file), and comes with an example of a simple project using the kit. More tools and features will be added in the future.