About Ant scripts

An Ant script is an XML build file, containing a single project and a single or multiple targets, each of which consists of a group of tasks that you want Ant to perform. A task is an XML element that Ant can execute to produce a result. Ant comes with a large number of built-in tasks; you can also add tasks of your own.

DITA Open Toolkit makes use of two kinds of Ant scripts:

System scripts: System-level scripts handle DITA source file processing and transformation into published output. They are an integral part of DITA Open Toolkit and should never be modified by users. The files are located in the ditaot root directory.
User scripts: User-level processing scripts are created and modified by users. They provide to the system scripts (which do the actual processing) information about the names and locations of the DITA source files, where to put the processed target files, and values for specific processing parameters. DITA Open Toolkit contains a number of sample user-level processing files that you can view to gain understanding of the build process, and modify for your own use.

Main system scripts in DITA Open Toolkit

Script	Description
build.xml	Initializes the Toolkit and builds various DITA targets.
build_demo.xml	Builds the Toolkit demos.
buildPackage.xml	Build source and binary packages for DITA Open Toolkit.
catalog-dita_template.xml and catalog-dita.xml	Contains information that directs the Toolkit to the names and locations of the DTD files. The template file creates the non-template file dynamically during every build.
integrator.xml	Adds plug-ins to the build.

Creating user scripts in DITA Open Toolkit

Sample Ant scripts for all target publishing environment supported by DITA Open Toolkit are located in ditaot/doc/ot-userguide/MY_DITA_SOURCE/samples/garage/ant_scripts of the Toolkit source distribution. Most of these scripts process the garage sample source files with the topics displayed in a hierarchy. One processes the garage sample to XHTML with the topics displayed as a sequence. One filters out some of the topics using a ditaval file before publishing as XHTML in a hierarchical format.

The following section contains one of these sample scripts for XHTML targets. You would run this build script in Windows by opening the Command Prompt, navigating to the ant_scripts directory, and entering the command:

ant -f garage_hierarchy_xhtml.xml

For more information about processing (building) to XHTML targets, see Processing to XHTML targets..

Sample user script

Here is an annotated script for publishing the garage sample to XHTML in a hierarchical format. The lines in bold are the actual script statements; the other lines are annotations.

			 
<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright 2006 VR Communications, Inc. --> 
<!-- All rights reserved. -->
<!-- SAMPLE: GARAGE -->
<!-- DITAMAP: HIERARCHY -->
<!-- TARGET: XHTML -->

<!-- SAMPLE ANT BUILD SCRIPT TO CREATE XHTML OUTPUT -->   
<!-- from the provided sample ("garage"). -->

<!-- This is a "user script," meant to be -->
<!-- modified; however, be cautious in modifying the -->
<!-- environment initialization section. -->
 
<!-- -->
<!-- ENVIRONMENT INITIALIZATION SECTION -->
<!-- -->

<!-- Modify with caution. -->
<!-- garage_xhtml is an arbitrary name alluding to the --> 
<!-- source and target trees. -->

<!-- default="all" means "build all the targets in the -->	 
<!-- 'depends' target list" (below) -->
<!-- (NOT all targets supported by DITA Open Toolkit). -->
<!-- basedir is the base directory for the Toolkit --> 
<!-- executables (NOT the DITA source directory, --> 
<!-- which is defined with projdir, below). -->
<!-- OK to modify. -->
<project name="garage_xhtml" default="all" basedir="C:/ditaot">


<!-- Location of DITA source files (projdir) and target --> 
<!-- output files (outdir). -->
<!-- OK to modify. -->
<property name="projdir" value="C:/MY_DITA_SOURCE/samples/garage"/>
				<property name="outdir" value="C:/MY_DITA_OUTPUT/samples/garage"/>

<!-- Location of DITA Java classes. -->
<!-- DO NOT modify! -->
<path id="dost.class.path">
				<pathelement location="${basedir}/lib/dost.jar"/>
				</path>
  
<!-- Ant task to initialize the processing environment. -->
<!-- Defines a new Ant task called "integrate" that -->
<!-- executes the code defined in "classname". -->
<!-- DO NOT modify! -->
<taskdef name="integrate" classname="org.dita.dost.platform.IntegratorTask">
				<classpath refid="dost.class.path"/>
				</taskdef>

<!-- dita2xhtml is a somewhat arbitrary name that -->
<!-- alludes to the source and target. -->
<!-- It must match the target name in the instance --> 
<!-- processing section below. -->
<!-- ${basedir} is the "basedir" defined above. -->
<!-- OK to modify. -->
<target name="all" depends="integrate, dita2xhtml"></target>
				<target name="integrate">
				<integrate ditadir="${basedir}"/>
				</target>

<!-- -->
<!-- INSTANCE PROCESSING SECTION -->
<!-- -->

<!-- Modify to process a particular source instance. -->
<!-- This sample builds only one target. --> 
<!-- You could add other target sections -->
<!-- to build to other targets --> 
<!-- (for example, PDF or HTML Help). --> 
<!-- If you do that, you must also add appropriate names --> 
<!-- (for example, dita2pdf or dita2htmlhelp) -->
<!-- to the "depends" list in the environment --> 
<!-- initialization section above. -->

<!-- This section builds to a single target (xhtml). -->
<!-- Target name must match the target name in the --> 
<!-- "depends" list in the environment initialization --> 
<!-- section. --> 
<target name="dita2xhtml">

<!-- The properties included below are input parameters. --> 
<!-- They are listed and defined in the DITA OT User Guide --> 
<!-- and Reference. -->
<ant antfile="${basedir}/conductor.xml" target="init">

<!-- projdir is defined in the environment initialization --> 
<!-- section above. -->
<property name="args.input" value="${projdir}/hierarchy.ditamap"/>

<!-- outdir is defined in the environment initialization --> 
<!-- section above. -->
<property name="output.dir" value="${outdir}/xhtml/hierarchy/unfiltered"/>

<!-- Name of the DITA temporary directory where files --> 
<!-- are stored during processing. -->
<property name="dita.temp.dir" value="${outdir}/temp"/>

<!-- transformation type (target output type). -->
<property name="transtype" value="xhtml"/>

<!-- The system default extname is .xml. --> 			
<!-- The following statement changes -->
<!-- the default to .dita. --> 
<!-- If you use other extensions --> 
<!-- (including .ditamap and .xml, -->
<!-- but also extensions like .jpg and .gif), --> 
<!-- you must specify the format attribute in --> 
<!-- your source files (for example, format="xml"). -->
<property name="dita.extname" value=".dita"/>
				</ant>
				</target>
				</project>