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

By submitting your information, you agree that devx.com may send you DevX offers via email, phone and text message, as well as email offers about other products and services that DevX believes may be of interest to you. DevX will process your information in accordance with the Quinstreet Privacy Policy.


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.




Application Security Testing: An Integral Part of DevOps

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

Comment and Contribute






(Maximum characters: 1200). You have 1200 characters left.



We have made updates to our Privacy Policy to reflect the implementation of the General Data Protection Regulation.
Thanks for your registration, follow us on our social networks to keep up-to-date