DocBook is more than 15 years old. It began in 1991 as a joint project of HaL Computer Systems and O’Reilly & Associates (as O’Reilly Media, Inc. was then called). Its popularity grew, and eventually it spawned its own maintenance organization, the Davenport Group. In mid-1998, maintenance moved to a Technical Committee of the Organization for the Advancement of Structured Information Standards (OASIS).

DocBook’s roots are in SGML, where it was defined with a Document Type Definition, or DTD. DocBook was released as both an SGML and an XML vocabulary starting with V4.1. The V4.x versions of DocBook, like the versions that came before them, were also defined with a DTD. Starting with DocBook V5.0, DocBook is exclusively an XML vocabulary defined with RELAX NG and Schematron.

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.

  1 <section id="dir">
  2   <title>DIR command</title>
      <para>...</para>
  4 </section>
    
  6 <section id="ls">
      <title>LS command</title>
  8   <para>This command is a synonym for
        <link linkend="dir"><command>DIR</command></link> command.
 10   </para>
    </section>

  1 <section xml:id="dir">
  2   <title>DIR command</title>
      <para>...</para>
  4 </section>
    
  6 <section xml:id="ls">
      <title>LS command</title>
  8   <para>This command is a synonym for
        <command linkend="dir">DIR</command> command.
 10   </para>
    </section>

  1 <article xmlns="http://docbook.org/ns/docbook" 
  2          xmlns:xl="http://www.w3.org/1999/xlink" version="5.0">
      <title>Test article</title>
  4 
      <para>
  6     <application xl:href="http://www.gnu.org/software/emacs/">Emacs</application> 
        is my favourite text editor.</para>
  8     ...
    </article>

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

All DocBook V5.0 elements are in the namespace http://docbook.org/ns/docbook. XML namespaces are used to distinguish between different element sets. In the past few years, almost all new XML grammars have used their own namespace. It is easy to create compound documents that contain elements from different XML vocabularies. Consider this simple article marked up in DocBook V4.5:

  1 <!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
  2                          'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd'>
    <article>
  4   <title>Sample article</title>
      <para>This is a really short article.</para>
  6 </article>

The corresponding DocBook V5.0 article will look very similar:

  1 <article xmlns="http://docbook.org/ns/docbook" version="5.0">
  2   <title>Sample article</title>
      <para>This is a really short article.</para>
  4 </article>

The only change is the addition of a default namespace declaration (xmlns="http://docbook.org/ns/docbook") on the root element (and a version attribute, which is described in the next section). This declaration applies the namespace to the root element and all nested elements. Each element is now uniquely identified by its local name and namespace.

For more than a decade, the DocBook schema was defined using a DTD. However, DTDs have serious limitations, and DocBook V5.0 is thus defined using a powerful schema language called RELAX NG. Thanks to RELAX NG, it is now much easier to create customized versions of DocBook, and the content models are now cleaner and more precise.

Using RELAX NG has an impact on the document prolog. Example 1.1, “DocBook V4.5 document” shows the typical prolog of a DocBook 4.x document. The version of the DocBook DTD (in this case V4.5) is indicated in the Document Type Declaration (<!DOCTYPE>) that points to a particular version of the DTD.

  1 <?xml version="1.0" encoding="utf-8"?>
  2 <!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                             'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd'>
  4 <article lang="en">
      <title>Sample article</title>
  6   <para>This is a very short article.</para>
    </article>

In contrast, DocBook V5.0 does not depend on DTDs anymore. Instead of the Document Type Declaration, the version attribute identifies the DocBook version, as shown in Example 1.2, “DocBook V5.0 document”.

  1 <?xml version="1.0" encoding="utf-8"?>
  2 <article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
      <title>Sample article</title>
  4   <para>This is a very short article.</para>
    </article>

DocBook V5.0 is built on top of existing XML standards as much as possible. For example, the lang attribute is superseded by the standard xml:lang attribute.

Another fundamental change is that there is no direct indication of the schema used. In Chapter 3, Validating DocBook Documents, you will learn how you can specify a schema to be used for document validation.

The simple answer is “because DocBook V5.0 is the future.” Apart from this marketing blurb, there are also more technical reasons:

Schemas for DocBook V5.0 are available in several formats at http://www.oasis-open.org/docbook/xml/5.0/ (or the mirror at http://docbook.org/xml/5.0/). Only the RELAX NG schema is normative, and it is preferred over the other schema languages. For your convenience there are also DTD and W3C XML Schema versions provided for DocBook V5.0. However, neither the DTD nor the W3C XML schema can capture all the constraints of DocBook V5.0. This means that a document that validates against the DTD or XML schema is not necessarily valid against the RELAX NG schema, and thus may not be a valid DocBook V5.0 document.

DTD and W3C XML Schema versions of the DocBook V5.0 grammar are provided as a convenience for users who want to use DocBook V5.0 with legacy tools that don’t support RELAX NG. Authors are encouraged to switch to RELAX NG-based tools as soon as possible, or at least to validate documents against the RELAX NG schema before further processing.

Some document constraints can’t be expressed in grammar-based schema languages like RELAX NG or W3C XML Schema. To define these additional constraints DocBook V5.0 uses Schematron. We recommend that you validate your document against both the RELAX NG and Schematron schemas.

Whether you’re just getting started with DocBook, or curating a collection of tens of thousands of DocBook documents, one question that you have to consider is “how stable is DocBook?” Will the documents that you write today still be useful tomorrow, or next year, or in the next century?

This question may seem particularly pertinent if you’re in the process of converting a collection of DocBook 4.x documents to DocBook V5.0 because we introduced a number of backward-incompatible changes in V5.0.

The DocBook Technical Committee understands that the community benefits from the long-term stability of the DocBook family of schemas. We also understand that DocBook must continue to adapt and change in order to remain relevant in a changing world.

All changes, and especially changes that are backward incompatible (changes that make a currently valid document no longer valid under a new version of the schema), have a cost associated with them. The technical committee must balance those costs against the need to remain responsive to the community’s desire to see DocBook grow to cover the new use cases that inevitably arise in documentation.

With that in mind, the DocBook Technical Committee has adopted the following policy on backward-incompatible changes. This policy spells out when backward-incompatible changes can occur and how much notice the technical committee must provide before adopting a schema that is backward incompatible with the current release.

This policy allows DocBook to continue to change and adapt while simultaneously guaranteeing that existing users will have sufficient advance notice to develop reasonable migration plans.

With respect to schema changes, the technical committee asserts that the following points will always apply:

By these rules, the technical committee can announce, in V5.1, for example, its plans to make a backward-incompatible change in V6.0. Then, in V6.0, if it’s been at least six months since V5.1 was released, it can make that change.

As a general rule, the technical committee tries to avoid backward-incompatible changes.