Author: Richard Johnson
Keywords: processing DITA file, building DITA file, garage sample, Ant script, Ant scripts, Ant scripts, system-level, user-level, build.xml, catalog-dita_template.xml, catalog-dita.xml, ditatargets.xml, integrator.xml, pretargets.xml, user-level Ant scripts

# 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.

## Sample Ant scripts

Sample Ant scripts are located at http://dita-ot.sourceforge.net/SourceForgeFiles/doc/user_guide.html. One of the sample scripts processes the garage sample source files with the topics displayed in a hierarchy. The other processes the garage sample with the topics displayed as a sequence. One of the targets in the hierarchy script does conditional processing.

The following section shows the script that publishes topics in a hierarchy. In Windows you would publish to XHTML by opening the Command Prompt, navigating to the ant_scripts directory, and entering the command:

    ant -f garage_hierarchy_all.xml xhtml

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

## Sample user script

Here is the annotated "hierarchy" script for the garage sample. This script is part of the DITA Open Toolkit User Guide package.

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- (c) Copyright 2006-2007 VR Communications, Inc. All rights reserved. -->
    <!-- Ant script for the garage sample processed as  a hierarchy of topics (garage_hierarchy_all.xml) -->
    <!-- Depending on the argument passed to the script at runtime,
    this script processed to one (example: dita2xhtml), multiple, or all output targets. -->
    <!-- This is a "user script," meant to be modified.
    However, be cautious in modifying the environment initialization section. -->
    <!-- -->
    <!-- ENVIRONMENT INITIALIZATION SECTION -->
    <!-- -->
    <!-- The project name is garage. The default output target is xhtml. -->
    <project name="garage" default="xhtml">
    	<!-- This message is echoed to the screen at the beginning of the build process -->
    	<!-- -->
    	<!-- To process using a different map, you need to change the following statement -->
    	<!-- -->
    	<echo> </echo>
    	<echo>Building garage sample as a hierarchy of topics.</echo>
    	<echo> </echo>
    	<!-- Allow the build process access to environment variables -->
    	<property environment="env"/>
    	<!-- Set toolkit directory from environment variable -->
    	<property name="toolkit_dir" value="${env.DITA_DIR}"/>
    	<!-- Note: basedir may be set in a higher-level script that invokes this one.
      Some plug-ins depend on its pointing to the Toolkit directory.
      In particular, the Idiom plug-in, which is required for PDF2 processing, requires it. -->
    	<property name="basedir" value="${env.DITA_DIR}"/>
    	<!-- Define the location of the project (source file) directory.
      In this case, the project directory is up two directory levels from the location of this file. -->
    	<property name="projdir" value="${ant.file}/../.."/>
    	<!-- Define the location of the output directory.
      In this case, it is a directory directly above the project (source file) directory. -->
    	<property name="outdir" value="${projdir}/../DITASAMPLE_GARAGE_OUTPUT"/>
    	<property name="PHPexe" value="${toolkit_dir}/php-5.1.4-Win32/php.exe"/>
    	<property name="args.logdir" value="${outdir}"/>
    	<!-- Set the name of the (master) ditamap -->
    	<!-- -->
    	<!-- To process using a different map, you need to change the following value -->
    	<!-- -->
    	<property name="MAP_file" value="hierarchy.ditamap"/>
    	<!-- Set the extension string for the dita files (files can also be .xml) -->
    	<property name="EXTNAME" value=".dita"/>
    	<!-- Create the default XHTML output and debug cross-reference -->
    	<target name="xhtml" depends="dita2xhtml">
      </target>
    	<target name="integrate">
    		<integrate ditadir="${toolkit_dir}"/>
    	</target>
    	<!-- -->
    	<!-- BEGIN INSTANCE PROCESSING SECTION -->
    	<!-- -->
    	<!-- Names of the output types this script is capable of producing -->
    	<!-- The target names are somewhat arbitrary. The following are traditional,
      and they allude to the source and target (for example, dita2xhtml). -->
      <!-- JavaHelp and PDF (using FOP) are not included in this list, because they don't work in Toolkit 1.3.1! -->
    	<target name="alltargets" depends="dita2xhtml, dita2filtered, dita2htmlhelp, dita2pdf2,
         dita2eclipsecontent, dita2eclipsehelp, dita2docbook, dita2javahelp, dita2troff, dita2wordrtf">
      </target>
    	<!-- Handy abbreviation (all) for alltargets -->
    	<target name="all" depends="alltargets"/>
    	<!-- Create all reports -->
    	<target name="allreports" depends="ditadebug, ditalinks, ditaauthors, ditaids, ditakeys"/>
    	<!-- Create the ditamap debug cross-reference -->
    	<target name="ditadebug">
    		<echo>Building debugging cross-reference file ditadebug.txt</echo>
    		<mkdir dir="${outdir}/debug_files"/>
    		<exec executable="${PHPexe}" dir="${projdir}" output="${outdir}/debug_files/ditadebug.txt">
    			<arg value="${projdir}/project/tools/ditadebug.php"/>
    			<arg value="${MAP_file}"/>
    		</exec>
    	</target>
    	<!-- Create plausible preview -->
    	<target name="preview">
    		<echo>Building XHTML plausible preview</echo>
    		<mkdir dir="${outdir}/debug_files"/>
    		<exec executable="${PHPexe}" dir="${projdir}" output="${outdir}/debug_files/ditapreview.txt">
    			<arg value="${projdir}/project/tools/ditapreview.php"/>
    			<arg value="${MAP_file}"/>
    			<arg value="L"/>
    		</exec>
    	</target>
    	<!-- Create the ditamap URL check -->
    	<target name="ditalinks">
    		<echo>Building URL check file ditalinks.txt</echo>
    		<mkdir dir="${outdir}/debug_files"/>
    		<exec executable="${PHPexe}" dir="${projdir}" output="${outdir}/debug_files/ditalinks.txt">
    			<arg value="${projdir}/project/tools/ditalinks.php"/>
    			<arg value="${MAP_file}"/>
    		</exec>
    	</target>
    	<!-- Create the ditamap author and copyright statistics -->
    	<target name="ditaauthors">
    		<echo>Building author/copyright file ditaauth.txt</echo>
    		<mkdir dir="${outdir}/debug_files"/>
    		<exec executable="${PHPexe}" dir="${projdir}" output="${outdir}/debug_files/ditaauthors.txt">
    			<arg value="${projdir}/project/tools/ditaauthors.php"/>
    			<arg value="${MAP_file}"/>
    		</exec>
    	</target>
    	<!-- Create the ditamap ID listing  -->
    	<target name="ditaids">
    		<echo>Building ID list file ditaids.txt</echo>
    		<mkdir dir="${outdir}/debug_files"/>
    		<exec executable="${PHPexe}" dir="${projdir}" output="${outdir}/debug_files/ditaids.txt">
    			<arg value="${projdir}/project/tools/ditaids.php"/>
    			<arg value="${MAP_file}"/>
    		</exec>
    	</target>
    	<!-- Create the ditamap keyword metadata statistics -->
    	<target name="ditakeys">
    		<echo>Building keyword metadata file ditakeys.txt</echo>
    		<mkdir dir="${outdir}/debug_files"/>
    		<exec executable="${PHPexe}" dir="${projdir}" output="${outdir}/debug_files/ditakeys.txt">
    			<arg value="${projdir}/project/tools/ditakeys.php"/>
    			<arg value="${MAP_file}"/>
    		</exec>
    	</target>
    	<!-- Create xhtml output (unfiltered) -->
    	<target name="dita2xhtml">
    		<ant antfile="${toolkit_dir}${file.separator}build.xml" target="init">
    		    <!-- -->
    			<!-- To process using a different map, you need to change the following value -->
    			<!-- -->
    			<property name="args.input" value="${projdir}/${MAP_file}"/>
    			<property name="output.dir" value="${outdir}/hierarchy/xhtml"/>
    			<!-- -->
    			<!-- To process using a different map, you need to change the following value -->
    			<!-- -->
    			<!-- The temp directory is shared by all targets -->
    			<property name="dita.temp.dir" value="${outdir}/hierarchy/temp"/>
    			<property name="transtype" value="xhtml"/>
    			<property name="args.draft" value="yes"/>
    			<property name="args.indexshow" value="yes"/>
    			<property name="dita.extname" value="${EXTNAME}"/>
    		</ant>
    	</target>
    	<!-- Create xhtml output (filtered) -->
    	<!-- The output file directory is structured so the filtered output files will not "step on" the existing files.
        They will be placed one level deeper than the existing hierarchy files. -->
    	<target name="dita2filtered">
    		<ant antfile="${toolkit_dir}${file.separator}build.xml" target="init">
    			<property name="args.input" value="${projdir}/${MAP_file}"/>
    			<property name="output.dir" value="${outdir}/hierarchy/filtered/xhtml"/>
    			<!-- The temp directory is shared by all targets -->
    			<property name="dita.temp.dir" value="${outdir}/hierarchy/filtered//temp"/>
    			<property name="transtype" value="xhtml"/>
    			<property name="args.draft" value="yes"/>
    			<property name="args.indexshow" value="yes"/>
    			<property name="dita.extname" value="${EXTNAME}"/>
    			<!-- Specify the ditaval file to be used for filtering -->
    			<!-- -->
    			<!-- To turn on filtering, you first need to change the following ditaval file to include the filter.
    			See the ditaval file for instructions.
    			Then run the Ant script with the dita2filtered target name.
    			Example (using the batch to call the Ant script): runbuild dita2filtered hierarchy -->
    			<!-- -->
    			<property name="dita.input.valfile" value="${projdir}/ditaval_files/garage_filtering.ditaval"/>
    		</ant>
    	</target>
    	<!-- Create htmlhelp output -->
    	<target name="dita2htmlhelp">
    		<ant antfile="${toolkit_dir}${file.separator}build.xml" target="init">
    			<property name="args.input" value="${projdir}/${MAP_file}"/>
    			<property name="output.dir" value="${outdir}/hierarchy/htmlhelp"/>
    			<!-- The temp directory is shared by all targets -->
    			<property name="dita.temp.dir" value="${outdir}/hierarchy/temp"/>
    			<property name="transtype" value="htmlhelp"/>
    			<property name="args.draft" value="yes"/>
    			<property name="args.indexshow" value="yes"/>
    			<property name="dita.extname" value="${EXTNAME}"/>
    		</ant>
    	</target>
    	<!-- Create idiom fo pdf2 output -->
    	<target name="dita2pdf2">
    		<ant antfile="${toolkit_dir}${file.separator}build.xml" target="init">
    			<property name="args.input" value="${projdir}/${MAP_file}"/>
    			<property name="output.dir" value="${outdir}/hierarchy/pdf2"/>
    			<!-- The temp directory is shared by all targets -->
    			<property name="dita.temp.dir" value="${outdir}/hierarchy/temp"/>
    			<property name="transtype" value="pdf2"/>
    			<property name="args.draft" value="yes"/>
    			<property name="args.indexshow" value="yes"/>
    			<property name="dita.extname" value="${EXTNAME}"/>
    		</ant>
    	</target>
    	<!-- Create eclipsecontent output -->
    	<target name="dita2eclipsecontent">
    		<ant antfile="${toolkit_dir}${file.separator}build.xml" target="init">
    			<property name="args.input" value="${projdir}/${MAP_file}"/>
    			<property name="output.dir" value="${outdir}/hierarchy/eclipsecontent"/>
    			<!-- The temp directory is shared by all targets -->
    			<property name="dita.temp.dir" value="${outdir}/hierarchy/temp"/>
    			<property name="transtype" value="eclipsecontent"/>
    			<property name="args.draft" value="yes"/>
    			<property name="args.indexshow" value="yes"/>
    			<property name="dita.extname" value="${EXTNAME}"/>
    		</ant>
    	</target>
    	<!-- Create eclipsehelp output -->
    	<target name="dita2eclipsehelp">
    		<ant antfile="${toolkit_dir}${file.separator}build.xml" target="init">
    			<property name="args.input" value="${projdir}/${MAP_file}"/>
    			<property name="output.dir" value="${outdir}/hierarchy/garage_top_1.0"/>
    			<!-- The temp directory is shared by all targets -->
    			<property name="dita.temp.dir" value="${outdir}/hierarchy/temp"/>
    			<property name="transtype" value="eclipsehelp"/>
    			<property name="args.draft" value="yes"/>
    			<property name="args.indexshow" value="yes"/>
    			<property name="dita.extname" value="${EXTNAME}"/>
    		</ant>
    	</target>
    	<!-- Create docbook output -->
    	<target name="dita2docbook">
    		<ant antfile="${toolkit_dir}${file.separator}build.xml" target="init">
    			<property name="args.input" value="${projdir}/${MAP_file}"/>
    			<property name="output.dir" value="${outdir}/hierarchy/docbook"/>
    			<!-- The temp directory is shared by all targets -->
    			<property name="dita.temp.dir" value="${outdir}/hierarchy/temp"/>
    			<property name="transtype" value="docbook"/>
    			<property name="args.draft" value="yes"/>
    			<property name="args.indexshow" value="yes"/>
    			<property name="dita.extname" value="${EXTNAME}"/>
    		</ant>
    	</target>
    	<!-- Create javahelp output -->
    	<target name="dita2javahelp">
    		<property name="jarfile" value="${outdir}/hierarchy/javahelp/garage.jar"/>
    		<ant antfile="${toolkit_dir}${file.separator}build.xml" target="init">
    			<property name="args.input" value="${projdir}/${MAP_file}"/>
    			<property name="output.dir" value="${outdir}/hierarchy/javahelp"/>
    			<!-- The temp directory is shared by all targets -->
    			<property name="dita.temp.dir" value="${outdir}/hierarchy/temp"/>
    			<property name="transtype" value="javahelp"/>
    			<property name="args.draft" value="yes"/>
    			<property name="args.indexshow" value="yes"/>
    			<property name="dita.extname" value="${EXTNAME}"/>
    		</ant>
    		<delete file="${jarfile}"/>
    		<jar destfile="${jarfile}" basedir="${outdir}/hierarchy/javahelp" includes="**">
        </jar>
    	</target>
    	<!-- Create troff output -->
    	<target name="dita2troff">
    		<ant antfile="${toolkit_dir}${file.separator}build.xml" target="init">
    			<property name="args.input" value="${projdir}/${MAP_file}"/>
    			<property name="output.dir" value="${outdir}/hierarchy/troff"/>
    			<!-- The temp directory is shared by all targets -->
    			<property name="dita.temp.dir" value="${outdir}/hierarchy/temp"/>
    			<property name="transtype" value="troff"/>
    			<property name="args.draft" value="yes"/>
    			<property name="args.indexshow" value="yes"/>
    			<property name="dita.extname" value="${EXTNAME}"/>
    		</ant>
    	</target>
    	<!-- Create wordrtf output -->
    	<target name="dita2wordrtf">
    		<ant antfile="${toolkit_dir}${file.separator}build.xml" target="init">
    			<property name="args.input" value="${projdir}/${MAP_file}"/>
    			<property name="output.dir" value="${outdir}/hierarchy/wordrtf"/>
    			<property name="dita.temp.dir" value="${outdir}/hierarchy/temp"/>
    			<!-- The temp directory is shared by all targets -->
    			<property name="transtype" value="wordrtf"/>
    			<property name="args.draft" value="yes"/>
    			<property name="args.indexshow" value="yes"/>
    			<property name="dita.extname" value="${EXTNAME}"/>
    		</ant>
    	</target>
    </project>