Chapter 3. The ditac command-line utility

ditac [option]* output_file [in_dita_file]+

Command-line usage

Converts specified DITA input files to specified output file.
The input files must comprise a single map or bookmap file or possibly several, possibly multi-topic, topic files.
Example: convert the userguide.ditamap map to multi-page XHTML:
C:\docsrc> ditac -p center "fig table" ..\doc\userguide.htm userguide.ditamap
Example: convert the introduction.dita and quickstart.dita topics to PDF:
C:\docsrc> ditac draft1.pdf introduction.dita  quickstart.dita
An input file may be specified using its URL or its filename.
The output directory is created if it does not already exist.
In some case, there is no need to specify a real output filename: the output directory and the extension of the output files suffice. In such case, specify "_" as the basename of the output file.
Example: convert foo.ditamap to multi-page XHTML. The XHTML pages must be generated in the bar/ subdirectory.
C:\docsrc> ditac bar\_.html foo.ditamap
In the above case, the basenames of the generated XHTML pages will be taken from the @chunk and @copy-to attributes specified in foo.ditamap if any, and from the basename of the map ("foo" in the case of our example) otherwise.

Commonly used command-line options

Some options have both a short name and a long name. Example: -p is equivalent to -param.
-p param_name param_value
-param param_name param_value
Specifies a XSLT stylesheet parameter. See Chapter 4.
-t XSLT_stylesheet_URL_or_file
-xslt XSLT_stylesheet_URL_or_file
Use the specified custom XSLT stylesheet rather than the stock one.
-c none|single|auto
-chunk none|single|auto
The "none" and "single" values may be used to force the generation of a single output file.
For example, "-chunk single" allows to reuse a map designed to output multiple HTML pages in order to generate a PDF file.
For example, "-chunk none" allows to reuse a map designed to output a PDF file in order to generate a single HTML page.
By default, the chunk mode is auto which means: generate a single output file (implicit "-chunk none") for formats such as pdf, ps, rtf, etc, and generate multiple output files for formats such as html, xhtml, javahelp, etc.
-f xhtml | xhtml1.1 | html | xhtml5 | html5 | webhelp | webhelp5 | epub | epub3 | javahelp | htmlhelp | ps | pdf | rtf | odt | wml | docx | fo
-format xhtml | xhtml1.1 | html | xhtml5 | html5 | webhelp | webhelp5 | epub | epub3 | javahelp | htmlhelp | ps | pdf | rtf | odt | wml | docx | fo
Explicitly specifies the output format. By default, the output format is determined using the extension of output_file.
Notes:
  • A "htm" or "html" filename extension implicitly specifies an XHTML 1.0 output format, and not an HTML 4.01 output format. In order to generate HTML 4.01, explicitly specify "-f html". The same remark applies to xhtml1.1, xhtml5, webhelp, webhelp5.
  • Option html5 is simply an alias for xhtml5.
  • Option webhelp5 means Web Help containing XHTML 5 pages rather than XHTML 1 pages.
  • Option epub specifies the EPUB 2 format.
-r resource_path
-resources resource_path
-i resource_path
-images resource_path
Copy the resource files, typically image files, referenced in the source topics to specified directory. If specified path is relative, it is relative to the output directory.
-resourcehandler class_name parameters
Pass the resource files, typically image files, referenced in the source topics to class_name, a Java™ class implementing interface com.xmlmind.ditac.preprocess.ResourceHandler. String parameters is used to configure the newly created ResourceHandler.
For example, "-r res" is equivalent to "-resourcehandler com.xmlmind.ditac.convert.ResourceCopier res".
-filter ditaval_URL_or_file
Apply specified conditional processing profile (.ditaval file) to the topics.
-toc
Equivalent to "-frontmatter toc".
Note that this option will not cause a Table of Contents to be generated when the map contains a single <topicref>(1) having no <topicref> descendants.
-index
Equivalent to "-backmatter indexlist".
-frontmatter spec
Automatically generate specified sections: Table of Contents, List of Tables, etc, before the other pages.
When used on a <bookmap>, this option adds elements after any existing <booklists> elements.
The syntax of spec is:
spec -> same_page [ ',' same_page ]*

same_page -> section [ '+' section ]*

section -> 'toc'|'figurelist'|'tablelist'|'examplelist'|
           'equationlist'|'indexlist'
Example: generate the Table Of Contents in its own page, followed by another page containing both the List of Figures and the List of Tables.
-frontmatter toc,figurelist+tablelist
-backmatter spec
Automatically generate specified sections: Table of Contents, List of Tables, etc, after the other pages. See -frontmatter for more information.
When used on a <bookmap>, this option adds elements before any existing <booklists> elements.
-addindex
When an output file contains the Table of Contents (let's call this file main.html) and when no file called index.html has been generated, this option allows to copy main.html to index.html. Applies to formats: xhtml, xhtml1.1, html, webhelp.
-lang language_code
Specifies the main language of the document
Shorthand for:
-foconverter  pdf "executable_file" 
-foconverter  ps "executable_file" 
. Examples: "fr", "fr-CA". Needed to sort the index entries.
By default, this information is taken from the @xml:lang attribute of the root element of the topic map (if any, "en" otherwise).
-v
-vv
-vvv
Turn verbosity on. More Vs means more verbose.
-o options_URL_or_file
-option options_URL_or_file
This option allows to specify a text file containing command-line arguments. This text file has the same format as the ditac.options file.
Example:
$ ditac -v -o html.options foo.htm foo.ditamap
If html.options contains:
-format html
-p css http://www.acme.com/css/acme.css
then this is equivalent to running:
$ ditac -v -format html -p css http://www.acme.com/css/acme.css \
    foo.htm foo.ditamap

Command-line options used to configure ditac

-fop executable_file
Specifies the location of the fop shell script (fop.bat on Windows).
Shorthand for:
-foconverter FOP pdf "executable_file" -q -r -fo "%I" -pdf "%O"
-foconverter FOP ps "executable_file" -q -r -fo "%I" -ps "%O"
-xep executable_file
Specifies the location of the xep shell script (xep.bat on Windows).
Shorthand for:
-foconverter XEP pdf "executable_file" -quiet -valid -fo "%I" -pdf "%O"
-foconverter XEP ps "executable_file" -quiet -valid -fo "%I" -ps "%O"
-ahf executable_file
Specifies the location of AHFCmd.exe (run.sh on platforms other than Windows).
Shorthand for:
-foconverter AHF pdf "executable_file" -x 3 -p @PDF -d "%I\" -o "%O"
-foconverter AHF ps "executable_file" -x 3 -p @PS -d "%I" -o "%O"
-xfc executable_file
Specifies the location of the fo2rtf shell script (fo2rtf.bat on Windows).
Suffice to specify the location of fo2rtf. Using this location, ditac infers the locations of fo2wml, fo2docx and fo2odt.
Shorthand for:
-foconverter XFC rtf "fo2rtf_executable_file" "%I" "%O"
-foconverter XFC wml "fo2wml_executable_file" "%I" "%O"
-foconverter XFC docx "fo2docx_executable_file" "%I" "%O"
-foconverter XFC odf "fo2odt_executable_file" "%I" "%O"
-foconverter processor_name target_format command
Register specified XSL-FO converter with ditac, a lower-level alternative to using -xep, -fop, -ahf or -xfc. Example:
-foconverter XFC rtf '/opt/xfc/bin/fo2rtf "%I" "%O"'
Note that this option can be specified several times with different values in the same command-line.
This low-level option may be used for example to specify a configuration file for Apache FOP Opens in new window:
-foconverter FOP pdf \
  '/opt/fop/fop -c /home/john/docs/fop.conf -q -r -fo "%I" -pdf "%O"'
-jhindexer executable_file
Specifies the location of the jhindexer shell script (jhindexer.bat on Windows), the Java™ Help indexer.
-hhc exe_file
Specifies the location of hhc.exe, the HTML Help compiler.
-plugin plugin_name
Use the DTDs/schemas and the XSLT stylesheets found in the plug-in subdirectory having specified name preferably to those found in ditac_install_dir/schema/ and in ditac_install_dir/xsl/. See What is a plug-in?.

Command-line options used to debug ditac

-preprocess
Stop after preprocessing input files.
-automap save_file
Save the automatically generated topic map (if any) to specified file.
-keepfo
When generating PDF, RTF, etc, do not delete the temporary XSL-FO file.
-errout
Output all messages, including errors and warnings, to stdout.
-ignoreoptionsfile
Do not load the ditac.options options file. See below The ditac.options file.
-validate
Validate all the XML files loaded by ditac. Any validation error will cause ditac to immediately stop running. Therefore the combination of the -validate and -dryrun options gives you a simple way to thoroughly check your DITA document.
Note that for the -validate option to work, all the XML files (maps, topics, even .ditaval filter files) loaded by ditac must start with the proper <!DOCTYPE> declaration.
-dryrun
Use ditac as a validator, and most notably check cross-references. That is, do not generate any file; just report errors if any .
-version
Print version number and exit.

The ditac.options file

It is also possible to specify command-line options in the ditac.options options file. The content of this plain text file, encoded in the native encoding of the platform (e.g. Windows-1252 on a Western Windows PC), is automatically loaded by ditac each time this command is executed. The content of this file, command-line options separated by whitespace, is prepended to the options specified in the command-line.
Example: If ditac.options contains:
-v -p number all
Running:
~/docsrc$ ditac -p center "fig table" ../doc/userguide.htm userguide.ditamap
is equivalent to running:
~/docsrc$ ditac -v -p number all -p center "fig table" \
    ../doc/userguide.htm userguide.ditamap
The ditac.options options file is found in the ditac user preferences directory. This directory is:
  • $HOME/.ditac/ on Linux.
  • $HOME/Library/Application Support/XMLmind/ditac/ on the Mac.
  • %APPDATA%\XMLmind\ditac\ on Windows XP, Vista, 7, 8, 10.
    Example: C:\Documents and Settings\john\Application Data\XMLmind\ditac\ on Windows XP. C:\Users\john\AppData\Roaming\XMLmind\ditac\ on Windows Vista, 7, 8, 10.
The ditac.options options file is mainly useful to configure ditac once for all by specifying values for the -fop, -xep, -xfc, -jhindexer, -hhc, -plugin options.
Example:
-v
-xep E:\opt\xep\xep.bat
-fop E:\opt\fop-2.1\fop.bat
-xfc E:\opt\xfc_eval_java-5_4_0\bin\fo2rtf.bat
-jhindexer E:\opt\javahelp\javahelp\bin\jhindexer.bat
-hhc "C:\Program Files\HTML Help Workshop\hhc.exe"
Remember
Remember
  • Relative filenames found in this file are relative to the current working directory, and not to the ditac.options options file. Therefore it is recommended to always specify absolute filenames.
  • No comments (e.g. lines starting with '#') are allowed in ditac.options. Options must be separated by whitespace.
  • In the above example, FOP is declared after XEP. This implies that it is FOP and not XEP, which will be used by ditac to generate PDF and PostScript®.
  • An XSL-FO processor tend to consume a lot of memory. If the DITA conversion fails with an out-of-memory error, you need to edit the xep (xep.bat), fop (fop.bat), fo2xxx (fo2xxx.bat) scripts in order to increase the maximum amount of memory that the Java™ runtime may allocate. This is done by using the -Xmx option of the Java™ command-line. Example: "java ... -Xmx512m ...".
  • Starting from Java™ 1.6.0_23, converting XML documents to PDF using RenderX XEP randomly fails with false XSL-FO errors (e.g. attribute "space-before" may not be empty). This problem seems specific to the 64-bit runtime.
    The workarounds for the above bug ("renderx #22766") are:
    • Use a 32-bit Java™ runtime.
    • OR Use a 64-bit Java™ runtime older than 1.6.0_23.
    • OR Specify option -valid in the xep command-line. Note that this workaround is automatically used when you specify which RenderX XEP executable to use by the means of the -xep command-line option.

What is a plug-in?

A plug-in is simply a subdirectory of ditac_install_dir/plugin/. For example, ditac_install_dir/plugin/MyPlugin/.
This subdirectory may contain an XML catalog file Opens in new window. This XML catalog file must be named catalog.xml. In the case of a DITA specialization, catalog.xml points to local copies of customized DTDs. Example: ditac_install_dir/plugin/MyPlugin/catalog.xml:
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"
         prefer="public">
  <public publicId="-//OASIS//DTD DITA Concept//EN"
          uri="dtd/concept.dtd"/>
  ...
</catalog>
This subdirectory may contain an xsl/ subdirectory organized exactly like ditac_install_dir/xsl/. That is, this xsl/ subdirectory may contain one or more of the following XSLT stylesheets:
XSLT stylesheet Description
xsl/fo/fo.xsl Used to generate an intermediate XSL-FO file. After that, the XSL-FO file is converted to PDF , PostScript , RTF , WordprocessingML , Office Open XML (.docx) or OpenOffice/LibreOffice (.odt) by the means of an XSL-FO processor.
xsl/xhtml/xhtml.xsl Used to generate XHTML 1.0 pages.
xsl/xhtml/xhtml1_1.xsl Used to generate XHTML 1.1 pages.
xsl/xhtml/html.xsl Used to generate HTML 4.01 pages.
xsl/xhtml/xhtml5.xsl Used to generate XHTML 5 pages.
xsl/webhelp/webhelp.xsl Used to generate Web Help containing XHTML 1 pages, which are then compiled using XMLmind Web Help Compiler Opens in new window.
xsl/webhelp/webhelp5.xsl Used to generate Web Help containing XHTML 5 pages, which are then compiled using XMLmind Web Help Compiler Opens in new window.
xsl/htmlhelp/htmlhelp.xsl Used to generate HTML Help files, which are then compiled using hhc.exe.
xsl/eclipsehelp/eclipsehelp.xsl Used to generate Eclipse Help files.
xsl/javahelp/javahelp.xsl Used to generate Java™ Help files, which are then archived in a .jar file.
xsl/epub/epub.xsl Used to generate EPUB 2 files, which are then archived in a .epub file (Zip archive having a .epub extension).
xsl/epub/epub3.xsl Used to generate EPUB 3 files, which are then archived in a .epub file (Zip archive having a .epub extension).
When ditac is passed command-line option -plugin plugin_name, it will use the DTDs/schemas and the XSLT stylesheets found in the plug-in subdirectory having specified name preferably to those found in ditac_install_dir/schema/ and in ditac_install_dir/xsl/.
Tip
Tip
If you don't want your plug-ins to reside inside ditac_install_dir/plugin/, you may specify an alternate parent directory by the means of the DITAC_PLUGIN_DIR environment variable. Example:
  • On Windows:
    C:\>set DITAC_PLUGIN_DIR=C:\Users\john\ditac_plugins
  • On Unix:
    $ export DITAC_PLUGIN_DIR=/home/john/ditac_plugins

 (1) Not counting <topicref>s contained in <frontmatter> and <backmatter>.