Part I, Chapter 3. The ditac command-line utility

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. More information in Chapter 2, Section 2.

-f xhtml|xhtml1.1|html|javahelp|htmlhelp|ps|pdf|rtf|odt|wml|docx|fo

-format xhtml|xhtml1.1|html|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.

Note that a "htm" or "html" filename extension implicitly specifies an XHTML 1.0 output format, and not an HTML 4.1 output format. In order to generate HTML 4.1, explicitly specify "-f html".

-i image_path

-images image_path

Copy the image files referenced in the source topics to specified directory . If specified path is relative, it is relative to the output directory.

-imagehandler class_name parameters

Pass the image files referenced in the source topics to an instance ImageHandler having specified Java™ class. String parameters is used to configure the newly created ImageHandler.

For example, "-images graphics" is equivalent to "-imagehandler com.xmlmind.ditac.convert.ImageCopier graphics".

-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⁽¹⁾ 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.

The syntax of spec is:

spec -> same_page [ ',' same_page ]*

same_page -> section [ '+' section ]*

section -> 'toc'|'figurelist'|'tablelist'|'examplelist'|'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.

-lang language_code

Specifies the main language of the document. 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).

-xep executable_file

Specifies the location of the xep shell script (xep.bat on Windows).

-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.

-foconverter processor_name target_format command

Register specified XSL-FO converter with ditac, a lower-level alternative to using -xep, -fop 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.

-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.

-xslt2 format XSLT_stylesheet_URL_or_file

Use the specified custom XSLT stylesheet rather than the stock one to generate specified format. This option is mainly useful to convert documents conforming to a DITA specialization. Example:

-xslt2 xhtml /opt/dita_xsl/custom_xhtml.xsl \
    -xslt2 pdf /opt/dita_xsl/custom_fo.xsl \
    -xslt2 ps /opt/dita_xsl/custom_fo.xsl

Note how this option can be specified several times with different values in the same command-line.

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.
-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 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 2000, XP, Vista, 7.

Example: C:\Documents and Settings\john\Application Data\XMLmind\ditac\ on Windows 2000 and XP. C:\Users\john\AppData\Roaming\XMLmind\ditac\ on Windows Vista and 7.

The ditac.options options file is mainly useful to configure ditac once for all by specifying values for the -fop, -xep, -xfc, -jhindexer, -hhc, -xslt2 options.