RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


DocBook: Write Once, Read Anywhere Documentation : Page 2

DocBook enables developers to create technical documentation in XML. Learn how to use it to transform its XML output to PDF and HTML automatically and integrate it into your development environment.

Transforming to HTML and PDF
Apache Velocity provides a framework for transforming DocBook XML files into HTML and PDF. Velocity uses a set of ANT build files for these transformations. For this article, download the Velocity DocBook framework and follow the installation instructions. In an IDE such as Eclipse, create a new project and import the velocity framework. You will also need the Xerces library. Download it from xerces.apache.org and copy it into the lib folder of your new project, alongside the third party jars. When this is done, your project should contain the Velocity tools as well as the Velocity documentation (written using DocBook) underneath the docs/src/docbook/dbf folder. You will be creating your own sample documentation here. Begin by creating the simple DocBook XML document from the previous page in this folder as simple.xml.

To transform simple.xml into PDF and HTML you will need to edit the Velocity build script to pick up the new file. Long term you can tailor the project structure and ANT scripts to suit your project and integrate more tightly with your build processes, but for this demonstration open the ANT file build.xml and change the entry from <property name="docbook.file" value="DBFUserGuide"/> to <property name="docbook.file" value="simple"/>. This ensures that it points to your new file.

To generate the PDF and HTML in Eclipse simply right-click on the build.xml file and select Run As –> ANT Build. When the build is complete, navigate to the doc/target/dbf/singlehtml folder to see the HTML output and doc/target/dbf/pdf to see the PDF output.

The resulting documentation looks like Figure 1 (HTML) and Figure 2 (PDF).

Click to enlarge

Figure 1. Simple.xml Rendered to HTML

Click to enlarge

Figure 2. Simple.xml Rendered to PDF

The DocBook Vocabulary
The DocBook vocabulary contains a rich set of tags for different content, including basic lists, tables, links, and images, as well as more specific programming constructs. To create an itemized list use a <orderedlist> or <itemizedlist> tag with <listitem> child elements as follows:

<chapter id="list">
  <para>You can use:</para>
    <itemizedlist mark="opencircle">
        <para> itemizedlist; or </para>

        <para> orderedlist </para>


You can incorporate images and links using the <mediaobject> and <ulink> tags. For example, you'd use this code to include the image logo.png:

    <imagedata fileref="images/logo.png"/>

And you'd use this code to add a link to the DocBook web site:

<ulink url="http://www.docbook.org">docBook</ulink>

To include source code use the <programlisting> element:

  protected void test() {
    System.out.println("This is a sample extract");

Experiment with a few tags by adding them to the simple.xml file and running the ANT build to see how they render.

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date