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 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 (possibly converting between image formats if some image converters have been
registered with ditac) 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.
Note that "
-r res" is equivalent to
"
-resourcehandler
com.xmlmind.ditac.convert.ResourceProcessor res".
 |
Remember
Unless option -r,
-resources, -i or
-images (or low-level option -resourcehandler)
are used, resources are not copied nor
converted.
|
|
Remember
When generating
any of the XSL-FO based output formats (PDF, DOCX, ODT, etc),
specifying option -r (or any of its aliases:
-resources, -i, etc) is generally
not useful as these output formats can embed the images referenced
in the source DITA document. However if your DITA document
references audio or video files or if your document embeds MathML
and the XSL-FO processor does not support MathML (e.g.
RenderX RenderX XEP ), then specifying option
-r is really needed.
|
-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>(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 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
-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.
-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
XSL-FO converters last registered with
ditac have priority over first registered
ones.
However, no matter the order of command-line options,
XSL-FO converters registered using low-level option
-foconverter always have priority over those
registered using options -fop,
-xep, -ahf, -xfc,
which in turn always have priority over bundled XSL-FO converters
(such as the Apache
FOP XSL-FO processor contained in
ditac-N_N_N-plus-fop.zip
distributions).
|
-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.
-foconverter FOP pdf \
'/opt/fop/fop -c /home/john/docs/fop.conf -q -r -fo "%I" -pdf "%O"'
|
Remember
XSL-FO converters last registered with
ditac have priority over first registered
ones.
However, no matter the order of command-line options,
XSL-FO converters registered using low-level option
-foconverter always have priority over those
registered using options -fop,
-xep, -ahf, -xfc,
which in turn always have priority over bundled XSL-FO converters
(such as the Apache
FOP XSL-FO processor contained in
ditac-N_N_N-plus-fop.zip
distributions).
|
-hhc exe_file- Specifies the location of
hhc.exe, the HTML Help
compiler.
-imageconverter input_file_extensions
output_file_extensions command- Register external image converter with
ditac
.
Example:
-imageconverter .wmf.emf .svg \
'/opt/inkscape/bin/inkscape --export-type=svg -l -o "%I" "%O"'
|
Remember
Image converters last registered with
ditac have priority over first registered
ones.
Note that image converters registered using option
-imageconverter always have priority over bundled
image converters (such as the stock
javax.imageio.ImageIO based image converter and the
Batik , JEuclid and JLaTeXMath image converters contained in
ditac-N_N_N-plus-fop.zip
distributions).
|
-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?.
-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.
Note that
"
-i images" is equivalent to
"
-resourcehandler com.xmlmind.ditac.convert.ResourceProcessor
images".
-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"'
-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!
|
§ 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
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:
Example:
-v
-xep E:\opt\xep\xep.bat
-fop E:\opt\fop\fop\fop.bat
-xfc E:\opt\xfc\bin\fo2rtf.bat
-hhc "C:\Program Files\HTML Help Workshop\hhc.exe"
|
Remember
|
§ 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 . 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:
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). |
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
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:
|
