DocBook 5: The Definitive Guide

DocBook V5.0

DocBook V5.0 represents a major step forward for DocBook. The differences between DocBook 4.x and V5.0 are quite radical in some aspects, but the basic idea behind DocBook is still the same, and almost all element names are unchanged. Because of this it is very easy to become familiar with DocBook V5.0 if you know any previous version of DocBook.

What’s New in DocBook V5.0?

In V5.0, DocBook has been rewritten as a native RELAX NG grammar (“An introduction to the RELAX NG schema language” [RNG-Intro] is an excellent introduction to the grammar). The objectives were to produce a schema that:

1. “Feels like” DocBook. Most existing documents should still be valid or it should be possible to transform them in simple, mechanical ways into valid documents.

2. Enforces as many constraints as possible in the schema. Some additional constraints are expressed with Schematron rules.

3. Cleans up the content models.

4. Gives users the flexibility to extend or subset the schema in an easy and straightforward way.

5. Can be used to generate XML DTD and W3C XML Schema versions of DocBook.

Under the ordinary operating rules of DocBook evolution, the only backward-incompatible changes that could be made in DocBook V5.0 were those announced in DocBook V4.0. In light of the fact that this is a complete rewrite, the Technical Committee gave itself the freedom to make “unannounced” backward-incompatible changes for this one release.

Renamed and removed elements

A number of elements have been removed from DocBook. Some have been replaced by simpler, more versatile alternatives. Others have been removed because they were no longer needed, and still others have been renamed. Table 1-1 lists the elements that have been renamed for DocBook V5.0.

Table 1-1. Renamed elements

Old name	New name
sgmltag	tag
bookinfo, articleinfo, chapterinfo, *info	info
authorblurb	personblurb
collabname, corpauthor, corpcredit, corpname	orgname
isbn, issn, pubsnumber	biblioid
lot, lotentry, tocback, tocchap, tocfront, toclevel1, toclevel2, toclevel3, toclevel4, toclevel5, tocpart	toc, tocdiv, and tocentry
graphic, graphicco, inlinegraphic, mediaobjectco	mediaobject and inlinemediaobject
ulink	link
ackno	acknowledgements

The following elements were removed from DocBook V5.0 without direct replacements: action, beginpage, highlights, interface, invpartnumber, medialabel, modespec, structfield, and structname. If you use one or more of these elements, Table 1-2 contains suggestions for recoding them in DocBook V5.0.

Table 1-2. Recommended mapping for removed elements

Old name	Recommended mapping
action	Use <phrase remap="action">.
beginpage	Remove: beginpage is advisory only and has tended to cause confusion. A processing instruction or comment should be a workable replacement if one is needed.
highlights	Use abstract. Note that because highlights has a broader content model, you may need to wrap contents in a para inside abstract.
interface	Use menuchoice or one of the “gui*” elements (guibutton, guiicon, guilabel, guimenu, guimenuitem, or guisubmenu).
invpartnumber	Use <biblioid class="other" otherclass="medialabel">. The productnumber element is another alternative.
medialabel	Use <citetitle pubwork="mediatype">, where mediatype is the type of media being labeled (e.g., cdrom or dvd).
modespec	No longer needed. The current processing model for olink renders modespec unnecessary.
structfield, structname	Use varname. If you need to distinguish between the two, use <varname remap="structname or structfield">. In some contexts, it may also be appropriate to use property for structfield.

Linking and cross-referencing

In DocBook 4.x the id attribute is used to assign a unique identifier to an element. In DocBook V5.0 this attribute is renamed xml:id, and its usage is consistent with xml:id Version 1.0 [XML-ID], a W3C Recommendation.

The biggest change in linking is that now nearly any inline element, not just xref or link, can be the source of a link. For example, consider the following DocBook 4.x example:

<section id="dir">
  <title>DIR command</title>
  <para>...</para>
</section>

<section id="ls">
  <title>LS command</title>
  <para>This command is a synonym for
    <link linkend="dir"><command>DIR</command></link> command.
  </para>
</section>

In DocBook V5.0, this can be written as the following:

<section xml:id="dir">
  <title>DIR command</title>
  <para>...</para>
</section>

<section xml:id="ls">
  <title>LS command</title>
  <para>This command is a synonym for
    <command linkend="dir">DIR</command> command.
  </para>
</section>

In addition, the href attribute from the XLink namespace was added to the same set of inline elements as linkend. The following example shows how you can use href. Note that you need to declare the XLink namespace in your document instance to use this attribute:

<article xmlns="http://docbook.org/ns/docbook" 
         xmlns:xl="http://www.w3.org/1999/xlink" version="5.0">
  <title>Test article</title>

  <para>
    <application xl:href="http://www.gnu.org/software/emacs/">Emacs</application> 
    is my favourite text editor.</para>
    ...
</article>

The ulink element was removed from DocBook V5.0. It can be replaced by the link element using the XLink href attribute.

The XLink href attribute may contain a fragment identifier to create a link within a document. For example:

<command xl:href="#dir">DIR</command>

Note

XLink references are not expected to be checked during validation, but linkend references are.

Uniform info elements

DocBook versions earlier than DocBook V5.0 use unique elements for block information. For example, a book element would contain a bookinfo element. This was done to support different content models for different block elements. DTDs only allow one content model for each element, so a different element name was required for each block’s information element.

RELAX NG does not have this limitation. An element can have a different content model in different contexts. Therefore, the array of info elements (articleinfo, bookinfo, etc.) has been replaced with a single info element.

Required title and version attributes

DocBook V5.0 requires the title attribute on large block elements such as article. The written specification for earlier versions of DocBook noted this, but the DTD could not enforce this constraint. With RELAX NG, this constraint can now be enforced in the schema.

DocBook V5.0 no longer requires a Document Type Declaration. However, because processors may need to know the version of an instance, DocBook V5.0 has added the version attribute, which must appear on the root element of a DocBook document. The version attribute may also appear on other elements, and mixing of versions is allowed.

Additional constraints

HTML and CALS tables

DocBook 4.x did not prevent mixing of CALS and HTML table elements in a single table, even in cases where the result might be unusable. DocBook V5.0 specifically prohibits mixing.

Co-constraints

DocBook V5.0 enforces co-constraints such as the constraint that the otherclass attribute on biblioid may appear if, and only if, the class attribute exists and has the value other.

Data types

DocBook V5.0 uses some data types; for example, the col attribute on tgroup is defined as a positive integer. In some cases, the data type for a particular value may constrain it further than that value was constrained in prior releases.

Table of contents

Prior to DocBook V5.0, the markup for tables of contents was clumsy and difficult to use. Although nearly all tables of contents are generated automatically, there are still cases where a table may need to be created or edited manually. Therefore, DocBook V5.0 introduces a simpler, recursive structure. See the toc, tocdiv, and tocentry reference pages for details and an example.

Constraint definitions using Schematron

DocBook V5.0 uses rule-based validation for certain constraints using Schematron. These constraints, such as the requirement that the root element of a document have a version attribute, are easier to express in a rule-based language than in a schema language, even one as flexible as RELAX NG.

Accessibility

Inline and block annotations are allowed in most contexts. Inline annotations use the alt element, and block annotations are supported by the new annotation element.