DocBook V5.0

The latest versions of schemas can be obtained from https://docbook.org/schemas/5x.html. At the time of this writing the latest version is 5.0b8 and individual schemas are available at the following locations:

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

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 a directory with 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. From this time 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 correspoding add-on. Go to Options → Install Add-ons…. Then choose DocBook 5 configuration and press OK button. After restart XXE is ready to work with DocBook V5.0 documents.

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 exactly the same way as 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.

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 can not 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:

Stripping NS from DocBook 5/NG document.
Processing stripped document.

Although you can successfully use the existing stylesheets to process DocBook V5.0, there are some limitations. To support some of the new features of DocBook V5.0, the existing stylesheets would require a significant rewrite. A rewrite is unlikely because a new version of stylesheets is currently under development.

The unsupported features include:

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.zip and unpack it somewhere. Then download and install Saxon 8 from http://saxon.sf.net.

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

java -jar /path/to/saxon8.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/saxon8.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 whereever 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"