Docbook: The Definitive Guide

chromatic has reviewed O'Reilly's DocBook. Written by Norman Walsh and Leonard Muellner the book is: "A hefty reference of DocBook Elements and Entities, with an emphasis on customization and configuration -- if you know what that means, you'll find this book useful."

DocBook: The Definitive Guide
author	Norman Walsh & Leonard Muellner
pages	652
publisher	O'Reilly & Associates, 10/1999
rating	8.5/10
reviewer	chromatic
ISBN	1565925807
summary	A hefty reference of DocBook Elements and Entities, with an emphasis on customization and configuration -- if you know what that means, you'll find this book useful.

DocBook, a SGML DTD for technical writing and documentation, has been widely adopted by a number of organizations and authors. Many commercial and free tools support it, and the specification is under active development. DocBook: The Definitive Guide is the official documentation.

Content

The first section of the Guide discusses SGML and XML concepts, as well as the specifics of DocBook. Be warned that this is not a particularly gentle introduction -- familiarity with well-formed HTML will help, but the Guide is a reference, not a tutorial.

With that in mind, the introduction walks through creating, parsing, and publishing valid DocBook documents. As the specification is cross-platform and not tied to any particular editor, the discussion focuses on the logical divisions and elements and practices of editing a document, rather than the particulars and mechanics of using a particular tool. The Parsing chapter gives solutions for some of the more common validation errors ("DTD not found", "misspelled tag", et cetera). The Publishing chapter zeroes in on stylesheets, focusing on DSSSL and the Jade utility. The authors demonstrate a stylesheet based configuration which will simplify the customization and publishing processes for different output formats.

The bulk of this book is a reference section which lists DocBook elements alphabetically. Each element has a content model lifted straight from the DTD, a list of applicable attributes, a list of parameter entities in which the element occurs, a description of what is is and where it might be used, processing expectations, and examples of its use mentioning any gotchas. Some elements are very simple, while elements higher in the hierarchy have much more complex requirements and nuances. Deprecated elements are marked with the appropriate version of the specification, with valid replacements suggested.

Each parameter entity has a synopsis and a description, listing all of the elements in which it occurs. Finally, each character entity is listed along with its Unicode number, a glyph, and the ISO decription. Characters are listed by character set, in alphabetical order.

The final section wraps up odds and ends in Appendices. This includes a section on installing the DocBook DTD, a discussion of the past and future versions of DocBook, and a useful list of additional resources (including pointers to SGML and XML tutorials). Another appendix is devoted to the differences between standard DocBook and XML. The included CD-ROM contains the complete SGML and HTML versions of the Guide itself, various DocBook DTDs, stylesheets, and applications mentioned in the book.

Pros and Cons

The Creating section includes an enumeration of the categories of DocBook elements. This includes sets, lists, and components. It would be nice to have a comprehensive list arranged hierarchically, in addition to the alphabetical reference. (Occasionally an author might want to search for the correct element in a specific context. Why not?)

Including a troubleshooting section, so to speak, in the Parsing chapter was an excellent idea. One might almost conclude that the best way to think of DocBook is as a code library instead of a huge tree of entities and options. (The Customization chapter bears this out.) The authors also present various ways to accomplish specific goals, always with an eye out for the best and most flexible option.

As mentioned before, however, the tutorial value of the Guide is low, unless you're already comfortable with SGML or XML. DocBook's probably not the place to start out anyway, but someone who needs a quick introduction to DocBook for whatever reason ought to look elsewhere first.

Summary

You may never use all of the information found here -- but if you're developing a customization layer, building stylesheets, or just using DocBook to mark up your writings, you'll find this book invaluable. (If you're the kind of person who can read the DTD and absorb the meaning there, you might not need it.) For anything more than casual use of the DTD, this is the first and last place you'll look.

Table of Contents

1. Introduction
2. 1. Getting Started with SGML/XML
   2. Creating DocBook Documents
   3. Parsing DocBook Documents
   4. Publishing DocBook Documents
   5. Customizing DocBook
3. Reference
4. 1. DocBook Element Reference
   2. DocBook Parameter Entity Reference
   3. DocBook Character Entity Reference
5. Appendixes
6. 1. Installation
   2. DocBook and XML
   3. DocBook Versions
   4. Resources
   5. What's on the CD-ROM?
   6. Interchanging DocBook Documents
   7. DocBook V3.1 Quick Reference

Read this book online at Docbook.org.