DocBook V5.0

The latest versions of schemas can be obtained from http://docbook.org/schemas/5x.html. At the time this was written the latest version was 5.0. Individual schemas are available at the following locations:

These schemas are also available from the mirror at http://www.oasis-open.org/docbook/xml/5.0/.

Detailed documentation about each DocBook V5.0 element is presented in the reference part of DocBook: The Definitive Guide.

nXML mode is an add-on for the GNU Emacs text editor. By installing nXML you can turn Emacs into a very powerful XML editor that offers guided editing and validation of XML documents.

Figure 1. Emacs with nXML mode provides guided editing and validation

nXML uses a special configuration file named schemas.xml to associate schemas with XML documents. Often you will find this file in the directory site-lisp/nxml/schema inside the Emacs installation directory. Adding the following line into the configuration file, will associate DocBook V5.0 elements with the appropriate schema:

<namespace ns="http://docbook.org/ns/docbook" uri="/path/to/docbook.rnc"/>

If you can't edit the global schemas.xml file, you can create this file in the same directory as your document. nXML will find associations placed there also. In this case you must create a complete configuration file like:

<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
  <namespace ns="http://docbook.org/ns/docbook" uri="/path/to/docbook.rnc"/>
</locatingRules>

oXygen is a feature rich XML editor. It has built-in support for many schema languages including RELAX NG. If you want to smoothly edit and validate DocBook 5.0 documents you should associate the DocBook namespace with the corresponding schema. Go to Options → Preferences… → Editor → Default Schema Associations. Then click the New button to add a new association. Type in the DocBook namespace and the RELAX NG schema location, choose the RNG Schema + Schematron type of schema as, and confirm your choice by clicking the OK button.

Figure 2. Adding a new schema association in oXygen

Because oXygen comes with preconfigured associations for DocBook V4.x, you must move your newly added configuration to the top of the list (using the Up button). That way you will be able to use oXygen with both DocBook V4.x and DocBook V5.0.

Figure 3. DocBook V5.0 association must precede associations for DocBook V4.x

Now you can close the preference box by clicking on the OK button. oXygen will assist you with writing DocBook V5.0 content, and you will be able to validate your documents against both RELAX NG and Schematron schemas.

Figure 4. DocBook V5.0 document opened in oXygen

XML Mind XML editor (XXE) is a visual validating XML editor that provides a wordprocessor-like interface to users. It is available in two versions, Standard and Professional. The Standard version is free and provides everything you need to edit DocBook V5.0 documents.

Figure 5. XML Mind XML Editor – feels almost like MS Word but real DocBook V5.0 markup is created

In order to use DocBook V5.0 in XXE you have to install an add-on. Go to Options → Install Add-ons…. Then choose DocBook 5 configuration and press the OK button. After restart, XXE is ready to work with DocBook V5.0 documents.

You can find a list of RELAX NG validators at http://relaxng.org/#validators. It is best to use validators with support for embedded Schematron rules inside RELAX NG schemas. Schematron is a rule-based validation language which is used to impose additional constraints on DocBook documents. Schematron rules assert conditions which are impossible or difficult to express in a pure RELAX NG schema.

Sun Multi-Schema XML Validator (MSV) is able to validate an XML document against a RELAX NG schema and Schematron rules at the same time. To install and use MSV follow these steps:

There is also an on-line DocBook V5.0 validator that validates DocBook V5.0 documents against the normative RELAX NG schema with embedded Schematron rules.

NVDL is a meta-schema language which can validate a document against several schemas. DocBook V5.0 comes with a NVDL schema which specifies that DocBook documents should be validated against both RELAX NG and Schematron schemas.

You can find a list of NVDL validators at http://nvdl.org/. The following procedures show how to install and use the oNVDL and JNVDL validators.

The DocBook stylesheets are designed to process content written in different versions of DocBook (for example 3.1 and 4.2). Recent versions of the stylesheets are also able to process DocBook V5.0 with some limitations.

You can process DocBook V5.0 documents with the DocBook XSL stylesheets in exactly the same way you process DocBook V4.x documents. You do not need special software; you can stick to your preferred XSLT processor, be it Saxon, xsltproc, Xalan or whatever else (but see the note about the lost base URI below).

During document processing, the stylesheets strip namespaces from DocBook V5.0 to get a document which will be very similar to DocBook V4.x. This is necessary because from the XSLT point of view, elements from different namespaces are distinct and cannot be easily processed by the same set of templates. This process is completely transparent to the user. If you are processing DocBook V5.0 documents, the only difference is that you will see the following additional message:

Note: namesp. cut : stripped namespace before processing
Note: namesp. cut : processing stripped document

Although you can successfully use the existing stylesheets to process DocBook V5.0, there are some limitations and unsupported features. The unsupported features include:

WARNING: cannot add @xml:base to node set root element. Relative paths may not work.

As you can see from reading the previous section, namespace stripping has limitations that will cause trouble in some situations. To overcome those limitations, Bob Stayton created a build system for taking the non-namespace-aware DocBook XSL stylesheets and generating namespace-aware versions from them. The DocBook XSL-NS stylesheets are the result.

The DocBook XSL-NS stylesheets are released side-by-side with the DocBook XSL stylesheets, as a separate docbook-xsl-ns package. They are the recommended XSLT 1.0 stylesheets to use for transforming namespaced (DocBook V5.0) documents.

XSLT 1.0 is missing some important features. To work around these missing features, the current DocBook XSL stylesheets use some implementation-specific extensions. XSLT 2.0 adds many new and previously missing features into the language. A new set of DocBook stylesheets is being implemented based on XSLT 2.0 to take advantage of these features and to fully support DocBook V5.0.

The XSLT 2.0 based stylesheets have many new features, including:

The XSLT 2.0 based stylesheets are still under development. At this writing, they only support HTML and chunked HTML output. As time permits, the stylesheet developers will be adding other formats. Since the stylesheets are developed in the limited free time the developers have, there's no specific schedule.

There are not very many XSLT 2.0 implementations available. But, if you want to try the new stylesheets, grab a snapshot of the development version from http://docbook.sourceforge.net/snapshots/docbook-xsl2-snapshot.tar.bz2 and unpack it somewhere. Then download and install Saxon 9 from http://saxon.sf.net.

To transform a DocBook V5.0 document to a single HTML page use the command:

java -jar /path/to/saxon9.jar -o output.html document.xml /path/to/docbook-xsl2-snapshot/html/docbook.xsl

To transform a DocBook V5.0 document to a set of chunked HTML pages use the command:

java -jar /path/to/saxon9.jar document.xml /path/to/docbook-xsl2-snapshot/html/chunk.xsl

External parsed entities, entities which load part of a document from another file, are a special case. These can often be replaced with XInclude elements.

The Perl script db4-entities.pl, also included in the DocBook V5.0 distribution attempts to perform this replacement for you. To use the script, perform the following steps:

Because named patterns are used extensively, the RELAX NG schema uses several naming conventions. These are:

Adding an element typically takes two definitions. The first defines the new element and its content model, and the second adds the new element into the schema. We'll show two examples.

Example 4 adds a new element, person, with the same content model as author. The new element will be allowed to appear wherever author can appear.

The db.author pattern is copied and renamed dbx.person, defining a new element called person. Then, the db.author pattern is redefined to be a choice of the current value or dbx.person. The combine attribute tells RELAX NG to combine this pattern with the existing named pattern. In this case, the value of the combine attribute is “choice”, which tells the parser that either the original pattern or this new pattern is a valid match.

r
n
g<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns:db="http://docbook.org/ns/docbook"
         ns="http://docbook.org/ns/docbook"
         xmlns="http://relaxng.org/ns/structure/1.0">
  <include href="docbook.rng"/>
  <!-- define the new element -->
  <define name="dbx.person">
    <element name="person">
        <ref name="db.author.attlist"/>
        <ref name="db.credit.contentmodel"/>
    </element>
  </define>
  <!-- redefine the db.author pattern to allow db.person in
       the same places as db.author -->
  <define name="db.author" combine="choice">
    <ref name="dbx.person"/>
  </define>
</grammar>

r
n
cdefault namespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc"
# define the new element
dbx.person =
  element person { db.author.attlist, db.credit.contentmodel }
# redefine the db.author pattern to allow db.person in
# the same places as db.author
db.author |= dbx.person

The preceding method works well when you'd like a new element to be a clone or near-clone of an existing element. It gives you complete control over the content model, but only limited control over where the element is allowed. It works well when you want to allow the element in the same places as an existing element, and for this example that works nicely, since author is allowed in four different named patterns, each of which would have had to be redefined to allow person. But, if you can't find an existing element that is allowed in exactly the places you need, this method doesn't work as well.

Example 5 adds two new elements by combining them into a higher level pattern. In this example, we'll add two new inline elements for writing about assembly language, register and instruction. We will allow them wherever programming inlines or operating system inlines are allowed. Example 5 defines the two elements, creates a new named pattern (dbx.asm.inlines) that contains them, and adds that pattern to db.programming.inlines and db.os.inlines. Since these two patterns don't have any elements in common, the strategy used in Example 4 would require selecting two different elements to “clone”, which would be messy.

r
n
g<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns:db="http://docbook.org/ns/docbook"
         ns="http://docbook.org/ns/docbook"
         xmlns="http://relaxng.org/ns/structure/1.0">
  <include href="docbook.rng"/>
  <!-- define the new elements -->
  <define name="dbx.register">
    <element name="register">
      <text/>
    </element>
  </define>
  <define name="dbx.instruction">
    <element name="instruction">
      <text/>
    </element>
  </define>
  <!-- create a new pattern that contains the new inlines -->
  <define name="dbx.asm.inlines">
    <choice>
      <ref name="dbx.register"/>
      <ref name="dbx.instruction"/>
    </choice>
  </define>
  <!-- add the new inlines to programming and os inlines -->
    <define name="db.programming.inlines" combine="choice">
      <ref name="dbx.asm.inlines"/>
    </define>
    <define name="db.os.inlines" combine="choice">
      <ref name="dbx.asm.inlines"/>
    </define>
</grammar>

r
n
cdefault namespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc"
# define the new elements
dbx.register = element register { text }
dbx.instruction = element instruction { text }
# create a new pattern that contains the new inlines
dbx.asm.inlines = dbx.register | dbx.instruction
# add the new inlines to programming and os inlines
db.programming.inlines |= dbx.asm.inlines
db.os.inlines |= dbx.asm.inlines

Deleting elements is straightforward, but takes some care and planning. Example 6 deletes the important admonition element by redefining it with a content model of notAllowed. Note that in this example, the redefinition is inside the include element. This is required for redefinitions that completely replace an existing pattern.

Be careful; If you delete an element that is a required part of another element's content model, you can make it impossible to create a valid document. For example, if you delete the title element, you won't be able to validate a book because a book requires a title.

r
n
g<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns:db="http://docbook.org/ns/docbook"
         ns="http://docbook.org/ns/docbook"
         xmlns="http://relaxng.org/ns/structure/1.0">
  <include href="docbook.rng">
    <!-- redefine important element as notAllowed -->
    <define name="db.important">
      <notAllowed/>
    </define>
  </include>
</grammar>

r
n
cnamespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc" inherit = db {
  # redefine important element as notAllowed
  db.important = notAllowed
}

Example 7 expands the definition of author to include two new elements, born and died. The author element allows two content models, db.person.author.contentmodel, which defines an author who is a person, and db.org.author.contentmodel, which defines an author that is an organization. We will modify db.person.author.contentmodel so that only authors who are persons can have the new elements.

r
n
g<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns:db="http://docbook.org/ns/docbook"
         ns="http://docbook.org/ns/docbook"
         xmlns="http://relaxng.org/ns/structure/1.0">
  <include href="docbook.rng"/>

  <define name="db.person.author.contentmodel" combine="interleave">
    <interleave>
      <optional>
        <element name="born">
          <ref name="db.date.contentmodel"/>
        </element>
      </optional>
      <optional>
        <element name="died">
          <ref name="db.date.contentmodel"/>
        </element>
      </optional>
    </interleave>
  </define>
</grammar>

r
n
cdefault namespace = "http://docbook.org/ns/docbook"
namespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc"

db.person.author.contentmodel &=
  element born { db.date.contentmodel }?
  & element died { db.date.contentmodel }?

This modification will allow instances like this:

<author>
  <personname>Babe Ruth</personname>
  <born>02/06/1895</born>
  <died>08/16/1948</died>
</author>

but because we only modified the content model for authors who are human, it won't allow an instance like this, which uses db.org.author.contentmodel:

<!-- INVALID -->
<author>
  <orgname>Boston Red Sox</orgname>
  <died>1919</died>
  <born>2004</born>
</author>

The simplest way to add an attribute to a single element is to add it to the attlist pattern for that element. Example 8 adds the optional attributes born and died to the attribute list for author. The db.author.attlist named pattern is redefined with the combine attribute set to “interleave”, which interleaves the two new optional attributes with the existing attributes on the list.

r
n
g<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns:db="http://docbook.org/ns/docbook"
         ns="http://docbook.org/ns/docbook"
         xmlns="http://relaxng.org/ns/structure/1.0">
  <include href="docbook.rng"/>

  <define name="db.author.attlist" combine="interleave">
    <interleave>
      <optional>
        <attribute name="born">
          <ref name="db.date.contentmodel"/>
        </attribute>
      </optional>
      <optional>
        <attribute name="died">
          <ref name="db.date.contentmodel"/>
        </attribute>
      </optional>
    </interleave>
  </define>
</grammar>

r
n
cnamespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc" inherit = db

db.author.attlist &=
  attribute born { db.date.contentmodel }?
  & attribute died { db.date.contentmodel }?

Unlike Example 7, Example 8 allows the new attributes to appear on any author element, not just those using the person content model.

Example 9 shows how you could limit the use of these attributes to authors who are persons. In this example, the new attributes are interleaved with the db.person.author.contentmodel. The only difference between this example and Example 7 is that the added patterns are identified as attributes rather than elements. This shows some of the flexibility of RELAX NG, which treats attributes and elements very consistently.

r
n
g<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns:db="http://docbook.org/ns/docbook"
         ns="http://docbook.org/ns/docbook"
         xmlns="http://relaxng.org/ns/structure/1.0">
  <include href="docbook.rng"/>
  <!-- redefinitions of named patterns -->
  <define name="db.person.author.contentmodel" combine="interleave">
    <interleave>
      <optional>
        <attribute name="born">
          <ref name="db.date.contentmodel"/>
        </attribute>
      </optional>
      <optional>
        <attribute name="died">
          <ref name="db.date.contentmodel"/>
        </attribute>
      </optional>
    </interleave>
  </define>
</grammar>

r
n
cnamespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc" inherit = db
# redefinitions of named patterns
db.person.author.contentmodel &=
  attribute born { db.date.contentmodel }?
  & attribute died { db.date.contentmodel }?

There is one difference in the treatment of attributes and elements that is worth noting. By the XML 1.0 definition, the relative order of attributes is not significant. Therefore, the interleave block is not required for attributes, though it does no harm.

Deleting an attribute is similar to deleting an element, except that you use the RELAX NG empty pattern rather than notAllowed. Example 10 deletes the linking attributes, which are collected in the db.common.linking.attributes pattern, by defining that pattern as empty.

r
n
g<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns:db="http://docbook.org/ns/docbook"
         ns="http://docbook.org/ns/docbook"
         xmlns="http://relaxng.org/ns/structure/1.0">
  <include href="docbook.rng">
    <define name="db.common.linking.attributes">
      <empty/>
    </define>
  </include>
</grammar>

r
n
cnamespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc" inherit = db {
  db.common.linking.attributes = empty
}

Generally, empty is used when deleting attributes and notAllowed is used when deleting elements.

Example 11 modifies db.spacing.enumeration to add the additional value “large”. Note that to remove a value from an enumeration, you need to redefine the entire enumeration, minus the values you don't need.

r
n
g<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns:db="http://docbook.org/ns/docbook"
         ns="http://docbook.org/ns/docbook"
         xmlns="http://relaxng.org/ns/structure/1.0">
  <include href="docbook.rng"/>
  <!-- add value to an enumeration -->
  <define name="db.spacing.enumeration" combine="choice">
    <value>large</value>
  </define>
</grammar>

r
n
cnamespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc" inherit = db
# add value to an enumeration
db.spacing.enumeration |= "large"