Semantic markup makes your documents more amenable to interpretation by software, especially publishing software. You can publish a white paper, authored as a DocBook Article, in the following formats:

You can produce each of these publications from exactly the same source document using the presentational techniques best suited to both the content of the document and the presentation medium. This versatility also frees the author to concentrate on the document content. For example, as we write this book, we don't know exactly how O'Reilly will choose to present chapter headings, bulleted lists, SGML terms, or any of the other semantic features. And we don't care. It's irrelevant; whatever presentation is chosen, the SGML sources will be transformed automatically into that style.

Semantic markup can relieve the author of other, more significant burdens as well (after all, careful use of paragraph and character styles in a word processor document theoretically allows us to change the presentation independently from the document). Using semantic markup opens up your documents to a world of possibilities. Documents become, in a loose sense, databases of information. Programs can compile, retrieve, and otherwise manipulate the documents in predictable, useful ways.

Consider the online version of this book: almost every element name (Article, Book, and so on) is a hyperlink to the reference page that describes that element. Maintaining these links by hand would be tedious and might be unreliable, as well. Instead, every element name is marked as an element using SGMLTag: a Book is a <sgmltag>Book</sgmltag>.

Because each element name in this book is tagged semantically, the program that produces the online version can determine which occurrences of the word “book” in the text are actually references to the Book element. The program can then automatically generate the appropriate hyperlink when it should.

There's one last point to make about the versatility of SGML documents: how much you have depends on the DTD. If you take a good photo with a high resolution lens, you can print it and copy it and scan it and put it on the Web, and it will look good. If you start with a low-resolution picture it will not survive those transformations so well. DocBook SGML/XML has this advantage over, say, HTML: DocBook has specific and unambiguous semantic and structural markup, because you can convert its documents with ease into other presentational forms, and search them more precisely. If you start with HTML, whose markup is at a lower resolution than DocBook's, your versatility and searchability is substantially restricted and cannot be improved.

There are a few significant shortcomings to structured authoring:

With internal entities, you can associate an essentially arbitrary piece of text (which may have other markup, including references to other entities) with a name. You can then include that text by referring to its name. For example, if your document frequently refers to, say, “O'Reilly & Associates,” you might declare it as an entity:

<!ENTITY ora "O'Reilly &amp; Associates">

Then, instead of typing it out each time, you can insert it as needed in your document with the entity reference &ora;, simply to save time. Note that this entity declaration includes another entity reference within it. That's perfectly valid as long as the reference isn't directly or indirectly recursive.

If you find that you use a number of entities across many documents, you can add them directly to the DTD and avoid having to include the declarations in each document. See the discussion of dbgenent.mod in Chapter 5, Customizing DocBook.

With external entities, you can reference other documents from within your document. If these entities contain document text (SGML or XML), then references to them cause the parser to insert the text of the external file directly into your document (these are called parsed entities). In this way, you can use entities to divide your single, logical document into physically distinct chunks. For example, you might break your document into four chapters and store them in separate files. At the top of your document, you would include entity declarations to reference the four files:

<!ENTITY ch01 SYSTEM "ch01.sgm">
<!ENTITY ch02 SYSTEM "ch02.sgm">
<!ENTITY ch03 SYSTEM "ch03.sgm">
<!ENTITY ch04 SYSTEM "ch04.sgm">

Your Book now consists simply of references to the entities:

<book>
&ch01;
&ch02;
&ch03;
&ch04;
</book>

Sometimes it's useful to reference external files that don't contain document text. For example, you might want to reference an external graphic. You can do this with entities by declaring the type of data that's in the entity using a notation (these are called unparsed entities). For example, the following declaration declares the entity tree as an encapsulated PostScript image:

<!ENTITY tree SYSTEM "tree.eps" NDATA EPS>

Entities declared this way cannot be inserted directly into your document. Instead, they must be used as entity attributes to elements:

<graphic entityref="tree"></graphic>

Conversely, you cannot use entities declared without a notation as the value of an entity attribute.

In order for the parser to recognize markup in your document, it must be able to distinguish markup from content. It does this with two special characters: “<,” which identifies the beginning of a start or end tag, and “&,” which identifies the beginning of an entity reference.^[4] If you want these characters to have their literal value, they must be encoded as entity references in your document. The entity reference < produces a left angle bracket; & produces the ampersand.^[5]

If you do not encode each of these as their respective entity references, then an SGML parser or application is likely to interpret them as characters introducing elements or entities (an XML parser will always interpret them this way); consequently, they won't appear as you intended. If you wish to cite text that contains literal ampersands and less-than signs, you need to transform these two characters into entity references before they are included in a DocBook document. The only other alternative is to incorporate text that includes them in your document through some process that avoids the parser.

In SGML, character entities are frequently declared using a third entity category (one that we deliberately chose to overlook), called data entities. In XML, these are declared using numeric character references. Numeric character references resemble entity references, but technically aren't the same. They have the form ϧ, in which “999” is the numeric character number.

In XML, the numeric character number is always the Unicode character number. In addition, XML allows hexadecimal numeric character references of the form &#xhhhh;. In SGML, the numeric character number is a number from the document character set that's declared in the SGML declaration.

Character entities are also used to give a name to special characters that can't otherwise be typed or are not portable across applications and operating systems. You can then include these characters in your document by refering to their entity name. Instead of using the often obscure and inconsistent key combinations of your particular word processor to type, say, an uppercase letter U with an umlaut (Ü), you type in an entity for it instead. For instance, the entity for an uppercase letter U with an umlaut has been defined as the entity Uuml, so you would type in Ü to reference it instead of the actual character. The SGML application that eventually processes your document for presentation will match the entity to your platform's handling of special characters in order to render it appropriately.

You might use a parameter entity reference in an SGML document in a marked section. Marking sections is a mechanism for indicating that special processing should apply to a particular block of text. Marked sections are introduced by the special sequence <![keyword[ and end with ]]>. In SGML, marked sections can appear in both DTDs and document instances. In XML, they're only allowed in the DTD.^[6]

The most common keywords are INCLUDE, which indicates that the text in the marked section should be included in the document; IGNORE, which indicates that the text in the marked section should be ignored (it completely disappears from the parsed document); and CDATA, which indicates that all markup characters within that section should be ignored except for the closing characters ]]>.

In SGML, these keywords can be parameter entities. For example, you might declare the following parameter entity in your document:

<!ENTITY % draft "INCLUDE">

Then you could put the sections of the document that are only applicable in a draft within marked sections:

<![%draft;[
<para>
This paragraph only appears in the draft version.
</para>
]]>

When you're ready to print the final version, simply change the draft parameter entity declaration:

<!ENTITY % draft "IGNORE">

and publish the document. None of the draft sections will appear.

The DocBook DTD was originally designed and implemented by HaL Computer Systems and O'Reilly & Associates around 1991. It was developed primarily to facilitate the exchange of UNIX documentation originally marked up in troff. Its design appears to have been based partly on input from SGML interchange projects conducted by the Unix International and Open Software Foundation consortia.

When DocBook V1.1 was published, discussion about its revision and maintenance began in earnest in the Davenport Group, a forum created by O'Reilly for computer documentation producers. Version 1.2 was influenced strongly by Novell and Digital.

In 1994, the Davenport Group became an officially chartered entity responsible for DocBook's maintenance. DocBook V1.2.2 was published simultaneously. The founding sponsors of this incarnation of Davenport include the following people:

Under the auspices of the Davenport Group, the DocBook DTD began to widen its scope. It was now being used by a much wider audience, and for new purposes, such as direct authoring with SGML-aware tools, and publishing directly to paper. As the largest users of DocBook, Novell and Sun had a heavy influence on its design.

In order to help users manage change, the new Davenport charter established the following rules for DocBook releases:

V3.0 was released in January 1997. After that time, although DocBook's audience continued to grow, many of the Davenport Group stalwarts became involved in the XML effort, and development slowed dramatically. The idea of creating an official XML-compliant version of DocBook was discussed, but not implemented. (For more detailed information about DocBook V3.0 and plans for subsequent versions, see Appendix C, DocBook Versions.)

The sponsors wanted to close out Davenport in an orderly way to ensure that DocBook users would be supported. It was suggested that OASIS become DocBook's new home. An OASIS DocBook Technical Committee was formed in July, 1998, with Eduardo Gutentag of Sun Microsystems as chair.

The DocBook Technical Commitee is continuing the work started by the Davenport Group. The transition from Davenport to OASIS has been very smooth, in part because the core design team consists of essentially the same individuals (we all just changed hats).

DocBook V3.1, published in February 1999, was the first OASIS release. It integrated a number of changes that had been “in the wings” for some time.

In February of 2001, OASIS made DocBook SGML V4.1 and DocBook XML V4.1.2 official OASIS Specifications.

Version 4.2 of the DocBook DTD, for both SGML and XML, was released in July 2002.

The committee continues new DocBook development to ensure that the DTD continues to meet the needs of its users. Forthcoming and experimental work includes: