XML Hacks

Create Books, Technical Manuals, and Papers in XML with DocBook

If you are writing a book, a manual, or a specification, DocBook provides an unsurpassed vocabulary for collecting your thoughts and words in XML form.

DocBook (http://www.docbook.org/) is an XML vocabulary or document type that is suited for books, technical manuals, and papers about computer hardware and software. Work on DocBook began in 1991 as a joint project of O’Reilly and HaL Computer Systems (Fujitsu). The effort evolved and was taken over by a group of technical documentation experts called the Davenport Group in 1994. In 1998, DocBook came under the control of a technical committee at OASIS (http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook). For more details on the history of DocBook, see http://www.oasis-open.org/docbook/intro.shtml.

Initially, DocBook was an SGML document type, but after the emergence of XML, an XML DTD was offered as well. Currently, you can download DocBook as an SGML DTD (http://www.docbook.org/sgml/), an XML DTD (http://www.docbook.org/xml/), a RELAX NG schema (http://www.docbook.org/rng/) in either XML or compact syntax, or an XML Schema (http://www.docbook.org/xsd/). At this point, the SGML and XML DTDs are the official versions of DocBook, and the RELAX NG and XML Schema forms should become official when DocBook reaches Version 5.

Following is a sampling of the kinds of elements you can use to mark up a document with DocBook:

• Books, manuals, articles, papers

• Tables of contents

• Chapters and sections

• Paragraphs

• Notes, cautions, and warnings

• Tables

• Images, graphics, callouts

• Code

• Author information

• Appendices

• Glossaries

• Indexes

Example 4-5 shows an article marked up with DocBook elements and called article.xml . It uses the DocBook 4.3 DTD and is valid with regard to it.

Example 4-5. article.xml

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
<title>The Legend of Wy'east</title>
 <articleinfo>
  <author>
   <firstname>Mike</firstname>
   <surname>Fitzgerald</surname>
  </author>
  <authorinitials>mjf</authorinitials>
  <pubdate>April 2004</pubdate>
  <revhistory>
   <revision>
    <revnumber>1.0</revnumber>
    <date>2004-04-07</date>
   </revision>
  </revhistory>
 </articleinfo>
  <para>According to local native legend, Wy'east (WHY east) was a 
  chief of the Multnomah peoples who loved a beautiful maiden named 
  Loo-wit. Klickitat, chief of the Klickitat tribe, also loved her.</para>
  <para>Loo-wit had brought fire back to the Multnomah and Klickitat
  peoples. The Great Spirit commanded her to light a fire on the 
  stone bridge across what we now call the Columbia River to help 
  restore warmth and light to the tribes who had fallen into a long 
  season of wrongdoing. The stone bridge was supposed to be a symbol 
  of peace between the warring peoples.</para>
  <para>Time passed and Loo-wit could not decide which of the 
  handsome young chiefs she liked better, Wy'east or Klickitat, so 
  the two chiefs began to quarrel. The Great Spirit became angry at 
  the squabbling chiefs. He dashed the stone arch into the river, and 
  turned Wy'east into Mt. Hood in northwest Oregon and Klicktat into 
  Mt. Adams in southwest Washington. Loo-wit became Washington's Mt. 
  St. Helens. The trio are still said to be angry with one another
  expressed by volcanic activity.</para>
  <bibliography>
   <bibliomixed>
    <author><firstname>Ella E.</firstname>
       <surname>Clark</surname></author>
    <copyright><year>1953</year></copyright>
    <publisher>
     <publishername>University of California Press</publishername>
    </publisher>
    <title>Indian Legends of the Pacific Northwest</title>
    <pagenums>20</pagenums>
   </bibliomixed>
   <bibliomixed>
    <author>
     <firstname>John</firstname>
     <othername role="middle">Foeste</othername>
     <surname>Graner</surname>
    </author>
    <copyright><year>1975</year></copyright>
    <title>Mount Hood: A Complete History</title>
    <pagenums>8</pagenums>
   </bibliomixed>
  </bibliography>
 </article>

This document is valid with regard to the DocBook DTD shown in the document type declaration (lines 2 and 3). The document element is article (line 4), and the title is on line 5. Following that is information about the article (articleinfo on line 6), including the title, the author, when it was published, and some revision history (lines 6 through 19). The body of the article is held in para elements (lines 20, 23, and 29). At the end of the section is a bibliography (lines 37 through 58), including information about books that were referenced to write the article. You can look up reference information about any DocBook element online at http://www.docbook.org/tdg/en/html/part2.html.

See Also

• DocBook also offers a smaller, proper subset called Simplified DocBook: http://www.docbook.org/specs/wd-docbook-simple-1.1b2.html

• The DocBook open repository on SourceForge has all kinds of supporting files, such as XSLT stylesheets, test documents, templates for slide presentations, and more: http://sourceforge.net/projects/docbook/

• DocBook: The Definitive Guide, by Norman Walsh (O’Reilly); also available online at http://www.docbook.org/tdg/en/html/part2.html