Chapter 5. Customizing DocBook

Starting with DocBook V5.0, DocBook is identified by its namespace, http://docbook.org/ns/docbook. The particular version of DocBook to which an element conforms is identified by its version attribute. If the element does not specify a version, the version of the closest ancestor DocBook element that does specify a version is assumed. The version attribute is required on the root DocBook element.

Here is how these attributes would appear on the book element.

  |<book xmlns="http://docbook.org/ns/docbook"
  |      version="5.0">
  |  …
  |</book>

If you change the DocBook schema, the namespace remains the same, but you must provide an alternate version identifier for the schema and the modules you changed. The version attribute identifies the version of DocBook the alternate is based on, specifies what type of variant it is, and names the variant and any additional modules. While the format for the version string is not part of the normative specification, the DocBook Technical Committee recommends the following format:

  |base_version-(subset|extension|variant) (name[-version])+

For example, version 1.0 of Acme Corporation’s extension of DocBook V5.0 could be identified as 5.0-extension acme-1.0.

If your schema is a proper subset, use the subset keyword in the version. If your schema extends the markup model, use the extension keyword. If you’d rather not characterize your variant specifically as a subset or an extension, use the variant keyword.

Although not directly supported by RELAX NG, in some cases it may still be valuable to identify a DocBook V5.0 customization layer with a public identifier. A public identifier for DocBook V5.0 is:

  |-//OASIS//DTD DocBook V5.0//EN

If you make any changes to the structure of the schema, you must change the public identifier. You should change both the owner identifier and the description. Formal public identifiers for the base DocBook modules would have identifiers with the following syntax:

  |-//OASIS//text-class DocBook description Vversion//EN

Your public identifiers should use the following syntax:

  |-//Owner-ID//text-class DocBook Vversion-Based (Subset|Extension|Variant) \
  |Description-and-version//lang

For example:

  |-//O'Reilly//DTD DocBook V5.0-Based Subset V1.1//EN

If your schema is a proper subset, use the Subset keyword in the description. If your schema extends the markup model, use the Extension keyword. If you’d rather not characterize your variant specifically as a subset or an extension, use the Variant keyword.

There are two standard syntaxes for RELAX NG, an XML syntax and a compact text syntax. The two forms have the same expressive power; it is possible to transform between them with no loss of information.

Many users find the relative terseness of the compact syntax makes it a convenient form for reading and writing RELAX NG. We will use compact syntax in our examples.

The DocBook RELAX NG schema is highly modular, using named patterns extensively. Every element, attribute, attribute list, and enumeration has its own named pattern. In addition, there are named patterns for logical combinations of elements and attributes. These named patterns provide hooks into the schema that allow you to do a wide range of customization by simply redefining one or more of the named patterns.

The names of the patterns used in a RELAX NG grammar can be defined in any way the schema designer chooses. To make it easier to navigate, the DocBook RELAX NG grammar employs the following naming conventions:

db.*.attlist

Defines the list of attributes associated with an element. For example, db.emphasis.attlist is the pattern that matches all of the attributes of the emphasis element.

db.*.attribute

Defines a single attribute. For example, db.conformance.attribute is the pattern that matches the conformance attribute on all of the elements where it occurs.

db.*.attributes

Defines a collection of attributes. For example, db.effectivity.attributes is all of the effectivity attributes (arch, audience, etc.).

db.*.blocks

Defines a list (a choice) of a set of related block elements. For example, db.list.blocks is a pattern that matches any of the list elements.

db.*.contentmodel

Defines a fragment of a content model shared by several elements.

db.*.enumeration

Defines an enumeration, usually one used in an attribute value. For example, db.revisionflag.enumeration is a pattern that matches the list of values that can be used as the value of a revisionflag attribute.

db.*.info

Defines the info element for a particular element. For example, db.example.info is the pattern that matches info on the example element.

Almost all of the info elements are the same, but they are described with distinct patterns so that customizers can change them individually.

db.*.inlines

Defines a list (a choice) of a set of related inline elements. For example, db.link.inlines is a pattern that matches any of the linking-related elements.

db.*.role.attribute

Defines the role attribute for a particular element. For example, db.emphasis.role is the pattern that matches role on the emphasis element.

All of the role attributes are the same, but they are described with distinct patterns so that customizers can change them selectively.

db.*

Defines a particular DocBook element. For example, db.title is the pattern that matches the title element.

RELAX NG allows multiple patterns to match the same element, so sometimes these patterns come in flavors, for example, db.indexterm.singular, db.indexterm.startofrange, and db.indexterm.endofrange. Each of these patterns matches indexterm with varying attributes.

These are conventions, not hard and fast rules. There are patterns that don’t follow these conventions.

Creating a customized schema is similar to creating a customization layer for XSL. The schema customization layer is a new RELAX NG schema that defines your changes and includes the standard DocBook schema. You then validate using the schema customization as your schema. Although customization layers vary in complexity, most of them have the same general structure as other customization layers of similar complexity.

In the most common case, you probably want to include all of DocBook, but you want to make some small changes. These customization layers tend to look like this:

  |namespace db = "http://docbook.org/ns/docbook"
  |# perhaps other namespace declarations
  | 
  |include "docbook.rnc"                            ①
  | 
  |# new patterns and augmented patterns            ②

If you want to completely replace a pattern (e.g., to remove or completely change an element), the template is a little different.

  |namespace db = "http://docbook.org/ns/docbook"
  |# perhaps other namespace declarations
  | 
  |include "docbook.rnc" {
  |   # redefinitions of DocBook patterns           ①
  |}
  | 
  |# new patterns and augmented patterns            ②

There are other possibilities as well; these examples are illustrative, not exhaustive.

If you’re considering writing a customization layer, there must be something that you want to change. Perhaps you want to add an element or attribute, remove one, or change some other aspect of the schema.

Adding an element, particularly an inline element, is one possibility. For example, if you’re writing about cryptography, you might want to add a cleartext element. The next section describes how to create a customization layer to do this.

Figuring out what to change may be the hardest part of the process. For the cleartext example, there are several patterns that you could possibly change. The choice will depend on the exact focus of your document. Here are several candidates, all of which look plausible: technical inlines, programming inlines, and domain inlines. Let’s suppose you chose the domain inlines.

As shown in Example 5.1, “Adding cleartext with a customization layer”, your customization would import the DocBook schema, extend the domain inlines, and then provide a pattern that matches the new element.

 1 |namespace db = "http://docbook.org/ns/docbook"
   |default namespace = "http://docbook.org/ns/docbook"
   | 
   |include "docbook.rnc"
 5 | 
   |db.domain.inlines |= db.cleartext                 ①
   | 
   |# Define a new cleartext element:                 ②
   | 
10 |db.cleartext.role.attribute = attribute role { text }    ③
   |db.cleartext.attlist =                            ④
   |   db.cleartext.role.attribute?
   | & db.common.attributes
   | & db.common.linking.attributes
15 | 
   |db.cleartext =                                    ⑤
   |   element cleartext {
   |      db.cleartext.attlist,
   |      db._text
20 |   }

Using a customization layer is simple. Just put the customization into a file—for example, mycustomization.rnc—and then refer to that file instead of the DocBook schema when your tools offer the option.

Schemas, by their nature, contain many complex, interrelated patterns. Whenever you make a change to the schema, it’s always wise to use a validator to check your work.

Start by validating a document that’s plain, vanilla DocBook, one that you know is valid according to the DocBook standard schema. This will help you identify any errors that you’ve introduced to the schema. Once you are confident the schema is correct, begin testing with instances that you expect (and don’t expect) to be valid against it.

The following sections contain examples for several common customizations.

The msgset element is a favorite target. It has a complex internal structure designed for describing interrelated error messages, especially on systems that may exhibit messages from several different components. Many technical documents can do without it, and removing it leaves one less complexity to explain to your authors.

Example 5.2, “Removing msgset” shows a customization layer that removes the msgset element.

1 |namespace db = "http://docbook.org/ns/docbook"
  | 
  |include "docbook.rnc" {
  |   db.msgset = notAllowed
5 |}

The complexity of msgset is really in its msgentry children. DocBook V4.5 introduced a simple alternative, simplemsgentry. Example 5.3, “Removing msgentry” demonstrates how you could allow msgset but only support the simpler alternative.

1 |namespace db = "http://docbook.org/ns/docbook"
  | 
  |include "docbook.rnc" {
  |   db.msgentry = notAllowed
5 |}

Closer examination of the msgentry content model will reveal that it contains a number of descendants. It isn’t necessary, but it wouldn’t be wrong, to define their patterns as notAllowed as well.

DocBook contains a large number of computer inlines. The DocBook inlines define a domain-specific vocabulary. If you’re working in another domain, many of them may be unnecessary.

They’re defined in a set of patterns that ultimately roll up to the db.domain.inlines pattern. If you make that pattern notAllowed, you’ll remove them all in one fell swoop. Example 5.4, “Removing computer inlines” is a customization that does this.

1 |namespace db = "http://docbook.org/ns/docbook"
  | 
  |include "docbook.rnc" {
  |   db.domain.inlines = notAllowed
5 |}

If you want to be more selective, you might consider making one or more of the following notAllowed instead:

• db.error.inlines: errors and error messages

• db.gui.inlines: GUI elements

• db.keyboard.inlines: key and keyboard elements

• db.markup.inlines: markup elements

• db.math.inlines: mathematical expressions

• db.os.inlines: operating system inlines

• db.programming.inlines: programming-related inlines

Another possibility is removing the complex synopsis elements. The customization layer in Example 5.5, “Removing cmdsynopsis and funcsynopsis” removes cmdsynopsis and funcsynopsis.

1 |namespace db = "http://docbook.org/ns/docbook"
  | 
  |include "docbook.rnc" {
  |   db.funcsynopsis = notAllowed
5 |   db.cmdsynopsis = notAllowed
  |}

Perhaps you want to restrict your authors to only three levels of sectioning. To do that, you could remove the sect4 and sect5 elements, as shown in Example 5.6, “Removing the sect4 and sect5 elements”.

1 |namespace db = "http://docbook.org/ns/docbook"
  | 
  |include "docbook.rnc" {
  |   db.sect4 = notAllowed
5 | 
  |   # Strictly speaking, we don't need to remove sect5 because, having removed
  |   # sect4, there's no way to reach it. But it seems cleaner to do so.
  |   db.sect5 = notAllowed
  |}

This technique works if your authors are using numbered sections, which you could require them to do by removing the section element. But suppose instead you want to allow them to use recursive sections, but limit them to only three levels.

One way to do this would be to define new section2 and section3 patterns, as shown in Example 5.7, “Limiting recursive sections to three levels”.

 1 |namespace db = "http://docbook.org/ns/docbook"
   |default namespace = "http://docbook.org/ns/docbook"
   | 
   |include "docbook.rnc" {
 5 |   db.section =
   |      element section {
   |         db.section.attlist,
   |         db.section.info,
   |         db.recursive.blocks.or.section2s,
10 |         db.navigation.components*
   |      }
   |}
   | 
   |db.recursive.section2s = (db.section2+, db.simplesect*) | db.simplesect+
15 | 
   |db.recursive.blocks.or.section2s =
   |  (db.all.blocks+, db.recursive.section2s?) | db.recursive.section2s
   | 
   |db.section2 =
20 |   element section {
   |      db.section.attlist,
   |      db.section.info,
   |      db.recursive.blocks.or.section3s,
   |      db.navigation.components*
25 |   }
   | 
   |db.recursive.section3s = (db.section3+, db.simplesect*) | db.simplesect+
   | 
   |db.recursive.blocks.or.section3s =
30 |  (db.all.blocks+, db.recursive.section3s?) | db.recursive.section3s
   | 
   |db.section3 =
   |   element section {
   |      db.section.attlist,
35 |      db.section.info,
   |      db.all.blocks+
   |      db.navigation.components*
   |   }

Another solution, assuming your validation environment supports Schematron, is simply to add a new rule, as shown in Example 5.8, “Limiting recursive sections to three levels using Schematron”.

 1 |namespace db = "http://docbook.org/ns/docbook"
   |namespace s = "http://www.ascc.net/xml/schematron"
   |default namespace = "http://docbook.org/ns/docbook"
   | 
 5 |include "docbook.rnc" {
   |   db.section =
   |      [
   |         s:pattern [
   |            name = "Limit depth of sections"
10 |            s:rule [
   |               context = "db:section"
   |               s:assert [
   |                  test = "count(ancestor::db:section) < 2"
   |                  "Sections can be no more than three levels deep"
15 |               ]
   |            ]
   |         ]
   |      ]
   |      element section {
20 |         db.section.attlist,
   |         db.section.info,
   |         db.recursive.blocks.or.sections,
   |         db.navigation.components*
   |      }
25 |}

In this example, we’ve put the Schematron pattern inline in the RELAX NG grammar. If your validation strategy requires that they be in a separate document, it may be more convenient to simply create them separately.

Sometimes what you want to do is not as simple as entirely removing an element. Instead, you may want to remove it only from some contexts. The way to do this is to redefine the patterns used to calculate the elements allowed in those contexts.

Standard DocBook allows any inline element or any block element to appear in a table cell. You might decide that it’s unreasonable to allow admonitions (note, caution, warning, etc.) to appear in a table cell.

In order to remove them, you must change what is allowed in the entry element, as shown in Example 5.9, “Removing admonitions from tables”.

 1 |namespace db = "http://docbook.org/ns/docbook"
   |default namespace = "http://docbook.org/ns/docbook"
   | 
   |include "docbook.rnc" {
 5 |   db.entry = element entry {
   |      db.entry.attlist,
   |      (db.all.inlines* | db.some.blocks*)
   |   }
   |}
10 | 
   |db.some.blocks =
   |   db.somenopara.blocks
   | | db.para.blocks
   | | db.extension.blocks
15 | 
   |db.somenopara.blocks =
   |   db.list.blocks
   | | db.formal.blocks
   | | db.informal.blocks
20 | | db.publishing.blocks
   | | db.graphic.blocks
   | | db.technical.blocks
   | | db.verbatim.blocks
   | | db.bridgehead
25 | | db.remark
   | | db.revhistory
   | | db.indexterm
   | | db.synopsis.blocks

The extent to which any particular change is easy or hard depends in part on how many patterns need to be changed. The DocBook Technical Committee is generally open to the idea of adding more patterns if it improves the readability of customization layers. If you think some refactoring would make your job easier, feel free to ask.

DocBook defines a set of common attributes, which appear on every element. Depending on how you process your documents, removing some of them can both simplify the authoring task and improve processing speed.

Some obvious candidates are:

Effectivity attributes (arch, os, condition...)

If you’re not using all of the effectivity attributes in your documents, you can get rid of up to seven attributes in one fell swoop.

xml:lang

If you’re not producing multilingual documents, you can remove xml:lang.

remap

The remap attribute is designed to hold the name of a semantically equivalent construct from a previous markup scheme (e.g., a Microsoft Word–style template name, if you’re converting from Word). If you’re authoring from scratch, or not preserving previous constructs with remap, you can get rid of it.

xreflabel

If your processing system isn’t using xreflabel, it’s a candidate as well.

The customization layer in Example 5.11, “Removing common attributes” reduces the common attributes to just xml:id, version, and xml:lang.

1 |namespace db = "http://docbook.org/ns/docbook"
  | 
  |include "docbook.rnc" {
  |   db.common.base.attributes =
5 |      db.version.attribute?
  |    & db.xml.lang.attribute?
  |}

The role attribute, found on almost all of the elements in DocBook, is a text attribute that can be used to subclass an element. In some applications, it may be useful to modify the definition of role so that authors must choose one of a specific set of possible values.

In Example 5.14, “Changing role on procedure”, the role attribute on the procedure element is constrained to the value required or optional.

1 |namespace db = "http://docbook.org/ns/docbook"
  | 
  |include "docbook.rnc" {
  |   db.procedure.role.attribute = attribute role { "required" | "optional" }
5 |}

Example 5.15, “Adding a value to an enumeration” adds the value large to the db.spacing.enumeration pattern. Any attribute that is defined using db.spacing.enumeration will now have large as a legal value. Note that while it is easy to add a value to an enumeration, to remove a value from an enumeration you need to redefine the entire enumeration, minus the values you don’t need.

1 |namespace db = "http://docbook.org/ns/docbook"
  |default namespace = "http://docbook.org/ns/docbook"
  | 
  |include "docbook.rnc"
5 | 
  |# add a value to an enumeration
  |db.spacing.enumeration |= "large"