Ant tasks and script

This topic lists detailed Ant tasks and script.

The build process including pre-process can be called by using Ant script. There are four major Ant script files:

conductor.xml, pretargets.xml, ditatargets.xml and catalog-ant.xml.

conductor.xml
The main Ant script file includes the other three ant scripts and provides main targets for every output style.
Table 1. General Parameter Table
Parameter Description Required
args.input The path and name of the input file. This argument should be in the same upper or lower case with the filename on file system.
Note: This parameter must be provided if dita.input and dita.input.dirname not be provided.
 No
dita.input The name of the input file .
Note: This parameter must be provided if args.input not be provided. And this parameter must be used together with the dita.input.dirname parameter. The result of this combination is equivalent to use only the args.input parameter. It is an alternative way to specify the path and name of the input file.
 No
dita.input.dirname The input directory which contains the input file.
Note: This parameter must be provided if args.input not be provided. And this parameter must be used together with the dita.input parameter. The result of this combination is equivalent to use only the args.input parameter. It is an alternative way to specify the path and name of the input file.
 No
dita.temp.dir The directory of the temporary files. The default is 'temp'. No
output.dir The path of the output directory. Yes
dita.extname The file extension name of the input topic files, for example, '.xml' or '.dita'. The default is '.xml'. No
args.xsl The xsl file to replace the default xsl file. It will replace dita2docbook.xsl in docbook transformation, dita2fo-shell.xsl in pdf transformation, dita2xhtml.xsl in xhtml/eclipsehelp transformation, and dita2html.xsl in javahelp/htmlhelp transformation. No
dita.input.valfile The name of the file containing filter/flagging/revision information. No
args.draft Default "hide draft & cleanup content" processing parameter ("no"= hide them); "no" and "yes" are valid values; non-"yes" is ignored. No
args.artlbl Default "output artwork filenames" processing parameter; "no"and "yes"are valid values; non-"yes" is ignored. No
clean.temp The parameter to specify whether to clean the temp directory before each build. Only "no" and "yes" are valid values. The default is yes. No
Table 2. General Parameter Table for Tasks(dita2xhtml,dita2htmlhelp,dita2javahelp,dita2eclipsehelp)
Parameter Description Required
args.indexshow The parameter to specify whether each index entry should display within the body of the text itself. Only "no" and "yes" are valid values. No
args.copycss The parameter to specify whether copy user specified css files to the directory specified by args.csspath. Only "no" and "yes" are valid values. No
args.outext The output file extension name for generated xhtml files. Typically, '.html' or '.htm' can be used as the extension name for the generated xhtml files. You can also specify other extension name. The default is '.html'. No
args.css User specified css file, it can be a local file or remote file in the web.
Note: It must be a filepath relative to URL or local root dir base on the type of args.csspath.
 No
args.csspath The path for css reference, it can be a URL start with 'http://' or 'https://', it also can be a local absolute directory. Default will be output directory.
Note: args.csspath should end with '/' if it is a URL, or file separator for local path.
 No
args.hdf The name of the file containing XHTML to be placed in the HEAD area. No
args.hdr The name of the file containing XHTML to be placed in the BODY running-heading area. No
args.ftr The name of the file containing XHTML to be placed in the BODY running-footing area. No
targets in conductor.xml

The following targets in conductor.xml will call the complete processing of DITA files which can be loaded by users.

dita2docbook
Transform DITA topic or DITA map into docbook output.
dita2eclipsehelp
Transform DITA topic or DITA map into Eclipse help plugin based on xhtml.
Table 3. Parameter Table of dita2eclipsehelp
Parameter Description Required
args.eclipsehelp.toc The root file name of the output eclipsehelp toc file in eclipsehelp transformation. The default is the name of input ditamap file. No
dita2eclipsecontent
Transform DITA topic or DITA map into Eclipse help plugin for Eclipse dynamic content provider based on xhtml.
Table 3. Parameter Table of dita2eclipsecontent
Parameter Description Required
args.eclipsecontent.toc The root file name of the output Eclipse content provider toc file in eclipsecontent transformation. The default is the name of input ditamap file. No
dita2htmlhelp
Transform DITA topic or DITA map into html help output based on html.
dita2javahelp
Transform DITA topic or DITA map into java help output based on html.
Table 3. Parameter Table of dita2javahelp
Parameter Description Required
args.javahelp.toc The root file name of the output javahelp toc file in javahelp transformation. The default is the name of input ditamap file. No
args.javahelp.map The root file name of the output javahelp map file in javahelp transformation. The default is the name of input ditamap file. No
dita2xhtml
Transform DITA topic or DITA map into xhtml web output.
Table 3. Parameter Table of dita2xhtml
Parameter Description Required
args.xhtml.toc The root file name of the output xhtml toc file in xhtml transformation. The default is 'index'. No
dita2pdf
Transform DITA topic or DITA map into pdf.
Table 3. Parameter Table of dita2pdf
Parameter Description Required
args.fo.img.ext The extension name of image file in pdf transformation. Only '.jpg', '.gif' are valid value. The default is '.jpg'.
Note: Only one extension supported in the same transformation, image files with other extensions will be renamed to the specified extension.
 No
dita2troff
Transform DITA map into troff, which is the system menu style in UNIX system.
pretargets.xml
The Ant script file which contains all targets for pre-process.
ditatargets.xml
The Ant script file which contains all targets for main transformation.
catalog-ant.xml
The xml catalog information which is used by Ant.

Sample ant script

These ant scripts are in ant directory. They are simple and easy to learn. From these files, you can learn how to write your own Ant script to build your own process.

Here is a sample template for writing an Ant script that executes transformation to xhtml in ant directory 
<?xml version="1.0" encoding="UTF-8" ?>
<project name="sample_xhtml" default="all" basedir=".."> 
  <import file="${basedir}${file.separator}conductor.xml"/> 
  <property name="dita.extname" value=".xml"/> 
  <target name="all" depends="sample2xhtml"> </target> 
  <!-- revise below here --> 
  <target name="sample2xhtml" depends="use-init"> 
    <antcall target="dita2xhtml"> 
      <param name="args.input" value="@DITA.INPUT@"/> 
      <param name="output.dir" value="@OUTPUT.DIR@"/> 
    </antcall> 
  </target> 
</project>
After you write the input file and output directory to overwrite @DITA.INPUT@ and @OUTPUT.DIR@, the script can execute the transformation from your input to xhtml by this command. The property of dita.extname is a global variable with which you can set the file extension name of the topic file. The default dita.extname is ".xml". You can also set it to ".dita" according to OASIS DITA recommendation. 
ant -f ant/template_xhtml.xml
All of targets we use here are defined in conductor.xml. Therefore, you need to import that file before calling the target.
Parent topic: Building DITA output with Ant