DocBook 5.0: The Definitive Guide Updates

Volume 11, Issue 28; 04 Mar 2008; last modified 08 Oct 2010

Better content, better presentation.

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:

biblioid ::=

  • Zero or more of:
    • text
    • alt
    • anchor
    • annotation
    • biblioref
    • indexterm (db.indexterm.endofrange)
    • indexterm (db.indexterm.singular)
    • indexterm (db.indexterm.startofrange)
    • inlinemediaobject
    • link
    • olink
    • phrase (db._phrase)
    • remark
    • replaceable
    • subscript
    • superscript
    • xref

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:

biblioid ::= [x] [+]

  • Zero or more of:
    • text
    • phrase (db._phrase)
    • replaceable
    • Graphic inlines [+]
    • Indexing inlines [+]
    • Linking inlines [+]
    • Ubiquitous inlines [+]

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:

biblioid ::= [x] [+]

  • Zero or more of:
    • text
    • phrase (db._phrase)
    • replaceable
    • Graphic inlines [+]
    • Indexing inlines [-]
      • indexterm (db.indexterm.endofrange)
      • indexterm (db.indexterm.singular)
      • indexterm (db.indexterm.startofrange)
    • Linking inlines [+]
    • Ubiquitous inlines [+]

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.

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

Comments and suggestions most welcome.

Comments

That's brilliant, Norm. I hate getting summaries when I want the element names, and getting element names when I want the summaries. This solution enables me to choose what level I look at. Great idea.

—Posted by Jeni Tennison on 04 Mar 2008 @ 08:11 UTC #

Very nice! Could be useful for all sorts of indexes also.

I'm trying to think of a way to re-establish grouping after I have clicked 'X' (short of reloading the page). deleteAll() is a bit too heavy-handed; IMHO self-annihilating controls are confusing. The need for a print-friendly layout can be fulfilled with a print stylesheet (<link ... media="print"/> or @media print { ... }).

On the refentry for 'biblioid', I could not help notice that "doi" is described as "A document object identifier."

A DOI name is a "Digital Object Identifier". The object need not be a document or digitial, it is a digital identifier of any material object as well as of any abstraction (such as a unicorn or a FRBR 'work'). BTW, DOI is now an ISO Committee Draft, ISO/CD 26234.

—Posted by Peter Ring on 05 Mar 2008 @ 09:36 UTC #

For the next release, I'll probably make the "x" control non-destructive. I'll add enough metadata to the HTML so that I can reconstruct it in JavaScript, probably with class values on the list items or something. The ability to remove all the groupings was really an afterthought.

And I've fixed DOI, thanks!

—Posted by Norman Walsh on 05 Mar 2008 @ 01:19 UTC #

Yes, that seems very good. Thanks for the guide, and keep up the good work! :-)

—Posted by Rasmus Kaj on 05 Mar 2008 @ 01:35 UTC #