Docbook is a widely used XML schema for technical documentation(*). It is an open source project with a great deal of supporting infrastructure and documentation. Start with the Docbook FAQ and the canonical text DocBook: The Definitive Guide (since we are using Docbook 4.x, read version 2.0 of the Guide).
Like LaTeX, Docbook is a structural description of a document. Docbook does not define formatting. Using XSL stylesheets, Docbook documents can be transformed into many other formats such as XHTML, PDF, Unix nroff man pages, and Windows HTML Help.
Khronos has agreed to use Docbook as the format for new man pages and technical specifications created within the group. This document captures basic information about Docbook and the toolchain required to use it.
(*) Actually, there are SGML and Relax NG schemas for Docbook as well. However, for Khronos' purposes we concentrate on the XML schema.
Since Docbook documents are XML, it is possible (and perhaps desirable for smaller documents) to simply use a text editor and mark up XML by hand. Emacs is reputed to have a Docbook and/or XML editing mode which may be useful.
There are a variety of free and commercial XML editors. Some are described in the Docbook FAQ. We have experimented with the free Standard version of XMLMind with some success; unlike many of the other options, XMLMind understands the Docbook schema and can render Docbook documents in a WYSIWYG-like fashion, in addition to the straight XML structure editor.
There are many versions of the Docbook XML Schema. We are currently using Docbook 4.3 with MathML 2.0 support. See the DOCTYPE declaration in the sample documents for the specific DTDs.
To transform Docbook documents into final viewable formats, we use the standard Modular Docbook XSL stylesheets (version 1.69). These are available prepackaged for modern Linux systems (although you may have to manually select the packages) as well as for the Cygwin environment on Windows. We are using version 1.69 of the stylesheets.
(Note: need links to Cygwin / Red Hat / other Linux distro? packages).
The Docbook 4.3 DTD is also prepackaged for most systems. Some additional work is required to install the Docbook 4.3+MathML 2.0 DTD (details to be added). (Note: need links to Cygwin / Red Hat / other Linux distro? packages).
To transform a Docbook document with the XSL Stylesheets, a processor like xsltproc or Saxon is required. Again, xsltproc is prepackaged. (Note: again, need links to Cygwin / Red Hat / other Linux distro? packages).
A simple example package containing a Docbook document (sample man page) and Makefile to transform it are here (link TBD).
Last modified August 13, 2006 by Jon Leech