Building DITA output with Ant

You can use the Ant build tool to automate builds that use the DITA processes including output for the sample documents provided with DITA.

DITA provides a set of XSLT scripts for producing help output in Eclipse, Java Help, HTML Help, for producing web HTML pages, or for producing PDF. To make it easier to invoke these scripts, the DITA distribution now provides an experimental Ant file that you can use to build the DITA documentation, demos, and samples.

Ant is a Java-based, Open Source tool provided by the Apache Foundation to declare a sequence of build actions. As such, Ant is well suited for document builds as well as development builds.

You don't have to set up a build environment, of course to run the DITA XSLT scripts. To execute the DITA scripts directly, see the .

Note: The following instructions and the associated build.xml and ditatargets.xml files are for the Java 1.4.1, Ant 1.6.1, FOP 0.20.5, and Saxon 6.5.3 releases. These instructions are likely to need some adjustment for other versions of these components and for specific environments.

Setting Up Ant

To create an Ant build environment for DITA, you can download and install some Java Open Source components.


For components other than the JDK, configuring the environment and using the component are often easier if you install the component in a directory without spaces in the pathname.
  1. Required: Download and install a JDK (Java Development Kit). Ant requires a full Java development environment (available at http://java.sun.com/j2se/index.jsp).
  2. Required: Download and install the DITA distribution. Unzip the DITA distribution in a directory.
  3. Required: Download and install Ant. You can get the Ant binary distribution from http://ant.apache.org/bindownload.cgi. Follow the instructions for installing Ant in the Ant manual at http://ant.apache.org/manual/index.html.
  4. Optional: Install Saxon Saxon is an advanced XSLT processor that integrates well with Ant. You can get Saxon from http://saxon.sourceforge.net/.
  5. Optional: Install FOP FOP is an XSL-FO processor, which you'll need if you want to generate PDF output. You can get a binary distribution of FOP from http://xml.apache.org/fop/download.html.
  6. Required: Set the environment variables. As of this writing, if you use all of the optional components and follow all of the recommendations in the component documentation, you would end up with the following environment variables:
    JAVA_HOME
    Set to the base directory for the JDK.
    ANT_HOME
    Set to the base directory for Ant.
    PATH
    Includes the add the bin and jre\bin directories under the JDK and the bin directory under Ant.
    CLASSPATH
    For Saxon, includes the saxon.jar library from the Saxon directory. For FOP, includes the fop.jar file from the build subdirectory and the avalon-framework-cvs-20020806.jar and batik.jar files from the lib subdirectory. In principle, you should not have to add JDK or Ant jar files to the CLASSPATH, but if you run into problems, you might want to try that.

Running Ant

After you set up your Ant environment, you can build the DITA output. Merely change to the DITA 1.3 distribution directory and execute Ant on the DITA build.xml file.

ant  all

The build creates an out directory and puts the build output in subdirectories that parallel the source directory.

To experiment with DITA, you can modify the DITA sample files and then rebuild that portion of the output. First, you remove that portion of the output by specifying a "clean" target. For instance, to rebuild just the FAQ demo, you can execute

ant clean_faq_demo
ant faq_demo

To find out the complete list of targets you can clean and build, look at the name attributes for the target elements within the build.xml file. Or, just enter

ant -projecthelp

You can reuse the targets provided by the ditatargets.xml file in builds for your own DITA content. Just copy the build.xml and ditatargets.xml file into a new directory and edit the build.xml to specify your DITA files.

Note: To troubleshoot problems in setting up Java, Ant, Saxon, or FOP, you will get better information from the communities for those components than for the DITA community. Of course, if you find issues with the DITA XSLT scripts (or have ideas for improving them), you should engage the DITA community.