DocBook NG: The “Absinthe” Release

RELAX NG can express constraints in the grammar that we could previously only express in the documentation. For example, biblioid has two attributes, class and otherclass, with the semantic that otherclass is required if class="other" and forbidden otherwise. In RELAX NG, we can enforce that constraint.

We can also tighten up constraints in content models. Consider table . In DocBook V4.3, we introduced HTML tables alongside CALS tables. To support this in the DTD, the content model for table had to be constructed so that it was the union of both models. This allows not only HTML tables and CALS tables but also hybrid tables that are neither HTML nor CALS. In DocBook NG, the two definitions are entirely separate: you can have CALS tables or HTML tables, but nothing in between.

DocBook NG attempts to solve the “ubiquitous linking” problem by allowing either linkend or href on most elements. So ulink doesn’t exist anymore, but you can say:

I prefer
<command href="/manual/emacs/">emacs</command>
for editing my documents

Which produces the same effect. Or it would if the stylesheets supported DocBook NG, which they don’t. Yet.

A lot of content models in DocBook are too big. This has been true for a long time and has been the subject of perennial improvement plans. Consider citation:

citation ::=
(#PCDATA|footnoteref|xref|abbrev|acronym|
 citation|citerefentry|citetitle|emphasis|
 firstterm|foreignphrase|glossterm|
 footnote|phrase|orgname|quote|trademark|
 wordasword|personname|link|olink|ulink|
 action|application|classname|methodname|
 interfacename|exceptionname|ooclass|
 oointerface|ooexception|command|
 computeroutput|database|email|envar|
 errorcode|errorname|errortype|errortext|
 filename|function|guibutton|guiicon|…)*

Does it really make sense to have an citerefentry in a citation? Probably not. So in DocBook NG, I made the content model much smaller:

citation ::=
    • Zero or more of:
          ◦ anchor
          ◦ indexterm (indexterm.endofrange)
          ◦ indexterm (indexterm.singular)
          ◦ indexterm (indexterm.startofrange)
          ◦ inlinemediaobject
          ◦ phrase (text.phrase)
          ◦ remark
          ◦ replaceable

Too small? Perhaps, but that should turn up pretty quickly in testing.

There’s a single info wrapper now (instead of bookinfo, chapterinfo, etc.). The info wrapper also occurs in several more places and comes in three flavors to establish greater consistency. Consider procedure:

procedure ::=
    • Sequence of:
          ◦ One of:
                ▪ Sequence of:
                      ▪ Interleave of:
                            ▪ title?
                            ▪ titleabbrev?
                      ▪ info? (db.info.titleforbidden)
                ▪ info (db.info.titleonly)
          ◦ Zero or more of:
                ▪ address
                ▪ anchor
                ▪ …
          ◦ One or more of:
                ▪ step

What does this say? Working from the inside out, it says that a procedure can optionally have a title and titleabbrev in any order (but at most once) followed by an info that forbids titles or it can have an info that allows titles. After the title markup, it can have optional blocks followed by at least one step.

There’s a real tension in schema design between simplicity and consistency on the one hand and rigerous enforcement of every possible constraint on the other.

For example, the DocBook NG schema includes a pattern called “blocks” that contains all the block level elements. Most content models that include block elements do so by reference to that pattern. That’s simple and consistent. But consider admonitions; admontions are not allowed to nest. So we have three choices:

Direct support for Schematron validation inside tools like msv makes this a very attractive option. So the DocBook NG patterns for admonitions include Schematron rules that enforce exclusion constraints. Sweet.

Now, in point of fact, the DocBook NG schema is built from sources that I “compile” into the actual schema. So all I actually have to do in the DocBook NG source to setup an exclusion is add an annotation:

ctrl:exclude [ from="admonition.blocks"
               exclude="admonition.blocks" ]

The sources and the build system are available from the DocBook project on SourceForge. They are very experimental and I’m reasonably confident that they’ll change in significant ways before all is said and done.

Another nice feature of this build strategy is that I’ll be able to produce a Schematron schema that expresses many of the constraints in DocBook NG that can’t be expressed in DTDs. So when there’s a DTD version, which will be necessity be much more liberal than the RELAX NG version, there will also be a Schematron schema to use as an adjunct, if you wish.

A little housecleaning was definitely in order. Some elements have been replaced by a single element in several flavors others have simply been discarded. A few of these may be controversial. They can always be added again.

All the flavors of info have been replaced by the single info element in several flavors.

Several of the linking elements are gone in favor of common linking attributes: link, olink, and ulink.

DocBook NG has recursive section and refsection elements, but it no longer has sectn or refsectn elements.

All of the lot/toc machinery has been simplified.

Some other elements have been tossed onto the scrap heap: action, alt, authorblurb (use personblurb), beginpage, collabname, corpauthor, corpcredit, corpname (use orgname), graphic, graphicco, inlinegraphic (use flavors of mediaobject), interface, invpartnumber, isbn, issn (use flavors of biblioid), medialabel, modespec, property, pubsnumber, tag (renamed xmltag), structfield, and structname.

I haven’t put DocBook NG in a namespace, but I still think it should be in one. I’ve figured out how to handle this dicotomy in the XSL stylesheets (though it won’t be terribly efficient), but I’m worried about other tools.

Maybe in the next release.