Ant argument properties for DITA-OT

Reference list of DITA-specific Ant properties.

DITA-OT processes your documentation project as an Ant project, which allows several Ant build properties specific to DITA-OT and your project. These properties can be divided into three categories:

The following tables describes the first group of properties, grouped by transformation type.

Parameters available to all transforms

The following common parameters are available for use by all DITA-OT builds.

Table 1. Common DITA-OT parameters
Project Ant Property Description
args.debug Specifies that DITA-OT print debugging information for your project. Allowed values are "yes" and "no". Default value is "no".
args.draft Indicates whether draft-comment and required-cleanup elements are included in the generated file. Corresponds to XSLT parameter DRAFT in most XSLT modules. Allowed values are "yes" and "no". Default value is "no".
Tip: For PDF output, setting ${args.draft} to "yes" will also cause the contents of <titlealts> to appear below the title.
args.figurelink.style Specifies how cross references to figures are styled. Allowed values are "NUMBER" and "TITLE". NUMBER results in "Figure 5", TITLE results in the title of the figure. Corresponds to the XSLT parameter FIGURELINK.
Note: This parameter is available for all except the PDF transform.
args.grammar.cache Specifies whether to use the grammar caching feature of the XML parser. Allowed values are "yes" and "no". Default value is "yes".
Note: For most users, this is an important option that dramatically speeds up processing time. However, there is a known problem with using this feature for documents that use XML Entities. If your build fails with parser errors about entity resolution, try setting this parameter to "no".
args.input Typically defines the location of the .ditamap file for your documentation project. However, the property can be set to a .dita file, as well. DITA-OT reads this file to find the .dita files that comprise the content for the documentation project.
args.logdir Defines the location where DITA-OT places log files for your project.
args.outext Specifies the file extension for HTML files in your project's output. Corresponds to XHTML parameter OUTEXT. Default values is ".html".
args.tablelink.style Specifies how cross references to tables are styled. Allowed values are "NUMBER" or "TITLE". Default is "NUMBER", which produces results such as "Table 5". TITLE results in the title of the table. Corresponds to the XSLT parameter TABLELINK.
Note: This parameter is available for all except the PDF transform.
basedir The directory where your project's ant build script resides. The DITA-OT will look for your .dita files relative to this directory. DITA-OT's default build script sets this as an attribute of the project, but you can also define it as a project property.
dita.ext Specifies an extension to use for DITA topics; All DITA topics will use this single extension in the temp directory. Corresponds to XSLT parameter DITAEXT. Default value is ".xml"
dita.input.valfile Defines the location of your project's filter file. Filter files end with the .ditaval suffix and are used to filter, include and exclude, content in the generated document. Alternatively, you can create multiple versions of your document by creating a different .ditamap file for each version.
output.dir The location of the directory to hold output from your documentation project.
transtype Defines the output type for a specific Ant target. Plug-ins may add new values for this option; by default, the following values are available:
  • pdf
  • xhtml
  • htmlhelp
  • eclipsehelp
  • eclipsecontent
  • odt
  • troff
  • rtf
  • javahelp
  • legacypdf
  • docbook
validate Specifies whether DITA-OT should validate your content files. Allowed values are "yes" and "no". Default value is "yes".

Parameters available for all XHTML based transforms

The following parameters are available for all output types that are based on the XHTML transform type, including:

Table 2. XHTML and related parameters
Project Ant Property Description
args.artlbl Adds a label to each image containing the image's filename. Allowed values are "yes" and "no". Default value is "no".
args.breadcrumbs Specifies whether to generate breadcrumb links. Corresponds to the XSLT parameter BREADCRUMBS. Allowed values are "yes" and "no". Default value is "no".
args.copycss Indicates whether you want to copy your own .css file to the output directory.
args.css The name of your custom .css file.
args.csspath The location of your copied .css file relative to the output directory. Corresponds to XSLT parameter CSSPATH.
args.cssroot The directory that contains your custom .css file. DITA-OT will copy the file from this location.
args.ftr Specifies the location of a well-formed XML file containing your custom running-footer for the document body. Corresponds to XSLT parameter FTR.
Note: The fragment must be valid XML, with a single root element, common practice is to place all content into <div>.
args.gen.default.meta Specifies whether to generate extra metadata that targets parental control scanners, meta elements with name="security" and name="Robots". Allowed values are "yes" and "no". Default value is "no". Corresponds to the XSLT parameter genDefMeta.
args.gen.task.lbl Specifies whether to generate locale-based default headings for sections within task topics. Allowed values are "YES" and "NO". Default value is "NO". Corresponds to the XSLT parameter GENERATE-TASK-LABELS.
args.hdf Specifies the location of a well-formed XML file to be placed in the document head.
args.hdr Specifies the location of a well-formed XML file containing your custom running-header for the document body. Corresponds to XSLT parameter HDR.
Note: The fragment must be valid XML, with a single root element, common practice is to place all content into <div>.
args.indexshow Indicates whether indexterm element should appear in the output. Allowed values are "yes" and "no". Default value is "no".
args.xhtml.toc.class String for a CSS class name attribute applied to the TOC (x)HTML output's <body> element. Found in map2htmltoc.xsl.
args.xhtml.classattr Specifies whether to include DITA class ancestry inside generated XHTML elements. Allowed values are "no" and "yes"; the default is "yes" in release 1.5.2 (it was "no" in 1.5 and 1.5.1). For example, the prereq element in a task (which is specialized from section) would generate "class="section prereq". Corresponds to the XSLT parameter PRESERVE-DITA-CLASS.
args.xsl Specifies an XSL file that is used rather than the default XSL transform, located in toolkitdir\xsl\dita2xhtml.xsl. Property must specify the full path and XSL file name.
generate.copy.outer Specifies whether to generate files for content files that are not located in or beneath the directory containing your ditmap file. Supported values are:
  • "1" (default) – do not generate outer files
  • "2 – generate outer files
  • "3" – old solution.
onlytopic.in.map Specifies whether files that are linked to, or referenced with a conref attribute, should generate output. If set to "yes", only files that are referenced directly from the map will generate output files.
outer.control Specifies whether content files are located in or below the directory containing your .ditamap file. Supported values are:
  • "fail" – fail quickly if files are going to be generated/copied outside of that directory
  • "warn" (default) – complete if files will be generated/copied outside, but log a warning
  • "quiet" – quietly finish with only those files (no warning or error).
The gen-list-without-flagging Ant task generates a harmless warning for content outside the map directory; you can suppress these warnings by setting the outer.control property to "quiet".
Warning: Microsoft HTML Help Compiler cannot produce HTMLHelp for documentation projects that use outer content. Your content files must reside in or below the directory containing the .ditamap file, and the map file cannot specify ".." at the start of href attributes for topicref elements.

PDF-specific Ant Properties

The following table describes Ant properties that are specific to the PDF transformation type.

Table 3. PDF parameters
Project Ant Property Description
args.gen.task.lbl Specifies whether to generate locale-based default headings for sections within task topics. Allowed values are "YES" and "NO". Default value is "NO". Corresponds to the XSLT parameter GENERATE-TASK-LABELS.
args.xsl.pdf Specifies an XSL file that is used in place of the default XSL transform at demo\fo\xsl\fo\topic2fo_shell.xsl. You must specify the full path and XSL file name.
publish.required.cleanup Indicates whether draft-comment and required-cleanup elements are included in the generated file. Allowed values are "yes" and "no". Default value is value of args.draft property. Deprecated, args.draft parameter should be used instead. Corresponds to XSLT parameter publishRequiredCleanup.
args.fo.userconfig The parameter to specify the user configuration file for FOP.
custom.xep.config The parameter to specify the user configuration file for RenderX.
retain.topic.fo Specifies whether to leave the generated FO file for a PDF project.
args.bookmap-order Specify if frontmatter and backmatter content order is retained in bookmap. Values are "retain" and "discard" (default).
customization.dir Specifies the customization directory path.
pdf.formatter Specified the XSL processor to use. Supported values are:
  • "fop" (default) – Apache FOP
  • "ah" – Antenna House Formatter
  • "xep" – RenderX XEP Engine
The Full Easy Install distribution package comes with Apache FOP installed, other XSL processors need to be separately installed.

ODT-specific Ant Properties

The ODT transform, which produces a document using the Open Document Format, is available in the 1.5.2 version of the DITA-OT.

Table 4. ODT related parameters
Project Ant Property Description
args.odt.img.embed Determines whether images are embedded as binary objects within the ODT file.

EclipseContent-specific Ant Properties

The "eclipsecontent" transform type produces normalized DITA files, along with Eclipse TOC and project files.

Table 5. EclipseContent properties
Project Ant Property Description
args.eclipsecontent.toc Specifies the name of the TOC file for an Eclipse Content project.

XHTML-specific Ant Properties

Parameters in this section are used by the "xhtml" transtype, but not by other XHTML based transforms.

Table 6. Properties for the "xhtml" transform type
Project Ant Property Description
args.xhtml.contenttarget Specifies the content frame name where links from TOC are opened.
args.xhtml.toc Specifies the name of the entry point for an XHTML project. Default value is index.html

EclipseHelp-specific Ant Properties

The following table describes Ant properties that are specific to the EclipseHelp transformation type, which is an XHTML based output for use with the Eclipse Help System.

Project Ant Property Description
args.eclipsehelp.toc Specifies the name of the TOC file.
args.eclipse.country Specifies the more specific region for the language specified with args.eclipse.language For example, US, CA and GB would clarify a value of "en" for args.eclipse.language. The content will be moved into the appropriate directory structure for an Eclipse fragment.
args.eclipse.language Specifies the base language for translated content, such as "en" for English. This parameter is a prerequisite for args.eclipse.country. The content will be moved into the appropriate directory structure for an Eclipse fragment.
args.eclipse.provider Specifies the name of the person or organization providing an Eclipse Help project. Default value is DITA.
Tip: The toolkit ignores the value of this property when processing an Eclipse Collection Map, eclipse.dtd.
args.eclipse.version Specifies the version number to include in the output. Default value is 0.0.0.
Tip: The toolkit ignores the value of this property when processing an Eclipse Collection Map, eclipse.dtd.
args.eclipse.symbolic.name Specifies the symbolic name (aka plugin ID) in the output for an Eclipse Help project. The @id value from the DITA map or the Eclipse map collection (Eclipse help specialization) is the symbolic name for the plugin in Eclipse. By default, the value org.sample.help.doc.
Tip: The toolkit ignores the value of this property when processing an Eclipse Collection Map, eclipse.dtd.

HtmlHelp-specific Ant Properties

The following table describes Ant properties that are specific to the HTML Help compiled help transformation target.

Project Ant Property Description
args.htmlhelp.includefile Specifies the name of a file that you want included in an HTMLHelp project.

JavaHelp-specific Ant Properties

The following table describes Ant properties that are specific to the JavaHelp transformation target.

Project Ant Property Description
args.javahelp.map Specifies the name of the ditamap file for a JavaHelp project.
args.javahelp.toc Specifies the name of the file containing the TOC in your JavaHelp output. Default value is the name of the ditamap file for your project.

Other Toolkit Ant Properties

The following table describes additional Ant properties specific to the DITA Open Toolkit that you may override. You should not override a DITA-OT Ant property if it does not appear in this table or one of the tables above.

DITA Ant Property Description
args.dita.locale Specifies the language locale file to use for sorting index entries. The JavaHelp transformation type also uses this parameter.
clean.temp Specifies whether DITA-OT should delete the files in the temporary directory, dita.temp.dir, when it finishes a build. Allowed values are "yes" and "no". Default value is "yes".
dita.dir The location of your DITA-OT installation. Verify that your project's build script points to the correct location.
dita.extname Deprecated, dita.ext parameter should be used instead. Defines the file extension for content files in the directory specified with the dita.temp.dir property. Allowed values are ".xml" and ".dita"; Default value is ".xml".
dita.preprocess.reloadstylesheet Instructs the toolkit to reload the XSL stylesheets used for transformation. Allowed values are "true" and "false". Default value is "false".
Tip: Set the value to true if you want to use more than one set of stylesheets to process a group of topics. The parameter is also useful for writers of toolkit build scripts who experience Java memory problems during transformation due to large Ant projects. Alternatively, you can adjust the size of your Java memory heap if setting dita.preprocess.reloadstylesheet for this reason.
dita.preprocess.reloadstylesheet.conref
dita.preprocess.reloadstylesheet.mapref
dita.preprocess.reloadstylesheet.mappull
dita.preprocess.reloadstylesheet.topicpull
dita.temp.dir Defines the directory where DITA-OT will create a temporary directory to place temporary files generated during the transformation process.