Search This Blog

Wednesday, March 12, 2008

DocBook 5.0: The Definitive Guide Updates

DocBook is a very popular set of tags for describing books, articles,
and other prose documents, particularly technical documentation.
DocBook is an XML vocabulary normatively defined using RELAX NG and
Schematron. But DocBook is older than any of those technologies. It
was originally an SGML vocabulary described with the standard SGML
Document Type Definition, or DTD... I recently 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 [code for 'bibliod']. If you want to
know what can go in a 'bibioid' element, 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. Recently, I decided to try grouping related elements in the list;
that seems to be an improvement. [As implemented in the online book,]
In a JavaScript-aware browser, you can click on the graphics to
expand part or all of the list; if you click the '[x]', the grouping
is removed, restoring the original presentation. On a
non-JavaScript-aware browser, all of the lists are shown expanded..

No comments: