Building DITA output with Java command line

The DITA Open Toolkit provides a Java command line interface as an alternative for users with little knowledge of Ant. Most parameters available to the Ant builds are also available using the Java command line.

Note: This information is currently being integrated with the parameter information in the Ant Quick Start Guide. Newer information on Java and Ant parameters can be found in that document here: Ant Properties for DITA-OT

Note: The Java command line interface is simply a wrapper around the Ant interface; it takes the simplified parameters as input, converts them to Ant parameters, and then runs an Ant build. This means that in general, applications embedding the toolkit are better off simply calling Ant directly. For individual builds, the additional Java overhead is minimal, but for repeated or server based builds, it the extra memory usage may become more of an issue.

Running a Java based build.

If you are using the "Full Easy Install" package, running the startcmd batch file will set up a build environment for you and put you in the correct directory. If you are not using this method, you must set up all of your tools (Ant, XSLT, FOP, etc) before running the build.

Change into the DITA Open Toolkit installation directory.

On the command line, enter the following command:

java -jar lib/dost.jar /i:samples/sequence.ditamap /outdir:out /transtype:xhtml

This particular example creates a properties file, and then calls Ant using this properties to build the sample sequence.ditamap file to XHTML. The output is placed in the out/ directory. You can add other parameters to this properties file and then run the build directly from Ant; see Table 1 for details on additional parameters.

Note:

In this example, the character slash preceded by a space is the separator for each parameter.
Currently, the parameters /filter, /ftr, /hdr, and /hdf require an absolute path.
The properties file is saved in the ${args.logdir} directory. The following command provides an example using this properties file:
```
ant -f conductor.xml -propertyfile ${args.logdir}/property.temp
```
To see a list of all supported parameters from the Java command line, run the following command with no additional parameters:
```
java -jar lib/dost.jar
```

Supported parameters

The following table lists many supported parameters that you can set with this tool. The equivalent Ant parameter names are specified within braces. To get a full list of parameters, run the following command with no additional options: ava -jar lib/dost.jar

Table 1. Table of supported parameters
Parameter	Description
/basedir:{basedir}	The path of the working directory for transformations, it will be the base of relative paths specified by other parameters. Note: If input is relative, it will be set relative to the current directory. In Ant scripts, the default is that specified in the Ant buildfile. In Java command line, the default is current directory.
/ditadir:{dita.dir}	The absolute path of the toolkit's home directory.
/i:{args.input}	The path and name of the input file. This argument should be in the same upper or lower case with the filename on file system. Note: This parameter must be provided if `dita.input` and `dita.input.dirname` not be provided.
/if:{dita.input}	The name of the input file . Note: This parameter must be provided if `args.input` not be provided. And this parameter must be used together with the `dita.input.dirname` parameter. The result of this combination is equivalent to use only the `args.input` parameter. It is an alternative way to specify the path and name of the input file. DEPRECATED - use `args.input` instead.
/id:{dita.input.dirname}	The input directory which contains the input file. Note: This parameter must be provided if `args.input` not be provided. And this parameter must be used together with the `dita.input` parameter. The result of this combination is equivalent to use only the `args.input` parameter. It is an alternative way to specify the path and name of the input file. DEPRECATED - use `args.input` instead.
/outdir:{output.dir}	The path of the output directory.
/tempdir:{dita.temp.dir}	The directory of the temporary files. The default is 'temp'.
/ditaext:{dita.extname}	The file extension name of the input topic files, for example, '.xml' or '.dita'. The default is '.xml'.
/transtype:{transtype}	The transformation type. Currently, the supported values include xhtml, pdf, javahelp, eclipsehelp, htmlhelp, eclipsecontent, troff, wordrtf and docbook.
/filter:{dita.input.valfile}	The name of the file containing filter/flagging/revision information.
/draft:{args.draft}	Default "hide draft & required-cleanup content" processing parameter ("no"= hide them); "no" and "yes" are valid values; non-"yes" is ignored.
/artlbl:{args.artlbl}	Default "output artwork filenames" processing parameter; "no"and "yes"are valid values; non-"yes" is ignored.
/ftr:{args.ftr}	The name of the file containing XHTML to be placed in the BODY running-footing area.
/hdr:{args.hdr}	The name of the file containing XHTML to be placed in the BODY running-heading area.
/hdf:{args.hdf}	The name of the file containing XHTML to be placed in the HEAD area.
/csspath:{args.csspath}	The path for css reference. Default is no path. Note: If `${args.csspath}` is an URL like path, it should starts with `http://` or `https://`. For example: `http://www.ibm.com/css`. Local absolute paths is not supported for `${args.csspath}`. Use '`/`' as the path separator and don't append separator at last. For example: `css/mycss`.
/css:{args.css}	User specified css file, it can be a local file or remote file from website. Note: If `${args.csspath}` is an URL, the `${args.css}` should be a filepath relative to the URL.
/cssroot:{args.cssroot}	The root directory of user specified css file. Note: If this parameter is set, the `${args.css}` should be a filepath relative to `args.cssroot`.
/copycss:{args.copycss}	The parameter to specify whether copy user specified css files to the directory specified by `{args.outdir}${args.csspath}`. "no" and "yes" are valid values. Default is "no".
/indexshow:{args.indexshow}	The parameter to specify whether each index entry should display within the body of the text itself. Only "no" and "yes" are valid values.
/outext:{args.outext}	The output file extension name for generated xhtml files. Typically, '.html' or '.htm' can be used as the extension name for the generated xhtml files. You can also specify other extension name. The default is '.html'.
/xsl:{args.xsl}	The xsl file to replace the default xsl file. It will replace dita2docbook.xsl in docbook transformation, dita2fo-shell.xsl in pdf transformation, dita2xhtml.xsl in xhtml/eclipsehelp transformation, dita2rtfImpl.xsl in word transformation and dita2html.xsl in javahelp/htmlhelp transformation.
/cleantemp:{clean.temp}	The parameter to specify whether to clean the temp directory before each build. Only "no" and "yes" are valid values. The default is yes.
/foimgext:{args.fo.img.ext}	The extension name of image file in pdf transformation. Only '.jpg', '.gif' are valid value. The default is '.jpg'. Note: Only one extension supported in the same transformation, image files with other extensions will be renamed to the specified extension.
/javahelptoc:{args.javahelp.toc}	The root file name of the output javahelp toc file in javahelp transformation. The default is the name of input ditamap file.
/javahelpmap:{args.javahelp.map}	The root file name of the output javahelp map file in javahelp transformation. The default is the name of input ditamap file.
/eclipsehelptoc:{args.eclipsehelp.toc}	The root file name of the output eclipsehelp toc file in eclipsehelp transformation. The default is the name of input ditamap file.
/eclipsecontenttoc:{args.eclipsecontent.toc}	The root file name of the output Eclipse content provider toc file in eclipsecontent transformation. The default is the name of input ditamap file.
/provider:{args.eclipse.provider}	The provider name of the eclipse help output. The default value is DITA.
/version:{args.eclipse.version}	The version number of the eclipse help output. The default value is 1.0
/xhtmltoc:{args.xhtml.toc}	The root file name of the output xhtml toc file in xhtml transformation. The default is 'index'.
/logdir:{args.logdir}	The directory used to keep generated log files. Default will be output directory. Note: If several transforms running batchly, e.g., ant all: If the user has specified a common logdir for all transformations, it will be used as log directory. If the user hasn't specified a common dir for all transformations: If all transformations have same output directory, the common output direcory will be used as log directory. If there is no same output directory for all transformations, the `basedir` will be used as default log directory.
/ditalocale:{args.dita.locale}	The locale used for sorting indexterms. If no locale specified, the first occurrence of "xml-lang" will be used as default locale; If no "xml-lang" found, "en-us" will be used by default.
/fooutputrellinks:{args.fo.output.rel.links}	The parameter to specify whether output related links in pdf transformation. "yes" and "no" are valid values. Default is "no". Note: Any value that is not "yes" is regarded as "no".
/fouserconfig:{args.fo.userconfig}	The parameter to specify the user configuration file for FOP.
/htmlhelpincludefile:{args.htmlhelp.includefile}	The parameter to specify the file that need to be included by the HTMLHelp output.
/validate:{validate}	The parameter to specify whether the ditamap/dita/xml files to be validated. Only "true" and "false" are valid values. The default is true. Note: It is not recommended to turn off the validation function , which will cause unexpected error during transformation.
/outercontrol:{outer.control}	The parameter to specify how to respond to the overflowing dita/topic files. Only "fail", "warn" and "quiet" are valid values. The default is warn. Note: The detailed introduction: fail: Fail quickly if files are going to be generated/copied outside of that directory warn: Complete if files will be generated/copied outside, but log a warning quiet: Quietly finish with only those files (no warning or error)
/generateouter:{generate.copy.outer}	The parameter to specify how to deal with the overflowing dita/topic files. Only "1", "2" and "3" are valid values. The default is 1. Note: The detailed introduction: 1: Only generate/copy files that fit within the designated output directory. 2: Generate/copy all files, even those that will end up outside of the output directory. 3: the old solution,adjust the input.dir according to the referenced files. (not default option any more but keep this as the option of backward compatibility).
/onlytopicinmap:{onlytopic.in.map}	The parameter to specify whether the referenced dita/topic files which are not referenced by ditamap files should be resolved. Only "true" and "false" are valid values. The default is false.

Enhanced command line help

You can find the version of toolkit and the usage of the command line from the command line help by using the following commands:

          java -jar lib/dost.jar -version
          java -jar lib/dost.jar -h

You can see the brief description of the supported parameters in the command line window when you type a specific command. For example, java -jar lib/dost.jar -h