XML documents often begin with an XML declaration that identifies a few simple aspects of the document:

<?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 your document uses. It must match the actual encoding that you use. The complete details of the XML declaration are described in the XML specification.

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.

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 the DTD that will be used by the document and what the root element of the document will be. A typical doctype declaration for a DocBook V4.4 document looks like this:

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
               "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

This declaration indicates that the root element will be book and that the DTD used will be DocBook V4.4. External declarations in XML must include a system identifier (the public identifier is optional). In this example, the DTD is stored on a web server. System identifiers in XML must be URIs. Many systems may accept filenames and interpret them locally as file: URLs, but it's always correct to fully qualify them.

DocBook V5.0 documents can be validated with a 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">

But the limited constraints that can be expressed in DTDs mean that the resulting 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.

It's also possible to provide additional declarations in a document by placing them inside the document type declaration:

<?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.sgm">
<!ENTITY chap2 SYSTEM "chap2.sgm">
]>

These declarations form what is known as the internal subset. The declarations stored in the file referenced by the public or system identifier in the DOCTYPE declaration is called the external subset, which is technically optional. It is legal to put the DTD in the internal subset and to have no external subset, which often makes sense documents that will be validated with RELAX NG:

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

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.sgm">
<!ENTITY chap2 SYSTEM "chap2.sgm">
]>
<book>…</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.

If you are entering XML using a text editor such as Emacs or vi, there are a few things to keep in mind. Using a structured text editor designed for XML hides most of these issues.

An important characteristic of public identifiers is that they are globally unique. Referring to a document with a public identifier should mean that the identifier will resolve to the same actual document on any system even though the location of that document on each system may vary. As a rule, you should never reuse public identifiers, and a published revision should have a new public identifier. Not following these rules defeats one purpose of the public identifier.

A public identifier can be any string of upper- and lowercase letters, digits, any of the following symbols: “'”, “(“, “)”, “+”, “,”, “-”, “.”, “/”, “:”, “=”, “?”, and white space, including line breaks.

prefix//owner-identifier//
text-class text-description//
language//display-version

System identifiers are usually filenames on the local system. In SGML, there's no constraint on what they can be. Anything that your SGML processing system recognizes is allowed. In XML, system identifiers must be URIs (Uniform Resource Identifiers).

The use of URIs as system identifiers introduces the possibility that a system identifier can be a URN. This allows the system identifier to benefit from the same global uniqueness benefit as the public identifier. It seems likely that XML system identifiers will eventually move in this direction.

XML Catalogs are the standard mechanism for resolving public identifiers into system identifiers. Some systems also use SGML Open Catalogs.

FIXME: Rewrite this section in terms of XML Catalogs.

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 an airplane engine or the documentation for a programming language.

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 in countries around the world, attempting to impose a strict ordering of elements can make the content model extremely complex. But DocBook gives you free reign. It's very reasonable to use a local Chapter 5, Customizing DocBook 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 the section titled the section called “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 block elements further down, 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.

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.

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

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

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

<index><title>Index</title>
<indexdiv><title>D</title>
<indexentry>
  <primaryie>database (bibliographic), 253, 255</primaryie>
     <secondaryie>structure, 255</secondaryie>
     <secondaryie>tools, 259</secondaryie>
</indexentry>
<indexentry>
  <primaryie>dates (language specific), 179</primaryie>
</indexentry>
<indexentry>
  <primaryie>DC fonts, <emphasis>172</emphasis>, 177</primaryie>
     <secondaryie>Math fonts, 177</secondaryie>
</indexentry>
</indexdiv>
</index>

glossarys, like bibliographys, are 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 markup 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.^[3]

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:

<glossary><title>Example Glossary</title>
⋮
<glossdiv><title>E</title>

<glossentry id="xml"><glossterm>Extensible Markup Language</glossterm>
  <acronym>XML</acronym>
<glossdef>
  <para>Some reasonable definition here.</para>
  <glossseealso otherterm="sgml">
</glossdef>
</glossentry>

</glossdiv>

Note that the glossterm tag reappears in the glossary to mark up the term and distinguish it from its definition within the glossentry. The 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 the online form of your document, as we have done with the online form of the glossary in this book.

There are two ways to set up a bibliography in DocBook: you can have the data raw or cooked. Here's an example of a raw bibliographical item, wrapped in the biblioentry element:

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

<bibliomixed>
  <bibliomset relation=article>
    <surname>Walsh</surname>, <firstname>Norman</firstname>.
    <title role=article>Introduction to Cascading Style Sheets</title>.
  </bibliomset>
  <bibliomset relation=journal>
    <title>The World Wide Web Journal</title> 
    <volumenum>2</volumenum><issuenum>1</issuenum>.
    <publishername>O'Reilly & Associates, Inc.</publishername> and
    <corpname>The World Wide Web Consortium</corpname>.
    <pubdate>Winter, 1996</pubdate></bibliomset>.
</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 DTD is concerned, but it will almost certainly cause problems for most processing applications.