Build DocBook XML in Eclipse

Document options Document options requiring JavaScript are not displayed My developerWorks needs you! Connect to your technical community Rate this page Help us improve this content

Level: Intermediate

Nathan A. Good (mail@nathanagood.com), Author and Software Engineer, Alliance of Computer Professionals

12 Jun 2007

DocBook XML is a library of standard XML tags you can use to write stylesheets for generating almost any output. However, because DocBook has been around for quite some time, many stylesheets already exist for generating different types of documentation. Learn how to use DocBook XML and the Eclipse IDE together to create reusable technical documentation that you can easily distribute in most formats.

Getting started

This article demonstrates how to use DocBook XML and the Eclipse integrated development environment (IDE) together to create reusable technical documentation that is easily distributed in many formats. DocBook XML is a library of standard XML tags with which you can write stylesheets for generating almost any output. However, because DocBook has been around for nearly 10 years, many stylesheets have already been written that generate many types of documentation, including HTML, text, PDF, and man pages.

After completing this article, you should be able to use DocBook XML to create documentation that can be generated into HTML and used in an Eclipse help plug-in and a PDF from a single XML source file. You should have some working knowledge of XML. You should also be comfortable using Eclipse and Apache Ant, including running Ant build files from the Eclipse IDE. You need Eclipse V3.2 or later, the DocBook XML V4.x Document Type Definitions (DTDs), DocBook XSL stylesheets, Apache Xalan-Java™, and (optionally) Apache FOP (see Resources for downloads).

DocBook XML overview

DocBook XML is an XML library of tags tailored for writing documentation. Many of the tags available in DocBook make it a natural choice for building technical documentation. Because DocBook is XML, it can be transformed to many different output formats using stylesheets, which makes DocBook XML a natural choice for writing technical documents once and generating them in various formats.

Note: This code in this article was developed using DocBook XML V4.5; V5.0 was in release candidate status at the time of writing.

Back to top

High-level elements

Table 1 shows the elements commonly used as the high-level elements of a DocBook XML file.

Back to top

Elements for content

Inside the higher-level elements, you might want to add actual contents — paragraphs, tables, lists, code samples, etc. Table 2 lists some of the common elements used for adding content to your book, chapter, or article.

A simple sample document containing a book with at least one of each of the elements listed in Table 2 is shown below.

                
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
    <title>My Example Book</title>
    <titleabbrev>Example</titleabbrev>
    <bookinfo>
        <author>
            <personname>
                <firstname>Nathan</firstname>
                <surname>Good</surname>
            </personname>
        </author>
    </bookinfo>
    <preface id="preface1">
        <title>Required Preface</title>
        <para>You will like my book (I think).</para>
    </preface>
    <chapter id="chapter1">
        <title>Your First Chapter</title>
        <para>You must include at least one chapter in your book.</para>
        <para>Here is another paragraph.</para>
        <important>
            <para>This is some really important text.</para>
        </important>
        <tip>
            <para>Look both ways before crossing the street!</para>
        </tip>
        <caution>
            <para>
                Liberal use of <code>new</code> in loops can cause performance issues!
            </para>
        </caution>
        <example>
            <title>Example 1</title>
            <programlisting>
String something = "Something";
            </programlisting>        
        </example>
    </chapter>
</book>

When the file is generated into HTML and rendered in a browser, it will look much like that shown in Figure 1.

An exhaustive mention of each available DocBook XML tag is best left to reference manuals; a link to an HTML version of one of these is available in Resources. Books about DocBook XML are also available. The tags listed in Table 2 will give you a good start, but many more are available for covering screenshots, command prompts, user input, trademarks, and quotations, to name a few.

Back to top

Setting up your environment

You must use a tool to perform Extensible Stylesheet Transformation Language (XSLT) transformation, along with XSL stylesheets to transform the DocBook XML into a format that you find more useful, such as HTML or PDF. If you were building your own proprietary XML, you would also have to write your own stylesheets. However, using an established format like DocBook XML allows you to use stylesheets other people have already written. To use the prewritten stylesheets, download them (see Resources). At the time of this writing, one set of stylesheets for DocBook XML V4.5 is DocBook XSL V1.72.0.

Get the stylesheets

The archive file you download that contains the DocBook XSL (for example, docbook-xsl-1.72.0.zip) includes the stylesheets in different directories organized by the type of output they produce. An html directory includes stylesheets for outputting HTML; a fo directory includes stylesheets for generating files in Formatting Objects (FO) format, etc.

Download the archive file and save it to a location that will be easy to remember later. There is no need to extract the files from the archive file — you can import them directly into Eclipse.

Use Xalan

In this article, I use Xalan as the XSLT processor. There's one problem with using Xalan with the version of Ant that ships with Eclipse: The version is older and has problems when trying to process the XSLs.

Xalan is an Apache project available as two subprojects: Xalan C++ and Xalan-Java. Download Xalan-Java if you do not have it on your machine. When you're finished downloading the file, save it in a location that's easy to remember. Like the archive file containing the stylesheets, do not extract the contents of the file yet.

Back to top

Create the Eclipse project

Up to this point, you've seen a few sample files and should have downloaded the latest versions of the DocBook XSL stylesheets, as well as the latest version of Xalan, if you didn't already have them. You should also have downloaded the DocBook XML schema files. The archive files (for example, docbook-xsl-1.72.0.zip, xalan-j_2_7_0_bin-2jars.zip, and docbook-xml-4.5.zip) should be saved in a location that's easy to find.

With all the archive files downloaded and saved, you're ready to start Eclipse to create your new project and edit the DocBook XML and Ant script that will transform your DocBook XML into different formats.

After Eclipse starts, create a new project by choosing File > New > Project. Under General, click the generic Project, then click Next. After typing the name of your project, click Finish to create the new project in your workspace.

Back to top

Import files from the archives

Now that you've created a new project in Eclipse, import the files that you'll be using to build the DocBook XML.

Import the DTD files

First, import the DocBook XML DTD files. Choose File > Import, as shown below, then, from the General category, choose Archive File. When the Import Wizard appears, click Browse to open a file browser you can use to locate the DocBook XML DTD archive file, such as docbook-xml-4.5.zip.

In the Into folder box, type /docbook-xml after your project name. Make sure that the / folder is selected, as shown below. Click Select All if it's not selected or if it's grayed out, then click Finish when you're done. The files within the archive are inserted into your project.

Import the XSL stylesheets

When you're finished importing the DocBook XML DTD files, follow the same process to import the contents of the docbook-xsl-1.72.0.zip file. This time, however, you don't need to specify a folder name after your project name in the Into folder box because the contents of the archive will already be put into a folder called docbook-xsl-1.72.0 inside your project.

Now that you've imported the XSL stylesheets, import the Java Archive (JAR) files you'll need from the archive you downloaded from the Xalan Web site. Follow the same process as importing the other archive files, but this time, make sure that you clear the docs, licenses, and samples directories so they aren't imported into the project. After you've cleared those directories, modify the project name in the Into folder box by adding /lib.

After importing all the files you'll need, create an additional folder within your project and name it src. This will be the base folder for all your DocBook XML files.

So far, you should have a project in Eclipse that has the following folders:

• docbook-xml, which contains the DocBook XML DTDs
• docbook-xsl-1.72.0, which contains the DocBook XSL stylesheets
• lib, which contains the Xalan JAR files
• src, which is empty right now

If you have all these folders in your project, you're ready to add an Ant build.xml file to run the transformation process.

Write an Ant script

Ant is a Java-based build tool that reads an XML script and can perform many tasks defined in the script. If you're unfamiliar with Ant, see Resources. In this article, you will use Eclipse to initiate Ant, so you don't have to become familiar with how to run it from the command line. Also, you needn't concern yourself with downloading and installing Ant because the Eclipse IDE V3.2.x ships with Ant. It's an older version than that currently available — V1.65 as opposed to V1.7 — but for purposes of this article, that won't matter.

However, the version of Xalan that comes with V1.6.5 of Ant didn't seem to work well when I tried it with the latest DocBook XSLs. But if you're downloading and using the latest version of Xalan (and the version of Xerces included), it should work just fine.

Back to top

Use Xalan with Ant

There are several ways to tell Ant to use a particular version of Xalan — or any other XSLT processor — instead of the default version that comes with Ant. One of them is to modify the classpath for Ant. When you're using Ant within the Eclipse IDE, this is fairly simple to do. Choose Window > Preferences to change the settings under Ant/CLASSPATH. You can remove any references to Xalan or Xerces on the CLASSPATH tab and replace them with the versions you have downloaded.

Irreversible changes Don't worry about making irreversible changes. The Restore Default button can be a real lifesaver if you decide you want to return the Ant settings to the state in which they were when you first downloaded Eclipse.

This approach is fine if you're the only one who'll be doing the transformation because only you will have to change the Ant settings to get the transformation to work correctly. However, if you're working with a team of people, the better approach is to include the Xalan and Xerces JAR files with the project in a directory (for example, lib) and modify your build.xml file to use the libraries for the xslt task. Using this approach, you can simply check files out of source control or distribute the project and run it without changing the Eclipse IDE settings.

An example of supplying the JAR files to the xslt task is provided in the Ant build script below.

                
<?xml version="1.0"?>
<!--
  - Author:  Nathan A. Good <mail@nathanagood.com>
  -->
<project name="docbook-src" default="usage">
    
    <description>
            This Ant build.xml file is used to transform DocBook XML to various
    </description>

    <!--
      - Configure basic properties that will be used in the file.
      -->
    <property name="docbook.xsl.dir" value="docbook-xsl-1.72.0" />
    <property name="doc.dir" value="doc" />
    <property name="html.stylesheet" value="${docbook.xsl.dir}/html/docbook.xsl" />
    <property name="xalan.lib.dir" value="lib/xalan-j_2_7_0" />

    <!--
      - Sets up the classpath for the Xalan and Xerces implementations
      - that are to be used in this script, since the versions that ship
      - with Ant may be out of date.
      -->
    <path id="xalan.classpath">
        <fileset dir="${xalan.lib.dir}" id="xalan.fileset">
            <include name="xalan.jar" />
            <include name="xercesImpl.jar" />
        </fileset>
    </path>

    <!--
      - target:  usage
      -->
    <target name="usage" description="Prints the Ant build.xml usage">
        <echo message="Use -projecthelp to get a list of the available targets." />
    </target>

    <!--
      - target:  clean
      -->
    <target name="clean" description="Cleans up generated files.">
        <delete dir="${doc.dir}" />
    </target>

    <!--
      - target:  depends
      -->
    <target name="depends">
        <mkdir dir="${doc.dir}" />
    </target>

    <!--
      - target:  build-html
      - description:  Iterates through a directory and transforms
      -     .xml files into .html files using the DocBook XSL.
      -->
    <target name="build-html" depends="depends" 
        description="Generates HTML files from DocBook XML">
        <xslt style="${html.stylesheet}" extension=".html" 
            basedir="src" destdir="${doc.dir}">
            <classpath refid="xalan.classpath" />
        </xslt>
    </target>
    
</project>

The <property> tag shown in bold allows you to specify the location of the Xalan JAR files. The <path> element defines a path you can reuse throughout the Ant script. You can also specify the path to the Xalan XSLT processor to the xslt target by using the classpath attribute or by specifying the path inside the classpath element instead of using the refid attribute to refer to the path.

The xslt target is designed with the basedir, extension, and destdir attributes to go through a folder recursively and generate HTML files for each of the XML files found in the directory. The output will be stored in a folder you'll use later as the HTML source for the help files that go with the Eclipse plug-in demonstrated later.

Back to top

Create a build.xml file

Create a build.xml file by choosing File > New >File. Type build.xml as the file name, then select the project as the location for the file. Click Finish to create the Ant file.

You can put the contents shown in Listing 2 inside your new build file. If any of the directory names you've chosen differ from those we used here, you may need to tweak some of the values in the property elements to get everything to work.

You may execute your build.xml file directly from Eclipse, as Eclipse has built-in hooks for running Ant build scripts. Using Ant has a couple of other advantages: First, it's cross-platform, which means you can execute this same build script on any operating system that runs Java code. Another advantage is that you can run this build script independent of the IDE. Therefore, you can incorporate it easily into an automated build process, or you can execute it from the command line. Initially, I was looking into setting Eclipse properties to run an XSLT processor as an external tool (see Run > External Tools), but I abandoned that idea to gain these advantages.

Back to top

Run the build-html target

After you've written the build.xml file, you can run the build-html target. You don't have any DocBook XML files, so the target won't do anything useful. However, you should not get any errors from running the script.

One of the easiest ways to run an Ant target is to do so from the Outline view while the build file is open in the editor. Within the Outline view, right-click the name of the build-html target, then choose Run As > Ant Build. Messages from the Ant build script, if any, will appear in the Console view.

Back to top

Write the DocBook XML file

In your Eclipse project, you should have the DocBook XML DTD files, the DocBook XSL files, Xalan libraries, and now the build.xml file. At this point, you have everything you need to start building the DocBook XML files.

Create the first DocBook XML file

To create your first DocBook XML file in Eclipse:

1. Choose File > New > Other.
2. From the XML category, select XML, then click Next.
3. In the Create XML File window, choose Create XML file from a DTD file, then click Next.
4. Type chapter1.xml in the File name box, then make sure that the src folder within your project is selected, then click Next.
5. In Select DTD File, navigate to the docbookx.dtd file in the docbook-xml folder of your project, then click Next.
6. When the Select Root Element window appears, choose chapter from Root element, then clear the Create first choice of required choice checkbox.
7. Type -//OASIS//DTD DocBook XML V4.5//EN, then click Finish.

Validating the XML The DocBook XML files can be validated right inside Eclipse. Simply right-click the file in the Project Explorer, then click Validate. If validation errors occur, they appear in the Problems view in the IDE beneath Errors. If you double-click the error message in this view, the Eclipse IDE shows you the location in the file where the error occurred.

Work with chapter1.xml in the XML editor

Eclipse opens chapter1.xml in the XML editor. The XML editor in Eclipse has two views of the file: Design and Source. The Design view of the XML file displays the elements of the file in a grid, with the element names in the left column and the content of the elements in the right column. You can add new elements to the file by right-clicking the file and choosing Add Child, Add After, or Add Before.

If you're using DTD, the menu options in the context menu limit you to adding only elements that are valid. This feature allows you to make sure that you don't have a bunch of validation errors in your XML file when you go to perform the transformation later.

Back to top

Building modular documentation

When you're creating many documents, there are bound to be similarities between the documents, particularly if they're all for the same audience, such as a large corporation or a staff of people. For instance, if you've read many technical books, you've probably noticed that nearly every one has a "Conventions Used in This Book" section or chapter that demonstrates how hints, tips, inline code, and code listings are formatted in the book.

Partition your DocBook XML files

Using DocBook XML gives you the ability to partition your documentation into many files that can be compiled into one unit and potentially reused. For example, you can put each chapter of your book into a separate XML document. You can then use these in other books or simply partition them into separate files to make them easier to maintain. You can then include the chapters in a book and use stylesheets to process them.

Listing 3 provides an example of building a DocBook XML document that includes other DocBook XML files dynamically. When this file is processed during transformation, it's as if the file — here, chapter1.xml — is where &chap1; is located.

                
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
    "../docbook-xml/docbookx.dtd" [
    <!ENTITY chap1 SYSTEM "chapter1.xml">
    ]>
<book>
    &chap1;
</book>

There are several things to watch out for when taking this approach. First, the you must modify the chapter1.xml file to remove the XML preprocessing directive and the DOCTYPE element. Because the contents of chapter1.xml will be put into place where the &chap1 entity is located, book.xml will contain an XML processing directive and DOCTYPE element in the middle of the file, making it invalid.

Second, if you no longer want to process the individual chapter files into individual HTML files, you should update the Ant build script to skip processing the chapter files. Fortunately, with the xslt task in Ant, this change is fairly trivial. The xslt task can contain the same elements as a fileset element in Ant, which means that you can build lists of files to include and exclude rather easily. Listing 4 shows how to include additions necessary to skip certain files in the processing using the <exclude> element.

                
<target name="build-html" depends="depends" 
    description="Generates HTML files from DocBook XML">
    <xslt style="${html.stylesheet}" extension=".html" 
        basedir="${source.dir}" destdir="${doc.dir}">
        <classpath refid="xalan.classpath" />
        <include name="**/*.xml" />
        <exclude name="chapter1.xml" />

    </xslt>
</target>

If you would still like to build all the documents, you can remove the exclude element shown above.

You're not limited to splitting up chapters and books. You can physically partition DocBook XML files in any way that makes sense, such as putting sections in files by themselves. You can even include books in a set element, which is the highest-level DocBook element.

Build a help plug-in

One of the powerful features of the Eclipse framework is its extensibility. I've often wondered — when I see enterprises with particular "corporate-approved" ways of connecting to databases, handling transactions, or handling errors — why enterprises make their developers look outside the environment they're working in to hunt down documentation. Why not build the same HTML documentation available on corporate intranets and distribute it to developers in the form of help that can be accessed easily from the IDE, indexed, and searched?

The Eclipse IDE comes with templates you can use to quickly create plug-in projects that include help in the form of HTML files. The next few sections demonstrate how to build this plug-in project. After you build the plug-in project, you can include the HTML files you build in your DocBook XML project.

Back to top

Create the help plug-in

To create the help plug-in:

1. Choose File > New > Project to launch the New Project Wizard.
2. From the list of available wizards, choose Plug-in Project from the Plug-in Development category, then click Next.
3. In the Project name box, type MyHelpPlugin, then click Next.
4. Click Next on the window shown in Figure 4.
   
   Figure 4. New Plug-in project
   
   
   
5. From the Available Templates list, choose Plug-in with sample help content, then click Next.
6. In the next window, click Finish. You may be prompted to switch to the Plug-in Development perspective. If you are, I recommend clicking Yes because the perspective automatically includes views that will be helpful to you in building the help.

The new project contains a folder called html and within that folder, some sample HTML files. You will replace these files with the HTML files generated in the DocBook project.

Check your progress

Without making any changes yet, choose Run > Run As > Eclipse Application to run the plug-in with an instance of Eclipse to see what the help looks like so far. A new instance of Eclipse starts, using your plug-in. After Eclipse starts, choose Help > Help Contents to see your plug-in in action. If you've made no changes, you'll see Test TOC listed among the contents, as shown in Figure 5.

Incorporate the HTML from your DocBook XML project

Now that you've seen the default contents of your new help plug-in, it's time to incorporate the HTML from the DocBook XML project you built earlier. Doing so requires copying the HTML output from the new help plug-in project, but you don't want to do that manually each time. If left a manual process, it would be easy to make a mistake or forget to do it in the course of building your plug-in.

Add an Ant file

The first step in copying the HTML files automatically is to build a simple Ant file. This Ant file only copies the HTML files from the DocBook XML project to the html folder in your plug-in project. The Ant file will then be executed whenever Eclipse builds your projects.

The contents of the Ant file are shown below. The file has only one target — prepare — which is also the default target of the build file. Because this build file is really intended to be called only by Eclipse, I left the default target as prepare.

                
<?xml version="1.0"?>
<project name="MyHelpPlugin" default="prepare">
    <description>
        Prepares the Help plug-in project by copying the HTML help files
        from the DocBook XML project into this one.
    </description>
    
    <property name="docbook.project.dir" value="../myProject" />
    <property name="html.dir" value="html" />
    <property name="html.src.dir" value="${docbook.project.dir}/doc" />
    
    <fileset id="html-files" dir="${html.src.dir}">
        <include name="**/*.html" />
        <include name="**/*.css" />
    </fileset>
    
    <target name="prepare">
        <copy todir="${html.dir}">
            <fileset refid="html-files" />
        </copy>
    </target>
</project>

Define a builder

In Eclipse, you can define programs that run when Eclipse builds your project. These programs are called builders. You can modify the builders by clicking the name of a project, then choosing Project > Properties. Beneath Builders, you will see builders already set up for the project: Java Builder, Plug-in Manifest Builder, and Extension Point Schema Builder. To have Eclipse run the Ant script to copy the HTML files into your plug-in project:

1. Click New from the Builders property page.
2. Choose Ant Build from the list, then click OK.
3. Type a name for the new builder, such as Ant Builder.
4. Under Buildfile, click Browser Workspace to locate your Ant file inside the workspace.
5. Click the Targets tab, and make sure that the After a "Clean" and Manual Build targets say <default target selected>.
6. Click OK to save the builder.
7. On the Builders page, choose the new Ant builder you just created, then click Up until your builder is the first one in the list. You must do this because you want to copy the files to your plug-in project before you do any more work.

After setting up the new builder, you can choose Project > Clean or Project > Build to clean or build the project. The Ant builder runs and automatically pulls the HTML files from the DocBook XML project.

Project build order You may have to modify the order in which projects are built in your workspace to ensure that the project containing the DocBook documentation is built before your help plug-in. To change your project build order, choose Window > Preferences. Under General/Workspace/Build Order, you will find a list of your projects. You can clear the Use default build order checkbox, then reorder the projects using the Up and Down buttons.

Adding builders works for the DocBook XML project, too. You can add an Ant builder to the DocBook XML project, setting any one of the targets as the target to execute when cleaning or building the project. (Remember that with those targets, the usage target was the default.)

Back to top

The help TOC files

The table of contents (TOC) for the HTML help files resides in two XML files included in the plug-in project. The files are shown below.

                
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Test TOC">
    <link toc="toc.xml" />
</toc>

The testTOC.xml file shown in Listing 6 contains the name of the heading that will appear in the Contents pane of the help window. It does nothing more than link to the toc.xml file.

                
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Sample Table of Contents">
    <topic label="Main Topic" href="html/book.html"> 
    </topic>
</toc>

The toc.xml file contains the main topics that appear under the primary topic. These main topics are linked to HTML pages with the href attribute, shown in bold in Listing 7.

You can build the help as one monolithic file, like a book, and have only one main topic that points to that file. However, consider breaking up the documentation into separate chapters that can index in the toc.xml file but also build into a single book if you'd like to. See "Building modular documentation" for tips on how to break up the documentation into different physical files you can organize.

Back to top

Customize the DocBook output

So far, you have DocBook XML that is transformed into regular HTML that is used as help inside an Eclipse plug-in. But what do you do if you want to spruce up the appearance of the HTML that is output by the transformation?

Fortunately, you don't have to write your own XSL stylesheets just to add a bit of personalization or custom formatting to the HTML. Instead, you can pass variables to the XSLT transform step to assign a Cascading Style Sheet (CSS) that will allow you to "pretty format" your HTML.

Back to top

Assign a CSS stylesheet

The XSL stylesheets for transforming DocBook XML to HTML inspect a variable named html.stylesheet. If the variable contains a value, that value is used in a link element in the HTML to link to the stylesheet that you specify.

Listing 8 shows a simple CSS with a couple of classes: important and caution. The CSS modifies the color of the text for these classes. You'll see when the page is displayed that these classes correspond to content inside the <important> and <caution> tags, respectively.

                
body { font-family : arial,sans-serif; font-size : small; }
.important { color : blue; }
.caution { color : red; }

Back to top

Modify the Ant build file

Save the CSS shown in Listing 8 into a file named style.css in the lib directory of your DocBook XML project. After saving the file, you must modify the Ant build file to pass the name of the CSS file in the xslt target, then copy the CSS file from the lib folder into the same folder as the rest of the HTML output. Listing 9 shows these changes in bold.

                
<target name="build-html" depends="depends" 
    description="Generates HTML files from DocBook XML">
    <xslt style="${html.stylesheet}" extension=".html" 
        basedir="${source.dir}" destdir="${doc.dir}">
        <classpath refid="xalan.classpath" />
        <include name="**/*.xml" />
        <exclude name="chapter1.xml" />
        <param name="html.stylesheet" expression="style.css" />
    </xslt>
    <!-- Copy the stylesheet to the same directory as the HTML files -->
    <copy todir="${doc.dir}">
        <fileset dir="lib">
            <include name="style.css" />
        </fileset>
    </copy>
</target>

After you've made those changes, you can rerun the Ant build script in your DocBook XML project. This time, when you look at the output HTML files, you will see the font changed and the new font colors for the "Important" and "Caution" parts.

Back to top

Create a PDF

Up to this point, you've been using the various tools to generate HTML from DocBook XML that can be distributed to an intranet site and included in Eclipse help plug-ins. However, I mentioned earlier that with the same DocBook XML source files, you can also generate PDFs. Generating PDFs from DocBook XML requires one additional tool: the FOP libraries from the Apache XML Graphics Project (see Resources).

The FOP libraries include an Ant task you can put directly into your existing Ant build file in your DocBook XML project. The Ant task, fop, transforms FO files, which are built with the FO stylesheets that come with DocBook XSL.

Back to top

Use the FOP libraries to generate PDFs

To use the FOP libraries, download the ZIP file containing the binary distribution (for example, fop-0.93-bin-jdk1.4.zip) from the Web site. Although the name of the ZIP file seems to indicate that it was built especially for Java 2 Platform, Standard Edition (J2SE), Development Kit (JDK) V1.4, it will work fine with Java V5. Like the other archive files you downloaded, you don't need to extract this file yet.

In Eclipse, choose File > Import, then go through the same process you used in "Import files from the archives." However, this time, select only the build and lib folders for import.

After you've finished importing the files, modify the Ant build script to set up the fop target and call it in a new build-pdf target, as shown below.

                
<!--
    - target:  build-pdf
    - description:  Iterates through a directory and transforms
    -     .xml files into .fo files which can then be turned into DocBook XML
    -     files.
    -->>
<target name="build-pdf" depends="depends" 
    description="Generates PDF files from DocBook XML">>
    <xslt style="${fo.stylesheet}" extension=".fo" 
        basedir="${source.dir}" destdir="${fo.dir}">>
        <classpath refid="xalan.classpath" />>
        <include name="book.xml" />>
    </xslt>>

    <property name="fop.home" value="lib/fop-0.93" />>

    <taskdef name="fop" classname="org.apache.fop.tools.anttasks.Fop">>
        <classpath>>
            <fileset dir="${fop.home}/lib">>
                <include name="*.jar" />>
            </fileset>>
            <fileset dir="${fop.home}/build">>
                <include name="fop.jar" />>
                <include name="fop-hyph.jar" />>
            </fileset>>
        </classpath>>
    </taskdef>>

    <fop format="application/pdf" fofile="${fo.dir}/book.fo" 
        outfile="${dist.dir}/book.pdf" />>
</target>>

After you've set up this target, run the build-pdf target from the Eclipse IDE. This time, in the dist directory, a file named book.pdf appears.

Summary

DocBook XML is a powerful format for building technical documentation that can be generated into a variety of different outputs, such as HTML and PDF. The format allows you to focus on the content of documents, leaving the styling separate. Because of its maturity, many tools are available for you to edit and build documentation in DocBook XML.

The Eclipse IDE includes editors for writing and validating XML documents. Eclipse also has integration with Ant, allowing you to create powerful build files that can be executed as regular builders in Eclipse. In addition, the templates included with Eclipse allow you to build plug-in projects quickly, including those that contain HTML files you can use for help in Eclipse.

All these tools work together to allow you to write technical documentation in one place and distribute it to a wide variety of audiences in different formats.

Resources

• Read more about DocBook XML at the DocBook: The Definitive Guide.
  
  
• Read more about Ant tasks in the Apache Ant manual.
  
  
• Check out the "Recommended Eclipse reading list."
  
  
• Browse all the Eclipse content on developerWorks.
  
  
• Users new to Eclipse should check out Eclipse project resources' Start Here.
  
  
• Expand your Eclipse skills by checking out IBM developerWorks' Eclipse project resources.
  
  
• To listen to interesting interviews and discussions for software developers, check out developerWorks podcasts.
  
  
• For an introduction to the Eclipse platform, see "Getting started with the Eclipse Platform."
  
  
• Stay current with developerWorks' Technical events and webcasts.
  
  
• Watch and learn about IBM and open source technologies and product functions with the no-cost developerWorks On demand demos.
  
  
• Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
  
  
• Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
  
  

• Download Eclipse from Eclipse.org.
  
  
• Download Apache FOP for converting FO files to various formats, including PDF, from the Apache FOP site.
  
  
• Download the DocBook XML DTD files.
  
  
• Get DocBook XSL stylesheets to perform transformations without writing your own stylesheets.
  
  
• Download and read about the latest version of Xalan-Java.
  
  
• Check out the latest Eclipse technology downloads at IBM alphaWorks.
  
  
• Download IBM product evaluation versions, and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  
• Innovate your next open source development project with IBM trial software, available for download or on DVD.

• The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
  
  
• The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
  
  
• Participate in developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

		Nathan Good lives in the Twin Cities area of Minnesota. Professionally, he does software development, software architecture, and systems administration. When he's not writing software, he enjoys building PCs and servers, reading about and working with new technologies, and trying to get his friends to make the move to open source software. He's written and co-written many books and articles, including Professional Red Hat Enterprise Linux 3, Regular Expression Recipes: A Problem-Solution Approach, and Foundations of PEAR: Rapid PHP Development.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top