DocBook 5.0: The Definitive Guide Updates

Yesterday, I published a new version of DocBook 5.0: The Definitive Guide (TDG5). Over the weekend, I finally sat down and updated chapters 4 (Publishing DocBook Documents) and 5 (Customizing DocBook). There's still not much in chapter 4, but chapter 5 is much improved, I think.

The element descriptions in the reference are now up-to-date with the official release of DocBook V5.0.

In the original Definitive Guide, the content models were expressed in DTD syntax. The DTD, in turn, was constructed from parameter entities which are really a string substitution or macro language. Expand all the parameter entities, reformat the text, and you get something that's terse, but relatively easy to learn to read.

In DocBook V5.0, the content models are expressed in RELAX NG. While RELAX NG has a compact syntax, the patterns aren't simple string substitutions. In addition, a few of the patterns exploit co-constraints which are tricky to read. One option for displaying them is simply to leave all the patterns in place:

element biblioid {
   db.biblioid.attlist,
   db._text
}

But that says more about the underlying structure of the schema than it does about what attributes are allowed on bibliod and what content model it allows. If you want to know what can go in a bibioid, you don't care what I called the patterns.

The solution I reached eventually was to expand the patterns, simplify them where possible, and present them as lists:

That works, mostly, but it's a bit hard to read when the list gets very long. For many DocBook elements, the list of inlines is quite long: I selected biblioid for this example because it's relatively short.

Recently, I decided to try grouping related elements in the list:

That seems to be an improvement. In a JavaScript-aware browser, you can click on the graphics to expand part or all of the list, for example, the indexing inlines:

If you click the “”, the grouping is removed, restoring the original presentation. On a non-JavaScript-aware browser, all of the lists are shown expanded.

I think that's an improvement. And it works across all the browsers I tried.

Comments and suggestions most welcome.