Description: Learning how buildfiles tell Ant what and how to compile.

# Writing Ant Build Files DITA-OT

Learning how buildfiles tell Ant what and how to compile.

## Customize the Default Ant Script

The sample Ant build scripts provided by the DITA-OT may not be adequate to meet the needs of your documentation project. This topic describes how to customize the default scripts and write your own.

The DITA Open Toolkit contains sample build files for both the DITA-OT and sample documentation. Writers new to the toolkit use the `sample_all.xml` Ant build script to create all the sample documents that come with DITA-OT. The toolkit also contains build scripts for individual ouput types, such as `sample_pdf.xml`. You can modify just one or two Ant properties in these scripts for your own documentation.

Here is the Ant project definition from `template_pdf.xml`.

    <project name="@PROJECT.NAME@_pdf" default="@DELIVERABLE.NAME@2pdf" basedir=".">

      <property name="dita.dir" location="${basedir}${file.separator}..${file.separator}.."/>

      <target name="@DELIVERABLE.NAME@2pdf">
        <ant antfile="${dita.dir}${file.separator}build.xml">
          <property name="args.input" location="@DITA.INPUT@"/>
          <property name="output.dir" location="@OUTPUT.DIR@"/>
          <property name="transtype" value="pdf"/>
        </ant>
      </target>

    </project>

You simply change the values of the following properties to match the values used in your project:

- Project name: The root element in an Ant build file.
- Target name: Must be one of the supported DITA-OT transtypes.

However, the toolkit's scripts assume that your input files are located in same directory structure used by the DITA-OT samples.

## Write Your Own Ant Script

The default build script may not meet the needs of your project for a range of reasons:

- You want to add additional Ant properties not used in the sample template, such XSL and DTD properties to assist your debugging efforts.
- Your content files may not have the same directory structure as the samples.
- You want to place the output files in a different directory.

You need to cutomize or write your own build file for these use cases. For example, each target for this guide's build script uses a separate value for `dita.temp.dir` to assist debugging for a specific output types.

Here is an example Ant script that can be used to produce this document:

    <project name="antquickstartguide" default="dita2pdf" basedir=".">

      <property environment = "env"/>
      <property name="DITA_DIR" value="${env.DITA_DIR}"/>
      <property name="args.logdir" value="../logs"/>
      <property name="dita.input.valfile" value="../QSG.ditaval"/>

      <property name="dita.extname" value=".dita"/>
      <property name="args.fo.img.ext" value=".gif"/>

      <property name="output.dir" location="../output"/>
      <property name="outdir" location ="../output"/>
      <property name="clean.temp" value="no"/>

      <property name="args.indexshow" value="no"/>

      <target name="dita2pdf">
        <ant antfile="${DITA_DIR}/build.xml">
          <property name="transtype" value="pdf"/>
          <property name="args.input" value="../quickstartguide.ditamap"/>
          <property name="dita.temp.dir" value="${outdir}/temp_pdf"/>
          <property name="output.dir" value="${outdir}/pdf"/>
          <property name="outer.control" value="quiet"/>
          <property name="clean.temp" value="yes"/>
        </ant>
      </target>

    </project>

Ant argument properties for DITA-OT contains a list of the most basic Ant properties used by DITA-OT. Use these properties to customize your document's build script for your needs.

Parent topic: Running DITA Open Toolkit
Related concepts
What is Ant?
Related reference
Ant argument properties for DITA-OT