XMLmind DITA Converter Manual

§ Command-line usage

C:\docsrc> ditac -p center "fig table" ..\doc\userguide.htm userguide.ditamap

C:\docsrc> ditac draft1.pdf introduction.dita  quickstart.dita

C:\docsrc> ditac bar\_.html foo.ditamap

§ Commonly used command-line options

-p param_name param_value

-param param_name param_value

Specifies a conversion parameter, generally an XSLT stylesheet parameter. See Chapter 4.

A param_name starting with "load.doc_loader_name." specifies an option which is passed to the alternate document loader called doc_loader_name. For example, -p load.mdita.autolink true turns on the autolink extension in the MDITA loader. See MDITA support.

-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 the reuse of a map designed to output multiple HTML pages in order to generate a PDF file.

For example, "-chunk none" allows the reuse of 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, webhelp, etc.

-f xhtml | xhtml1.1 | html | xhtml5 | html5 | webhelp | webhelp5 | epub | epub3 | htmlhelp | ps | pdf | rtf | odt | wml | docx | fo

-format xhtml | xhtml1.1 | html | xhtml5 | html5 | webhelp | webhelp5 | epub | epub3 | 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.

-attrvalues subject_scheme_map_URL_or_file

Specify an external subject scheme map. The controlled attribute values found in this subject scheme map are prepended to those loaded from the subject scheme maps possibly referenced in the map or bookmap to be converted.

-defaultattrvalues subject_scheme_map_URL_or_file

Same as -attrvalues except that the controlled attribute values found in this subject scheme map will not be used if some controlled attribute values are loaded from the subject scheme maps referenced in the map or bookmap to be converted.

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

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 copies 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 lets the user 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"'

-fopconf configuration_file

Specifies the location of an Apache FOP configuration file . A relative file path is relative to the current working directory. Ignored unless option -fop is also specified.

Remember No matter the order of command-line options, option -foconverter has priority over options -fop, -xep, -ahf, -xfc, which is turn have priority over bundled XSL-FO converters (such as the Apache FOP contained in ditac-N_N_N-plus-fop.zip distributions).

-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"'

-ahfconf configuration_file

Specifies the location of an Antenna House Formatter configuration file . A relative file path is relative to the current working directory. Ignored unless option -ahf is also specified.

-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" -rtf.target=MSWord "%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"'

WARNING XMLmind XSL-FO Converter Evaluation Edition (download page ) generates output containing random duplicate letters. This makes this edition useless for any purpose other than evaluating XMLmind XSL-FO Converter. Of course, this does not happen with XMLmind XSL-FO Converter Professional Edition!

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

-foconverter FOP pdf \
  '/opt/fop/fop -c /home/john/docs/fop.conf -q -r -fo "%I" -pdf "%O"'

Remember No matter the order of command-line options, option -foconverter has priority over options -fop, -xep, -ahf, -xfc, which is turn have priority over bundled XSL-FO converters (such as the Apache FOP contained in ditac-N_N_N-plus-fop.zip distributions).

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

This option is unrelated to attribute value validation validation by the means of subject scheme maps. When the map to be converted (or any of its submaps) references some subject scheme maps then the attribute value validation is automatic and cannot be turned off.

-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

-v -p number all

~/docsrc$ ditac -p center "fig table" ../doc/userguide.htm userguide.ditamap

~/docsrc$ ditac -v -p number all -p center "fig table" \
    ../doc/userguide.htm userguide.ditamap

• $HOME/.ditac/ on Linux.
• $HOME/Library/Application Support/XMLmind/ditac/ on the Mac.
• %APPDATA%\XMLmind\ditac\ on Windows. Example: C:\Users\john\AppData\Roaming\XMLmind\ditac\.

-v
-xep E:\opt\xep\xep.bat
-fop E:\opt\fop-2.9\fop\fop.bat
-xfc E:\opt\xfc_eval_java-6_4_3\bin\fo2rtf.bat
-hhc "C:\Program Files\HTML Help Workshop\hhc.exe"

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?

This subdirectory may contain an XML catalog file . 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>

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 .
xsl/webhelp/webhelp5.xsl	Used to generate Web Help containing XHTML 5 pages, which are then compiled using XMLmind Web Help Compiler .
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/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).

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