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 common parameters are available for use by all DITA-OT builds.
Project Ant Property | Java Option | Description |
---|---|---|
args.debug | /debug | Specifies that DITA-OT print debugging information for your project. |
args.draft | /draft | Indicates whether draft-comment and required-cleanup elements
are included in the generated file. Corresponds to XSLT parameter
DRAFT in most XSLT modules. Default value is "no". f ${publish.required.cleanup} is
not set, ${args.draft} will be used. Tip: The ${publish.required.cleanup} property
is a legacy property that applies only to PDF transformations. The args.draft parameter
should be used instead.
Tip: For PDF output, setting ${args.draft} to
"yes" will also cause the contents of <titlealts> to
appear below the title.
|
args.grammar.cache | /grammarcache | Specifies whether to use the grammar caching
feature of the XML parser. Values are "yes" and "no". The default
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 | /i | Typically defines the location of the .ditamap file for your documentation project. However, the propery 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 | /logdir | Defines the location where DITA-OT places log files for your project. |
args.outext | /outext | Specifies the file extension for HTML files in your project's output. |
basedir | /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.input.valfile | /filter | 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 | /outdir | The location of the directory to hold output from your documentation project. |
transtype | /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:
|
validate | /validate | Specifies whether DITA-OT should validate your content files. The default value is "yes". |
Project Ant Property | Java Option | Description |
---|---|---|
args.artlbl | /artlbl | Adds a label to each image containing the image's filename. |
args.breadcrumbs | NA | Specifies whether to generate breadcrumb links. Corresponds to the XSLT parameter BREADCRUMBS. Allowed values are "yes" and "no". Default is "no". |
args.copycss | /copycss | Indicates whether you want to copy your own .css file to the output directory. |
args.css | args.css | The name of your custom .css file. |
args.csspath | /csspath | The location of your copied .css file relative to the output directory |
args.cssroot | /cssroot | The directory that contains your custom .css file. DITA-OT will copy the file from this location. |
args.figurelink.style | NA | 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. |
args.ftr | /ftr | Specifies the location of a well-formed XML file containing your custom running-footer for the document body. |
args.gen.default.meta | NA | Specifies whether to generate extra metadata that targets parental control scanners, meta elements with name="security" and name="Robots". Allowd values are "yes" and "no". The default is "no". Corresponds to the XSLT parameter genDefMeta. |
args.gen.task.lbl | /usetasklabels | Specifies whether to generate locale-based default headings for sections within task topics. Allowed values are "YES" and "NO". Default is "NO". Corresponds to the XSLT parameter GENERATE-TASK-LABELS. This parameter is also available for the PDF transform. |
args.hdf | /hdf | Specifies the location of a well-formed XML file to be placed in the document head. |
args.hdr | /hdr | Specifies the location of a well-formed XML file containing your custom running-header for the document body. |
args.hide.parent.link | NA | Specifies whether to hide links to parent topics in the rendered XHTML. Corresponds to the XSLT parameter NOPARENTLINK. Allowed values are "yes" and "no". Default is "no". |
args.indexshow | /indexshow | Indicates whether indexterm element should appear in the output. |
args.tablelink.style | NA | Specifies how cross references to tables are styled. Allowed values are "NUMBER" or "TITLE". The default is "NUMBER", which produces results such as "Table 5". TITLE results in the title of the table. Corresponds to the XSLT parameter TABLELINK. |
args.xhtml.classattr | /xhtmlclass | 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 | /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 | /generateouter | Specifies whether to generate files for content files that are not located in or beneath the directory containing your ditmap file. |
onlytopic.in.map | /onlytopicinmap | 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 | /outercontrol | Specifies whether content files are located
in or below the directory containing your .ditamap file.
The default value is "no." 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 "true". 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 specifiy ".." at the start of href attributes for topicref elements. |
The following table describes Ant properties that are specific to the PDF transformation type.
Project Ant Property | Java Option | Description |
---|---|---|
args.fo.include.rellinks | /foincluderellinks | Specifies which links to include in the
PDF file. Values are:
|
args.fo.output.rel.links | /fooutputrellinks | Note: This parameter is deprecated in favor
of ${args.fo.include.rellinks}.
Specifies whether
to show links in your project's output. Values are "yes" (include
all links) and "no" (the default, include no links). If ${args.fo.include.rellinks} is
specified, this parameter is ignored. |
args.gen.task.lbl | /usetasklabels | Specifies whether to generate locale-based default headings for sections within task topics. Allowed values are "YES" and "NO". Default is "NO". Corresponds to the XSLT parameter GENERATE-TASK-LABELS. This parameter is also available for the XHTML based transforms. |
args.xsl.pdf | /xslpdf | Specifies an XSL file that is used in place of the default XSL transform at toolkitdir\demo\fo\xsl\fo\topic2fo_shell.xsl. You must specify the full path and XSL file name. |
retain.topic.fo | /retaintopicfo | Specifies whether to leave the generated FO file for a PDF project. |
The ODT transform, which produces a document using the Open Document Format, is available in the 1.5.2 version of the DITA-OT.
Project Ant Property | Java Option | Description |
---|---|---|
args.odt.img.embed | /odtimgembed | Determines whether images are embedded as binary objects within the ODT file. |
args.odt.include.rellinks | /odtincluderellinks | Specifies which links to include in the ODT file. Values are:
|
The "eclipsecontent" transform type produces normalized DITA files, along with Eclipse TOC and project files.
Project Ant Property | Java Option | Description |
---|---|---|
args.eclipsecontent.toc | /eclipsecontenttoc | Specifies the name of the TOC file for an Eclipse Content project. |
Parameters in this section are used by the "xhtml" transtype, but not by other XHTML based transforms.
Project Ant Property | Java Option | Description |
---|---|---|
args.xhtml.toc | /xhtmltoc | Specifies the name of the entry point for an XHTML project. The default value is index.html |
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 | Java Option | Description |
---|---|---|
args.eclipsehelp.toc | /eclipsehelptoc | Specifies the name of the TOC file for an Eclipse Help project. |
args.eclipse.country | NA | Specifies the more specifc 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. |
args.eclipse.language | NA | Specifies the base language for translated content, such as "en" for English. |
args.eclipse.provider | /provider | Specifies the name of the person or organization providing an Eclipse Help project. |
args.eclipse.version | /version | Specifies the version number to include in the output for an Eclipse Help project. |
The following table describes Ant properties that are specific to the HTML Help compiled help transformation target.
Project Ant Property | Java Option | Description |
---|---|---|
args.htmlhelp.includefile | /htmlhelpincludefile | Specifies the name of a file that you want included in an HTMLHelp project. |
The following table describes Ant properties that are specific to the JavaHelp transformation target.
Project Ant Property | Java Option | Description |
---|---|---|
args.javahelp.map | /javahelpmap | Specifies the name of the ditamap file for a JavaHelp project. |
args.javahelp.toc | /javahelptoc | Specifies the name of the file contaning the TOC in your JavaHelp output. The default value is the name of the ditamap file for your project. |
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 | Java Option | Description |
---|---|---|
dita.temp.dir | /tempdir | Defines the directory where DITA-OT will create a temporary directory to place temporary files generated during the transformation process. |
dita.extname | /ditaext | Deprecated. Defines the file extension for content files in the directory specified with the dita.temp.dir property. Valid values are ".xml" and ".dita"; the default is ".xml". |
dita.dir | /ditadir | The location of your DITA-OT installation. Also referred to as toolkit_dir in the sample ant scripts. Verify that your project's build script points to the correct location. |
clean.temp | /cleantemp | Specifies whether DITA-OT should delete the files in the temporary directory, dita.temp.dir, when it finishes a build. |
args.dita.locale | /ditalocale | Specifies the language locale file to use for sorting index entries. The JavaHelp transformation type also uses this parameter. |