Building DocBook XML in eclipse

Entry

This article demonstrates how to use the DocBook XML and Eclipse Integrated development Environment (IDE) to create reusable technical documents that are easily distributed in a variety of formats. DocBook XML is a standard XML tag library that you can use to write style sheets that generate almost any output. However, since DocBook has existed for nearly 10 years, many style sheets have been written to generate many types of documents, including HTML, text, PDFs, and manuals.

After you've read this article, you should be able to use DocBook XML to create documents that can be HTML-formatted and available to the Eclipse help plug-in and PDFs from a single XML source file. You should have some knowledge of XML usage and should be able to use Eclipse and Apache ant, including running Ant build files from the Eclipse IDE. You need to use Eclipse V3.2 or later, DocBook XML v4.x document type definition (document type DEFINITION,DTD), DocBook XSL style sheet, Apache xalan-java™, and (optional) Apa Che FOP (see Resources for download).

DocBook XML Overview

DocBook XML is an XML tag library that is suitable for writing documents. The many available tags in DocBook make it the best choice for building technical documents. Because DocBook is XML, you can use style sheets to convert it to many different output formats, and stylesheets make DocBook XML the best choice for writing technical documents at once and generating technical documents in various formats.

Note: The code in this article is developed using DocBook XML V4.5, and V5.0 is in pre-release state when writing this article.

Advanced elements

The elements shown in table 1 are often used as high-level elements for DocBook XML files.

Table 1. Top-level DocBook XML element

Elements	Description
Book	contains many other elements; the only advanced element is the <set>
Chapter	Part of the book
Article	An article that can also be included in a book

Content element

Within more advanced elements, you might want to add actual content--paragraphs, tables, lists, code samples, and so on. Table 2 lists some of the common elements that are used when adding content to books, chapters, or articles.

Table 2. Elements

/tr>

element	description
caution	contains warning reader actions may result in data loss, hardware loss Bad or software problem text
code	contains inline Code, such as this
example	code example with caption
itemizedlist	List of entries with optional bullet point
contains text that draws the reader's attention specifically to
List of numbered entries; You do not have to number the list at build time--the style sheet will perform the action for you
text paragraph or text block
table	text table or datasheet
tip
title	title related to the element