LWN Review: DocBook: The Definitive Guide

[DocBook cover]
DocBook: The Definitive Guide
Norman Walsh and Leonard Muellner
O'Reilly, 1999
Reviewed February 16, 2000

DocBook is an up-and-coming standard for the formatting of technical reference materials. A number of publishers can accept it, as can the Linux Documentation Project and other free documentation efforts. As more people try to produce documentation for free software, they are going to go looking for information on how to use DocBook to that end.
Thus far, DocBook: The Definitive Guide is about the only option they have. That is somewhat unfortunate. This book is a high-quality reference work, but does not even really try to be a gentle introduction to DocBook, which is a tremendously complicated system. I came in hoping for something along the lines of Knuth's beautiful T_EXbook, but that book does not yet exist for DocBook.
So the beginning DocBook author is going to have to start by looking at a lot of examples. Fortunately, DocBook: The Definitive Guide is published under an open content license. It comes with a CDROM containing the SGML source for the entire book; it can also be obtained from the DocBook.org web site. Given that DocBook is an enabling technology for free documentation, it's fitting that the guide be free as well.
The book is divided into two distinct parts. The first section, about 110 pages, provides a quick introduction to DocBook. There is some historical discussion, an overview of elements, entities, and attributes, an overview of some of the more important elements, a section on the validation process (which DocBook authors learn to loathe), a very quick summary of available tools, and a section on customizing DocBook. The material that is there is all clear and well written, but the space allotted is nowhere near sufficient to cover the material. DocBook is a complicated beast!
The core of the book is over 400 pages of straight reference material. Each possible element is presented in alphabetical order, in a highly formalized way. See, for example, the entry for <ListItem>. If you are an intermediate or above DocBook author looking for information on how to use a particular tag, this is great stuff. You get what you're after, quickly, and without having to dig through an index. If, instead, you're wondering "how do I make a bulleted list?" life will be harder.
To the extent that this review seems critical, it is probably unfair. DocBook: The Definitive Guide is only one book, not three. It is better that it be one well-done book, rather than a mishmash of two or three mediocre ones. In any case, if you are going to be writing with DocBook, you need this book. That's all there is to it. It's a top-quality reference, which is exactly what DocBook authors need.
Now if somebody would only write DocBook: the comprehensive introduction....
--jc