Difficulty: ★☆☆ (easy)
Keywords: top level, namespace

Problem

You want to know what root elements are possible and what else is needed to create a DocBook V5 document.

Solution

A document type definition (DTD) allows every definied element to become a root element. A DTD cannot express any constraints to limit this set. On the other hand, RELAX NG—the official schema language for DocBook 5 and up—can impose such constraints.

To create a valid DocBook V5 document you need:

  • A valid DocBook V5 element to begin your document.

  • An attribute version containing the used DocBook version.

  • The DocBook 5 namespace, possibly other namespaces too.

To assemble all the above hints, a valid DocBook 5 document could look like this:

Example 1.1. A Valid DocBook 5 Book
<book version="5.0" xmlns="http://docbook.org/ns/docbook">
  <title>The Example Book</title>
  <chapter>
     <title>An Example Chapter</title>
     <para>This is a paragraph.</para>
  </chapter>
</book>

Discussion

There are many more possible root elements, not only book. Using the list from the last section, a valid DocBook V5 element to start with can be:

acknowledgementsdedicationreferencesect3
appendixglossaryrefsect1sect4
articleindexrefsect2sect5
bibliographypararefsect3section
bookpartrefsectionset
chapterprefacesect1setindex
colophonrefentrysect2toc

For the next DocBook release, V5.1, the technical committee plans to include all elements that can contain an info wrapper.

Regarding namespaces, DocBook 5 uses only one namespace (which is http://docbook.org/ns/docbook). However, sometimes it is needed to include other in order to adhere to the XML specification.

A namespace declaration consists of an (optional) namespace prefix and a namespace URI. The prefix may be selected arbitrarily, however, it is recommended to use the prefixes from Table 1.1, “Common Prefixes and Their Namespaces”. Although they are not a “standard” in its strict sense, over time they have been extensively used.

Table 1.1. Common Prefixes and Their Namespaces
PrefixNamespace
d[a], dbhttp://docbook.org/ns/docbook
fohttp://www.w3.org/1999/XSL/Format
hhttp://www.w3.org/1999/xhtml
mmlhttp://www.w3.org/1998/Math/MathML
rnghttp://relaxng.org/ns/structure/1.0
svghttp://www.w3.org/2000/svg
xihttp://www.w3.org/2001/XInclude
xlinkhttp://www.w3.org/1999/xlink
xsdhttp://www.w3.org/2001/XMLSchema
xslhttp://www.w3.org/1999/XSL/Transform

[a] In this book the DocBook prefix is omitted and the standard namespace is used.

Usually it is a good idea to insert all the namespaces used in the document into the root element. Example 1.2, “Start Tag with Several Namespace Declarations”, shows three namespace declarations: the DocBook namespace, using no prefix; the XInclude namespace using the xi prefix, and the XLink namespace using the xlink prefix.

Example 1.2. Start Tag with Several Namespace Declarations
<book version="5.0"
   xmlns="http://docbook.org/ns/docbook"
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xmlns:xlink="http://www.w3.org/1999/xlink">

Project@GitHubIssue#6