This chapter explains in concrete, practical terms how to make DocBook documents. It’s an overview of all the kinds of markup that are possible in DocBook documents. It explains how to create several kinds of DocBook documents: books, sets of books, chapters, articles, and reference manual entries. The idea is to give you enough basic information to actually start writing. The information here is intentionally skeletal; you can find the details in the reference section of this book.
An XML document consists of an optional XML declaration, an optional Document Type Declaration, which includes an optional internal subset, and a document (or root) element. We’ll discuss each of these in turn.
In XML vocabularies like DocBook, which are defined with RELAX NG (and also in the case of vocabularies defined with W3C’s XML Schema), it is common to omit the Document Type Declaration entirely. The Document Type Declaration associates a document with a particular Document Type Definition (DTD).
XML documents often begin with an XML declaration that identifies a few simple aspects of the document, for example:
<?xml version="1.0" encoding="utf-8"?>
Identifying the version of XML ensures that future changes to the XML specification will not alter the semantics of this document. The encoding declaration tells the processor what character encoding this document uses. It must match the actual encoding that you use. The complete details of the XML declaration are described in the W3C standard, Extensible Markup Language (XML) 1.0 [XML].
If your document uses XML 1.0 and an encoding
of either utf-8 or utf-16, the XML declaration
is not required. But it is never wrong to include it. If you do not
include an XML declaration, your document must
conform to XML 1.0. If you want to use
XML 1.1, you must include an XML
declaration and specify version="1.1" in it.
The XML declaration is syntactically similar to a processing instruction, but it is not one. The XML declaration, if it is present, must be absolutely the first thing in your document and it may not appear anywhere else.
XML documents don’t require a DTD, and if you are using RELAX NG, often they will not include one. Historically, DocBook XML documents have almost always had one.
The Document Type Declaration identifies what the root element of the document will be and may specify the DTD that should be used when parsing the document. A typical Document Type Declaration for a DocBook V4.5 document looks like this:
<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">This declaration indicates that the root element will be
book and that the DTD used will be
DocBook V4.5, identified with both its public and
system identifiers. In this example, the DTD is
identified with an HTTP URI.
System identifiers in XML must be
URIs. Almost all systems accept filenames and
interpret them locally as file:
URLs, but it’s always correct to fully qualify
them.
You can specify a DTD for DocBook V5.0 documents:
<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
"http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd">But the limited constraints that can be expressed in DTDs mean that the resultant document may or may not really be valid DocBook V5.0. The normative schema for DocBook V5.0 is the RELAX NG grammar with its Schematron annotations.
The only reason to use a DTD with DocBook V5.0 is if your editing environment (or other tool) requires one, for example, for syntax-directed editing. If you’re using a tool that requires DTDs, check with the vendor, as maybe a more recent version is available that supports RELAX NG.
Even if you aren’t using the DTD version of DocBook V5.0, you may still want to use a Document Type Declaration to provide local declarations such as entities:
<?xml version='1.0'?> <!DOCTYPE book [ <!ENTITY nwalsh "Norman Walsh"> <!ENTITY chap1 SYSTEM "chap1.xml"> <!ENTITY chap2 SYSTEM "chap2.xml"> ]>
These declarations form what is known as the internal subset. In this example, the DTD has been omitted, but the two are not mutually exclusive. If you are using a DTD (which is technically known as the external subset), you can include the internal subset immediately after the DTD:
<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0/EN"
"http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd" [
<!ENTITY nwalsh "Norman Walsh">
<!ENTITY chap1 SYSTEM "chap1.xml">
<!ENTITY chap2 SYSTEM "chap2.xml">
]>When both are specified, the internal subset is parsed first. If multiple declarations for an entity occur, the first declaration is used. This means that declarations in the internal subset override declarations in the external subset.
All XML documents must have exactly one root element, although it may have sibling comments and processing instructions. If the document has a Document Type Declaration, the root element usually immediately follows it:
<?xml version='1.0'?> <!DOCTYPE book [ <!ENTITY nwalsh "Norman Walsh"> <!ENTITY chap1 SYSTEM "chap1.xml"> <!ENTITY chap2 SYSTEM "chap2.xml"> ]> <book xmlns="http://docbook.org/ns/docbook" version="5.0">…</book>
The important point is that the root element must be physically present immediately after the Document Type Declaration. You cannot place the root element of the document in an external entity.