Ant tasks and scripts

This topic describes detailed Ant tasks and scripts.

The build process including pre-process can be called by using an Ant script. The most important Ant script files are called build.xml, build_general.xml, and build_preprocess.xml; together they define common pre-processing and output transformation routines, as well as extension points that allow DITA-OT Plug-ins to add to this common processing.

The following table lists many general parameters to the DITA-OT transforms.

Table 1. General Parameter Table
Parameter Description Required
basedir The path of the working directory for transformations, it will be the base of relative paths specified by other parameters.
Note:
  • If input is relative, it will be set relative to the current directory.
  • In Ant scripts, the default is that specified in the Ant buildfile.
  • In Java command line, the default is current directory.
No
dita.dir The absolute path of the toolkit's home directory. No
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. DEPRECATED - use args.input instead.
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. DEPRECATED - use args.input instead.
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, dita2rtfImpl.xsl in word 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 & required-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
args.logdir The directory used to keep generated log files. Default will be output directory.
Note: If several transforms running batchly, e.g., ant all:
  • If the user has specified a common logdir for all transformations, it will be used as log directory.
  • If the user hasn't specified a common dir for all transformations:
    • If all transformations have same output directory, the common output direcory will be used as log directory.
    • If there is no same output directory for all transformations, the basedir will be used as default log directory.
No
validate The parameter to specify whether the ditamap/dita/xml files to be validated. Only "true" and "false" are valid values. The default is true.
Note: It is not recommended to turn off the validation function , which will cause unexpected error during transformation.
No
outer.control The parameter to specify how to respond to the overflowing dita/topic files. Only "fail", "warn" and "quiet" are valid values. The default is warn.
Note: The detailed introduction:
  • fail: Fail quickly if files are going to be generated/copied outside of that directory
  • warn: Complete if files will be generated/copied outside, but log a warning
  • quiet: Quietly finish with only those files (no warning or error)
No
generate.copy.outer The parameter to specify how to deal with the overflowing dita/topic files. Only "1", "2" and "3" are valid values. The default is 1.
Note: The detailed introduction:
  • 1: Only generate/copy files that fit within the designated output directory.
  • 2: Generate/copy all files, even those that will end up outside of the output directory.
  • 3: the old solution,adjust the input.dir according to the referenced files. (not default option any more but keep this as the option of backward compatibility).
No
onlytopic.in.map The parameter to specify whether the referenced dita/topic files which are not referenced by ditamap files should be resolved. Only "true" and "false" are valid values. The default is false. No

The following table lists general parameters that apply to the various HTML and XHTML based output formats.

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.outdir}${args.csspath}. "no" and "yes" are valid values. Default is "no". 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 from website.
Note: If ${args.csspath} is an URL, the ${args.css} should be a filepath relative to the URL.
No
args.cssroot The root directory of user specified css file.
Note: If this parameter is set, the ${args.css} should be a filepath relative to args.cssroot.
No
args.csspath The path for css reference. Default is no path.
Note:
  • If ${args.csspath} is an URL like path, it should starts with http:// or https://. For example: http://www.ibm.com/css.
  • Local absolute paths is not supported for ${args.csspath}.
  • Use '/' as the path separator and don't append separator at last. For example: css/mycss.
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

Several additional parameters are available for other output formats.

XHTML (no navigation)
Table 3. Parameters for the dita2xhtml target
Parameter Description Required
args.xhtml.toc The root file name of the output xhtml toc file in xhtml transformation. The default is 'index'. No
Eclipse help output
Table 4. Parameters for the dita2eclipsehelp target
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
args.eclipse.provider The provider name of the eclipse help output. The default value is DITA. No
args.eclipse.version The version number of the eclipse help output. The default value is 1.0 No
Eclipse Content (also known as normalized or dynamic DITA)
Table 5. Parameters for the dita2eclipsecontent target
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
args.eclipse.provider The provider name of the eclipse help output. The default value is DITA. No
args.eclipse.version The version number of the eclipse help output. The default value is 1.0 No
HTML Help
Table 6. Parameters for the dita2htmlhelp target
Parameter Description Required
args.dita.locale The locale used for sorting indexterms. If no locale specified, the first occurrence of "xml-lang" will be used as default locale; If no "xml-lang" found, "en-us" will be used by default. No
args.htmlhelp.includefile The parameter to specify the file that need to be included by the HTMLHelp output. No
Java Help
Table 7. Parameters for the dita2javahelp target
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
args.dita.locale The locale used for sorting indexterms. If no locale specified, the first occurrence of "xml-lang" will be used as default locale; If no "xml-lang" found, "en-us" will be used by default. No

RTF output: The transform from DITA to Word RTF does not support the args.artlbl parameter from the general parameters table.

Legacy PDF output: The default PDF output, which was initially developed as a plug-in to the toolkit, is not described here. The following parameters are only for the older PDF transform, now known as the "legacypdf" transform.
Table 8. Parameters to the LEGACY PDF TRANSFORM dita2legacypdf
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
args.fo.output.rel.links The parameter to specify whether output related links in pdf transformation. "yes" and "no" are valid values. Default is "no". No
args.fo.userconfig The parameter to specify the user configuration file for FOP. No

Sample ant script

These ant scripts are in samples/ant_sample 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 samples/ant_samples directory:
<?xml version="1.0" encoding="UTF-8" ?>
<project name="@PROJECT.NAME@_xhtml" default="@DELIVERABLE.NAME@2xhtml" basedir=".">

  <property name="dita.dir" value="${basedir}${file.separator}..${file.separator}.."/>
 
  <import file="${dita.dir}${file.separator}integrator.xml"/>

  <target name="@DELIVERABLE.NAME@2xhtml" depends="integrate">
    <ant antfile="${dita.dir}${file.separator}build.xml" target="init">
      <!-- please refer to the toolkit's document for supported parameters, and 
           specify them base on your needs -->
      <property name="args.input" value="@DITA.INPUT@"/>
      <property name="output.dir" value="@OUTPUT.DIR@"/>
      <property name="transtype" value="xhtml"/>
    </ant>
  </target>

</project>
To use this template, modify the following items:
  • Replace @PROJECT.NAME@ with the name of your project, such as "MyDocs".
  • Replace @DELIVERABLE.NAME@ with the name of your deliverable, such as "installDocs".
  • Replace @DITA.INPUT@ with the name of your input file (using either a full path or a relative path from the location of this template).
  • Replace @OUTPUT.DIR@ with the desired output directory (using either a full path or a relative path from the location of this template).
Once you have updated these items, you can run your build with the following command:
ant -f samples/ant_sample/template_xhtml.xml

The build will convert your input file to XHTML. Note that the build directly calls the Ant script "build.xml", which is a common entry point for DITA-OT builds; it in turn imports all of the scripts mentioned above.

Note: To get a more accurate error reporting about the transformation, you may add the command-line option -logger org.dita.dost.log.DITAOTBuildLogger after your Ant command.