The DocBook Schema

A number of elements have been removed from DocBook. Many of these have been replaced by simpler, more versatile alternatives. Others have simply been removed because they are not believed to be widely used.

The content models of many inlines have been reduced, sometimes drastically. The parameter entity customization of DocBook V4.x and previous versions resulted in very broad content models for some inlines.

Consider, for example, command in DocBook V4.4:

command ::=
   (#PCDATA|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|guilabel|
   guimenu|guimenuitem|guisubmenu|hardware|interface|keycap|keycode|
   keycombo|keysym|literal|code|constant|markup|medialabel|
   menuchoice|mousebutton|option|optional|parameter|prompt|property|
   replaceable|returnvalue|sgmltag|structfield|structname|symbol|
   systemitem|uri|token|type|userinput|varname|nonterminal|anchor|
   remark|subscript|superscript|inlinegraphic|inlinemediaobject|
   indexterm|beginpage)*

In DocBook V5.0, command has a much smaller, more rational content model:

command ::=

  * Zero or more of:
      o text
      o alt
      o anchor
      o annotation
      o biblioref
      o indexterm
      o inlinemediaobject
      o link
      o phrase
      o remark
      o replaceable
      o subscript
      o superscript
      o xref

DocBook V5.0 may be overzealous in its simplification of content models. The Technical Committee expects to adjust these simplifications during user testing. Users are encouraged to report places where formally valid documents can no longer be made valid because content models have been reduced.

DocBook V4.x has setinfo, bookinfo, chapterinfo, appendixinfo, sectioninfo, etc. DocBook would be smaller and simpler if it had a single info element in all these places.

There’s an historical reason for the large number of unique names: customizers might very well want to adjust the content models of info elements at different levels. For example, a copyright statement might be required at the book level, or an author forbidden at the sub-section level. In DTDs, there’s only one content model allowed per element name, so in order to support independent customization, each info element must have a different name.

In RELAX NG, no such limitation exists. We can use patterns to achieve both a single info element while still allowing customizers to change its content model in different contexts. In light of this functionality, we've replaced all the various flavors of info with a single element name.

DocBook V5.0 enforces the constraint that titles are required on articles and other large structures where they are effectively optional in DocBook V4.x. (They are optional only in the sense that DTDs are unable to enforce the constraint that they be present, the documentation has always made it clear that titles were required.)

In DocBook V4.x and earlier, the presence of a document type declaration served as a mechanism for identifying the DocBook version of a document. Although the declaration was not actually required, it was present in the vast majority of DocBook documents.

In RELAX NG, no similar declaration exists. Although a document type declaration might still be present, it seems likely that this will not usually be the case.

Nevertheless, downstream processors may benefit from some indication of the version of DocBook being used. As a result DocBook V5.0 adds a new version attribute which must be present on the document element of a DocBook document.

Mixing versions is explicitly allowed and the version attribute may be used on other elements as well. This might be the case, for example, in a compound document constructed from multiple documents each with its own version.

DocBook V5.0 enforces attribute co-constraints such as the class/otherclass attributes on biblioid.

In DocBook V5.0, HTML tables and CALS tables are independently specified. Where the DTD of DocBook V4.x allows for incoherent mixing of the two models, DocBook V5.0 forbids such mixtures.

DocBook V5.0 adds a few simple data types. For example, the cols attribute on tgroup must be a positive integer.

Some of these constraints, such as the requirement that elements like pubdate include a proper date-time type, may prove controversial. Users are encouraged to report places where formally valid documents can no longer be made valid because data types have been introduced.

Starting with DocBook V5.0, the linkend and xlink:href attributes are available on almost all elements.

The linkend attribute provides an ID/IDREF link within the document. The xlink:href attribute provides a URI-based link.

The ulink element has been removed from DocBook as URI-based links can now be achieved directly from the appropriate inline (such as productname or command). For instances where no specific semantic inline is needed, link is still available. Where link used to be limited to ID/IDREF linking, it now sports an xlink:href attribute as well.

Support for extended links are provided through the extendedlink, arc, and locator elements.

Accessibility is improved by allowing both inline and block annotations in most context. The alt element is now allowed in most places for inline annotations, the new element annotation supports block annotations.

The DocBook V4.x markup for Tables of Contents, or more generally for Lists of Titles, was complex and had not evolved quite in step with the rest of DocBook. In DocBook V5.0, it has all been replaced by a quite simple, recursive toc/tocdiv/tocentry structure.

While most Tables of Contents and Lists of Titles are generated automatically and authors never have to produce markup for them by hand, this simplified content model should make it easier for authors to generate them when necessary. One possible application of hand-authored toc markup is to generate custom hierarchies which can be assembled on-the-fly from a library of topics marked up in DocBook.

Grammar based validation technologies (like RELAX NG) and rule based validation technologies (like Schematron) are naturally complementary. Mixing them allows us to play to the strengths of each without stretching either to enforce constraints that they aren’t readily designed to enforce.

For example, DocBook NG requires that the root element of a document have an explicit version attribute. Because there are a great many elements that can be root elements in DocBook, and because they can almost all appear as descendants of a root element as well, it would be tedious to express this constraint in RELAX NG. But it is easy in a rule-based schema language.

DocBook V5.0 uses Schematron where appropriate.

From the very beginning, one of the goals of DocBook has been that users should be able to produce customizations that are either subsets of extensions of DocBook.

Customization is possible in DocBook V4.x, but because of the intricacies of XML DTD syntax and the complex and highly stylized patterns of parameter entitiy usage in DocBook, it's not as easy as we would like it to be.

In DocBook V5.0, we hope to take advantage of RELAX NGs more robust design (and it's lack of pernicious determinism rules) to make customization easier.

Three schema design patterns get us most of the way there.

db.technical.inlines |= endpoint
db.programming.inlines |= endpoint
db.os.inlines |= endpoint

There’s an XSLT 1.0 stylesheet for performing conversion from DocBook V4.x to DocBook V5.0. Presented with a valid DocBook V4.x document, it attempts to produce a valid DocBook V5.0 document.

It succeeds entirely automatically for the most part, though human intervention is suggested for constructs that might have multiple interpretations (and therefore multiple possible transformations).

Users are encouraged to report documents that are not successfully transformed by the stylesheet, especially those which do have valid DocBook V5.0 representations.