DocBook: Write Once, Read Anywhere Documentation

ocBook is an OASIS standard for creating technical documentation in XML. The documentation from Spring or Hibernate is generated from DocBook. Particularly suited for computer-related content, DocBook is a set of XML tags, defined by a Document Type Definition (DTD) and XML schema for technical content. In addition to the DTD, DocBook and other open source projects supply a collection of tools and frameworks that enable developers to transform DocBook-compliant XML into PDF, HTML, Eclipse Help, and even MAN pages. This alleviates the need to write the same material multiple times or manually convert from one format to another.

No big deal, you say. I can write HTML, Eclipse Help, and PDF if I have to. Why is DocBook different? In the DocBook model, you write the raw documentation once in XML and then transform or "compile" it to the desired target formats using DocBook tools—a paradigm familiar to developers, who already code and compile. So DocBook is ideal for developers who have to write documentation, not only because it is targeted for technical content but also because DocBook files—like any other XML files—can be managed and edited within an IDE. No longer is documentation someone else's problem; it's right there next to your code. This encourages you keep the software documentation in sync as you develop.

Because the DocBook XML structure is focused on structure and content rather than presentation, you do not have to worry about formatting and presentation aspects. The XML transformation tools and style sheets take care of these details. The transformation tools ensure a uniform look and feel to the generated documentation, and you can customize it separately from the raw content.

This article introduces DocBook and explains how to use it for the following:

1. Writing a simple document
2. Transforming it into PDF and HTML using the Velocity DocBook framework
3. Automatically interleaving source code extracts into your documentation

DocBook Introduction
A DocBook-compliant XML file doesn't require any special documentation tools—any XML editor or IDE plug-in will do, provided it can access the DocBook DTD to understand the DocBook tags and validate the XML. Several free and commercial WYSIWYG Eclipse plugins and standalone editors are available, but any standard XML editor or IDE plug-in, such as the ones that come with WTP or MyEclipse, will suffice.

Once the documentation is in the development environment, you can seamlessly integrate it into the development processes. Your DocBook artifacts can be:

• Placed under version control so that they can be checked-in, checked-out, tagged, and branched with releases
• Edited within your development environment using standard IDEs and readily available XML editor plug-ins
• Kept in sync with code and included in any code refactoring. When a classname changes so do the references in the documentation
• Integrated with your continuous and nightly build processes so that the documentation distributions (PDF, HTML, etc.) are built automatically

There are many tags in DocBook, such as <book>, <chapter>, and <title>, as well as more programming-specific elements such as <classname>, <programlisting>, and <database>. However, you don't need to know them all to get started—just a few basic elements. A simple DocBook XML file is comprised of a <Book>, which contains one or more <chapter> elements. A book is a single deliverable documentation artifact with chapters that correspond to logical sections within your end document. Chapters are hierarchical; a chapter can contain other chapters, and they can be nested indefinitely.

The following is a simple DocBook XML document that you will use as an example in this article. It contains a title, bookinfo, a table of contents, and two chapters, each containing some text:

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

  <bookinfo>
    <releaseinfo>V 1.0</releaseinfo>
    <author>devx
    </author>

  </bookinfo>

  <toc/>
  
  <chapter id="intro">
    <title>Introduction</title>
    <para>DocBook is simple to use and provides a rich set of tags for common elements.</para>  
  </chapter>
  
  <chapter id="basics">
    <title>Basic Elements</title>
    <para>This section describes the basic tags.</para>
  </chapter>
  
</book>

Note the DTD reference at the top. This reference must be present for your XML editor to understand and validate your XML against the DocBook structure and provide content assistance.

Next Page