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


DocBook: Write Once, Read Anywhere Documentation : Page 4

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.

Incorporating Source Code Using <xi:include>
The <xi:include> element is useful for not only structuring your book but also for including source code. One of the common challenges of technical documentation—especially in agile environments—is keeping it in sync with the code. Sample source code in the documentation can get old fast. Source code that is incorporated manually using copy/paste is error prone, hard to test, and likely to get out of date quickly unless someone is willing to continually maintain the code samples. DocBook offers another way.

You can place code that you want included in your documentation into unit tests where it can be automatically tested, refactored as normal, and then mark it up for inclusion in DocBook. It's a simple process to create an extraction program that can crawl the codebase for markup and extract the annotated code into DocBook XML files. You then can include these files, like any other DocBook files using <xi:include>.

To see <xi:include> in action, create a sample Java class called SampleClass.java. Mark up the method test() using Java comments: //@extract-start <extractname> to mark the beginning of the extract and //@extract-end <extractname> to mark the end:

public class SampleClass {

    //@extract-start test
    protected void test() {
        System.out.println("This is a sample extract");
    //@extract-end test

The markup can then be processed by an extractor program, such as the one included in the code download for this article, so that the code inside test() can be extracted into the DocBook XML file test.xml. The name of the file is specified by the markup tags.

Test.xml contains a <programlisting> element with the annotated Java inside:

<?xml version="1.0" encoding="UTF-8"?>
    protected void test() {
        System.out.println("This is a sample extract");

The following code shows how you would include a <programlisting> element in a chapter:

<?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"> <chapter id="programlisting"> <title>including source code</title> <xi:include href="test.xml" xmlns:xi="http://www.w3.org/2003/XInclude" /> </chapter>

The advantage of this approach is that you can maintain the code in once place—the source files where it belongs—and unit test it as part of your build. Code included in your documentation is guaranteed to be correct if your unit tests pass. Extraction, along with the DocBook ANT build scripts, can be integrated using an ANT task to ensure that your documentation is always generated and always up to date with your code.

DocBook in Perspective
DocBook is an ideal strategy for technical, developer-centric documentation because it enables you to work closely with documentation in the same way you would your code. Popular open-source projects such as Spring and Hibernate use DocBook to generate their documentation. However, as with all technologies it has its downside: it requires a bit of up-front investment to learn how to use XML and the DocBook tags and how to integrate the rendering tools and style sheets into your build processes. You can use other standards such as DITA, also based on XML, as alternatives if they are easier for you though.

Of course, DocBook won't make poorly written documentation better. However, by integrating it into your development environment and leveraging the many DocBook resources available on the Web, you can evolve your documentation with your code—keeping it in sync, even in agile environments—and ensure that you get a professional-looking result at the end, and in the distribution format of your choosing.

Lara D'Abreo is an independent consultant with over 10 years experience in commercial product development in the US, Japan, and the UK. She's currently based out of Sydney, Australia and spends her time trying to make J2EE systems run faster.
Email AuthorEmail Author
Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date