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:

  1 <?xml version='1.0'?>
  2 <!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:

  1 <?xml version='1.0'?>
  2 <!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:

  1 <?xml version='1.0'?>
  2 <!DOCTYPE book [
    <!ENTITY nwalsh "Norman Walsh">
  4 <!ENTITY chap1 SYSTEM "chap1.xml">
    <!ENTITY chap2 SYSTEM "chap2.xml">
  6 ]>

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:

  1 <?xml version='1.0'?>
  2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0/EN"
                   "http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd" [
  4 <!ENTITY nwalsh "Norman Walsh">
    <!ENTITY chap1 SYSTEM "chap1.xml">
  6 <!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:

  1 <?xml version='1.0'?>
  2 <!DOCTYPE book [
    <!ENTITY nwalsh "Norman Walsh">
  4 <!ENTITY chap1 SYSTEM "chap1.xml">
    <!ENTITY chap2 SYSTEM "chap2.xml">
  6 ]>
    <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.

A set contains two or more books. It’s the hierarchical top of DocBook. You use the set tag, for example, for a series of books on a single subject that you want to access and maintain as a single unit, such as the manuals for series of computer systems or the documentation (tutorial, reference, etc.) for a programming language. Sets are allowed to contain other sets, though this is not common.

A book is probably the most common top-level element in a document. The DocBook definition of a book is very loose and general. Given the variety of books authored with DocBook and the number of different conventions for book organization used around the world, any attempt to impose a strict ordering of elements would make the content model extremely complex. Therefore, DocBook gives you free rein. You can use a local customization (see Chapter 5, Customizing DocBook) if you want to impose a more strict ordering for your applications.

A book consists of a mixture of the following elements:

Components are the chapter-like elements of a book or part: preface, chapter, appendix, glossary, and bibliography. An article can also occur at the component level. We describe articles in more detail in Section 7, “Making an Article”. Components generally contain block elements and/or sections, and some can contain navigational components and refentrys.

There are several flavors of sectioning elements in DocBook:

All of the elements at the section level and above, and many other elements, include a wrapper for meta-information about the content. That element is named info. In earlier versions of DocBook, there were many similarly named elements for this purpose: bookinfo, chapterinfo, etc. In DocBook V5.0, there is only one.

The meta-information wrapper is designed to contain bibliographic information about the content (author, title, publisher, and so on) as well as other meta-information such as revision histories, keyword sets, and index terms.

An info can contain:

The title, titleabbrev, and subtitle elements can usually appear either immediately before or inside the info wrapper (but not both). This means you don’t need the extra wrapper in the common case where all you want to specify is a title.

The block elements occur immediately below the component and sectioning elements. These are the (roughly) paragraph-level elements in DocBook. They can be divided into a number of categories: lists, admonitions, line-specific environments, synopses of several sorts, tables, figures, examples, and a dozen or more miscellaneous elements.

Users of DocBook are provided with a surfeit of inline elements. Inline elements are used to mark up running text. In published documents, inline elements often cause a font change or other small change, but they do not cause line or paragraph breaks.

In practice, writers generally settle on the tagging of inline elements that suits their time and subject matter. This may be a large number of elements or only a handful. What is important is that you choose to mark up not every possible item, but only those for which distinctive tagging will be useful in the production of the finished document for the readers who will search through it.

The following comprehensive list may be a useful tool for the process of narrowing down the elements that you will choose to mark up; it is not intended to overwhelm you by its sheer length. For convenience, we’ve divided the inlines into several subcategories.

The classification used here is not meant to be authoritative, only helpful in providing a feel for the nature of the inlines. Several elements appear in more than one category, and arguments could be made to support the placement of additional elements in other categories or entirely new categories.

In some highly structured documents such as reference manuals, you can automate the whole process of generating an index successfully without altering or adding to the original source. You can design a processing application to select the information and compile it into an adequate index. But this is rare.

In most cases—and even in the case of some reference manuals—a useful index still requires human intervention to mark occurrences of words or concepts that will appear in the text of the index.

  1 <para>
  2   <indexterm><primary>Big Cats</primary>
      <secondary>Tigers</secondary></indexterm>
  4   The tiger is a very large cat indeed.
    </para>

  1 <para>
  2   <indexterm xml:id="tiger-desc" class="startofrange">
      <primary>Big Cats</primary>
  4   <secondary>Tigers</secondary></indexterm>
      The tiger is a very large cat indeed…
  6 </para>
    ⋮
  8 <para>
    So much for tigers<indexterm startref="tiger-desc" class="endofrange"/>.
 10 Let's talk about leopards.  
    </para>

  1 <indexterm zone="tiger-desc">
  2 <primary>Big Cats</primary>
    <secondary>Tigers</secondary></indexterm>

  1 <index><title>Index</title>
  2   <indexdiv><title>D</title>
        <indexentry>
  4       <primaryie>database (bibliographic), 253, 255</primaryie>
             <secondaryie>structure, 255</secondaryie>
  6          <secondaryie>tools, 259</secondaryie>
        </indexentry>
  8     <indexentry>
          <primaryie>dates (language specific), 179</primaryie>
 10     </indexentry>
        <indexentry>
 12       <primaryie>DC fonts, <emphasis>172</emphasis>, 177</primaryie>
             <secondaryie>Math fonts, 177</secondaryie>
 14     </indexentry>
      </indexdiv>
 16 </index>

A glossary, like a bibliography, is often constructed by hand. However, some applications are capable of building a skeletal index from glossary term markup in the document. If all of your terms are defined in some glossary database, it may even be possible to construct the complete glossary automatically.

To enable automatic glossary generation, or simply automatic linking from glossary terms in the text to glossary entries, you must add markup to your documents. In the text, you mark up a term for compilation later with the inline glossterm tag. This tag can have a linkend attribute whose value is the ID of the actual entry in the glossary.^[1]

For instance, if you have this markup in your document:

<glossterm linkend="xml">Extensible Markup Language</glossterm> is a new standard… 

your glossary might look like this:

  1 <glossary><title>Example Glossary</title>
  2 ⋮
      <glossdiv><title>E</title>
  4 
        <glossentry xml:id="xml"><glossterm>Extensible Markup Language</glossterm>
  6       <acronym>XML</acronym>
          <glossdef>
  8        <para>Some reasonable definition here.</para>
           <glossseealso otherterm="sgml">
 10       </glossdef>
        </glossentry>
 12 
      </glossdiv>
 14 ⋮
    </glossary>

Note that the glossterm tag reappears in the glossary to mark up the term and distinguish it from its definition within the glossentry. The xml:id that the glossentry referenced in the text is the ID of the glossentry in the glossary itself. You can use the link between source and glossary to create a link in electronic formats, as we have done with the HTML and PDF forms of the glossary in this book.

You can use the baseform attribute on glossterm and firstterm when the term marked up in context is in a different form, for example, plural. Here is an example:

  1 <para>
  2   Using <glossterm baseform="DTD">DTDs</glossterm> can
      be hazardous to your sanity.
  4 </para>

There are two ways to set up a bibliography in DocBook: you can have the data raw or cooked. When you use “raw” data, you wrap your entry in the biblioentry element and mark up each item individually. The processor determines the display order and supplies punctuation. When you use “cooked” data, you wrap your entry in the bibliomixed and provide the data in the order in which you want it displayed, and you include the punctuation.

Here’s an example of a raw bibliographical item, wrapped in the biblioentry element:

  1 <biblioentry xreflabel="Kites75">
  2   <authorgroup>
        <author><firstname>Andrea</firstname><surname>Bahadur</surname></author>
  4     <author><firstname>Mark</firstname><surname>Shwarek</surname></author>
      </authorgroup>
  6   <copyright><year>1974</year><year>1975</year>
         <holder>Product Development International Holding N. V.</holder>
  8      </copyright>
      <isbn>0-88459-021-6</isbn>    
 10   <publisher>
        <publishername>Plenary Publications International, Inc.</publishername>
 12   </publisher>
      <title>Kites</title>
 14   <subtitle>Ancient Craft to Modern Sport</subtitle>
      <pagenums>988-999</pagenums>
 16   <seriesinfo>
        <title>The Family Creative Workshop</title>
 18     <seriesvolnums>1-22</seriesvolnums>
        <editor>
 20       <firstname>Allen</firstname>
          <othername role=middle>Davenport</othername>
 22       <surname>Bragdon</surname>
          <contrib>Editor in Chief</contrib>
 24     </editor>
      </seriesinfo>
 26 </biblioentry>

The “raw” data in a biblioentry is comprehensive to a fault—there are enough fields to suit a host of different bibliographical styles, and that is the point. An abundance of data requires processing applications to select, punctuate, order, and format the bibliographical data, and it is unlikely that all the information provided will actually be output.

All the “cooked” data in a bibliomixed entry in a bibliography, on the other hand, is intended to be presented to the reader in the form and sequence in which it is provided. It even includes punctuation between the fields of data:

  1 <bibliomixed>
  2   <bibliomset relation="article">
        <surname>Walsh</surname>, <firstname>Norman</firstname>.
  4     <title role="article">Introduction to Cascading Style Sheets</title>.
      </bibliomset>
  6   <bibliomset relation="journal">
        <title>The World Wide Web Journal</title> 
  8     <volumenum>2</volumenum><issuenum>1</issuenum>.
        <publishername>O'Reilly & Associates, Inc.</publishername> and
 10     <corpname>The World Wide Web Consortium</corpname>.
        <pubdate>Winter, 1996</pubdate></bibliomset>.
 12 </bibliomixed>

Clearly, these two ways of marking up bibliographical entries are suited to different circumstances. You should use one or the other for your bibliography, not both. Strictly speaking, mingling the raw and the cooked may be “kosher” as far as the schema is concerned, but it will almost certainly cause problems for most processing applications.