Building output using the dita command

You can generate output using the DITA Open Toolkit dita command-line tool. Build parameters can be specified on the command line or with .properties files.

About this task

The DITA-OT client is a command-line tool with no graphical user interface.

Procedure

  1. Open a terminal window by typing the following in the search bar:
    • On OS X and Linux, type Terminal.
    • On Windows, type Command Prompt.
  2. At the command-line prompt, enter the following command: 
    dita-ot-dir/bin/dita -input input-file -format format options

    where:

    • dita-ot-dir is the DITA-OT installation directory.
    • input-file is the DITA map or DITA file that you want to process.
    • format is the output format (transformation type). Use the same values available for the transtype build parameter, for example, html5 or pdf.
    • options include the following optional build parameters:
      -o, -output dir
      Specifies the path of the output directory; the path can be absolute or relative to the current directory. By default, the output is written to the out subdirectory of the current directory.
      -filter file
      Specifies a filter file to be used to include, exclude, or flag content.
      -t, -temp dir
      Specifies the location of the temporary directory.
      -v, -verbose
      Verbose logging.
      -d, -debug
      Debug logging.
      -l, -logfile file
      Write logging messages to a file.
      -Dparameter=value
      Specify a value for a DITA-OT or Ant build parameter.

      Parameters not implemented by the specified transformation type or referenced in a .properties file are ignored.

      Tip: If you are building in different environments where the location of the input files is not consistent, set args.input.dir with the dita command and reference its value with ${args.input.dir} in your .properties file.
      -propertyfile file
      Use build parameters defined in the referenced .properties file.

      Build parameters specified on the command line override those set in the .properties file.

    If processing is successful, nothing is printed in the terminal window. The built output is written to the specified output directory (by default, in the out subdirectory of the current directory).

    Tip: Add the absolute path for dita-ot-dir/bin to the PATH environment variable to run the dita command from any location on the file system without typing the path.

Example

Run from dita-ot-dir/docsrc/samples, the following command generates HTML5 output for the sequence.ditamap file:

dita-ot-dir/bin/dita -input sequence.ditamap -format html5

Example

For example, from dita-ot-dir/docsrc/samples, run:

dita -input sequence.ditamap -format html5 \
     -output output/sequence \
     -Dargs.input.dir=dita-ot-dir/docsrc/samples \
     -propertyfile properties/sequence-html5.properties

This builds sequence.ditamap to HTML5 output in output/sequence using the additional parameters specified in the properties/sequence-html5.properties file:

args.gen.task.lbl = NO
args.cssroot = ${args.input.dir}/css/
args.css = style.css
args.copycss = yes
args.csspath = branding
nav-toc = full
args.xhtml.toc = toc

What to do next

Most builds require you to specify more options than are described in this topic.

Usually, you will want to specify a set of reusable build parameters in a .properties file.