SGML documents begin with an optional SGML Declaration. The declaration can precede the document instance, but generally it is stored in a separate file that is associated with the DTD. The SGML Declaration is a grab bag of SGML defaults. DocBook includes an SGML Declaration that is appropriate for most DocBook documents, so we won't go into a lot of detail here about the SGML Declaration.

In brief, the SGML Declaration describes, among other things, what characters are markup delimiters (the default is angle brackets), what characters can compose tag and attribute names (usually the alphabetical and numeric characters plus the dash and the period), what characters can legally occur within your document, how long SGML “names” and “numbers” can be, what sort of minimizations (abbreviation of markup) are allowed, and so on. Changing the SGML Declaration is rarely necessary, and because many tools only partially support changes to the declaration, changing it is best avoided, if possible.

Wayne Wholer has written an excellent tutorial on the SGML Declaration; if you're interested in more details, see http://www.oasis-open.org/cover/wlw11.html.

All SGML documents must begin with a document type declaration. This 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 document looks like this:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

This declaration indicates that the root element, which is the first element in the hierarchical structure of the document, will be <book> and that the DTD used will be the one identified by the public identifier -//OASIS//DTD DocBook V3.1//EN. See the section called “Public Identifiers”” later in this chapter.

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

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!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 and it is technically optional. It is legal to put the DTD in the internal subset and to have no external subset, but for a DTD as large as DocBook that wouldn't make much sense.

Although comments and processing instructions may occur between the document type declaration and the root element, the root element usually immediately follows the document type declaration:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!ENTITY nwalsh "Norman Walsh">
<!ENTITY chap1 SYSTEM "chap1.sgm">
<!ENTITY chap2 SYSTEM "chap2.sgm">
]>
<book>
&chap1;
&chap2;
</book>

You cannot place the root element of the document in an external entity.

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

If you are willing to modify both the declaration and the DTD, even more dramatic minimizations are possible, including completely omitted tags and “shortcut” markup.

XML documents should begin with an XML declaration. Unlike the SGML declaration, which is a grab bag of features, the XML declaration identifies a few simple aspects of the document:

<?xml version="1.0" standalone="no"?>

Identifying the version of XML ensures that future changes to the XML specification will not alter the semantics of this document. The standalone declaration simply makes explicit the fact that this document cannot “stand alone,” and that it relies on an external DTD. The complete details of the XML declaration are described in the XML specification.

Strictly speaking, XML documents don't require a DTD. Realistically, DocBook XML documents will have 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 document looks like this:

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
                         "http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd">

This declaration indicates that the root element will be <book> and that the DTD used will be the one indentified by the public identifier -//Norman Walsh//DTD DocBk XML V3.1.4//EN. 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.

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

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4/EN"
                         "http://nwalsh.com/docbook/xml/3.1.4/db3xml.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, but for a DTD as large as DocBook, that would make very little sense.

Although comments and processing instructions may occur between the document type declaration and the root element, the root element usually immediately follows the document type declaration:

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
                         "http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd" [
<!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 SGML 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.

Conceptually, almost everything in this book applies equally to SGML and XML. But because DocBook V3.1 is an SGML DTD, we naturally tend to use SGML conventions in our writing. If you're primarily interested in XML, there are just a few small details to keep in mind.

For a more detailed discussion of DocBook and XML, see Appendix B, DocBook and XML.

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.

Catalog files are the standard mechanism for resolving public identifiers into system identifiers. Some resolution mechanism is necessary because DocBook refers to its component modules with public identifiers, and those must be mapped to actual files on the system before any piece of software can actually load them.

The catalog file format was defined in 1994 by SGML Open (now OASIS). The formal specification is contained in OASIS Technical Resolution 9401:1997.

Informally, a catalog is a text file that contains a number of keyword/value pairs. The most frequently used keywords are PUBLIC, SYSTEM, SGMLDECL, DTDDECL, CATALOG, OVERRIDE, DELEGATE, and DOCTYPE.

A small fragment of an actual catalog file is shown in Example 2.1, “A Sample Catalog”.

                                                           
-- Comments are delimited by pairs of double-hyphens,
   as in SGML and XML comments. --
                                                           
OVERRIDE YES
                                                           
SGMLDECL "n:/share/sgml/docbook/3.1/docbook.dcl"
                                                           
DOCTYPE  BOOK  n:/share/sgml/docbook/3.1/docbook.dtd
                                                           
PUBLIC "-//OASIS//DTD DocBook V3.1//EN" 
  n:/share/sgml/docbook/3.1/docbook.dtd
                                                           
SYSTEM "http://nwalsh.com/docbook/xml/1.3/db3xml.dtd"
  n:/share/sgml/Norman_Walsh/db3xml/db3xml.dtd

	Catalog files may also include comments.
	This catalog specifies that public identifiers should be used in favor of system identifiers, if both are present.
	The default declaration specified by this catalog is the DocBook declaration.
	Given an explicit (or implied) SGML DOCTYPE of <!DOCTYPE BOOK SYSTEM> use n:/share/sgml/docbook/3.1/docbook.dtd as the default system identifier. Note that this can only apply to SGML documents because the DOCTYPE declaration above is not a valid XML element.
	Map the OASIS public identifer to the local copy of the DocBook V3.1 DTD.
	Map a system identifer for the XML version of DocBook to a local version.

A few notes:

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 customization layer to impose a more strict ordering for your applications.

Books consist of a mixture of the following elements:

Components are the chapter-like elements of a Book or Part: Preface, Chapter, Appendix, Glossary, and Bibliography. Articles 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 include a wrapper for meta-information about the content. See, for example, BookInfo.

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>

<!DOCTYPE index PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<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.^[11]

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:

<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<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.