DocBook: Write Once, Read Anywhere Documentation : Page 2

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).

Figure 1. Simple.xml Rendered to HTML

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">
  <title>Lists</title>
  <para>You can use:</para>
    <itemizedlist mark="opencircle">
      <listitem>
        <para> itemizedlist; or </para>
      </listitem>

      <listitem>
        <para> orderedlist </para>
      </listitem>

    </itemizedlist>
</chapter>

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:

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

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:

<programlisting><![CDATA[
  protected void test() {
    System.out.println("This is a sample extract");
  }
...]]>
</programlisting>

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

Previous Page

Next Page