bn
/
se


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225
							<!DOCTYPE html
  SYSTEM "about:legacy-compat">
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="UTF-8"><meta name="copyright" content="(C) Copyright 2020"><meta name="DC.rights.owner" content="(C) Copyright 2020"><meta name="DC.type" content="task"><meta name="description" content="You can generate output using the dita command-line tool. Build parameters can be specified on the command line or with .properties files."><meta name="DC.subject" content="macOS, command, dita, Linux, Windows, command, using"><meta name="keywords" content="macOS, command, dita, Linux, Windows, command, using"><meta name="DC.relation" scheme="URI" content="../topics/building-output.html"><meta name="DC.relation" scheme="URI" content="../topics/using-dita-properties-file.html"><meta name="DC.relation" scheme="URI" content="../topics/migrating-ant-to-dita.html"><meta name="DC.relation" scheme="URI" content="../topics/using-project-files.html"><meta name="DC.relation" scheme="URI" content="../parameters/dita-command-arguments.html"><meta name="DC.relation" scheme="URI" content="../topics/dita-command-help.html"><meta name="DC.relation" scheme="URI" content="../parameters/parameters_intro.html"><meta name="DC.relation" scheme="URI" content="../parameters/internal-ant-properties.html"><meta name="DC.format" content="HTML5"><meta name="DC.identifier" content="using-command-line-tool"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Building output using the dita command</title></head><body id="using-command-line-tool"><header role="banner"><div class="header">
  <p>DITA Open Toolkit</p>
  <hr>
</div></header><nav role="toc"><ul><li><a href="../index.html">DITA Open Toolkit 3.5</a></li><li><a href="../release-notes/index.html">Release Notes</a></li><li><a href="../topics/installing-client.html">Installing DITA-OT</a></li><li><a href="../topics/building-output.html">Building output</a><ul><li class="active"><a href="../topics/build-using-dita-command.html">Using the dita command</a><ul><li><a href="../topics/using-dita-properties-file.html">Using a properties file</a></li><li><a href="../topics/migrating-ant-to-dita.html">Migrating Ant builds</a></li><li><a href="../topics/using-project-files.html">Using a project file</a></li></ul></li><li><a href="../topics/using-docker-images.html">Using Docker images</a></li><li><a href="../topics/publishing-with-ant.html">Using Ant</a></li><li><a href="../reference/java-api.html">Using the Java API</a></li></ul></li><li><a href="../topics/input-formats.html">Authoring formats</a></li><li><a href="../topics/output-formats.html">Output formats</a></li><li><a href="../parameters/index.html">Parameters</a></li><li><a href="../topics/html-customization.html">Customizing HTML</a></li><li><a href="../topics/pdf-customization.html">Customizing PDF</a></li><li><a href="../topics/adding-plugins.html">Adding plug-ins</a></li><li><a href="../topics/custom-plugins.html">Creating plug-ins</a></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a></li><li><a href="../reference/index.html">Reference</a></li><li><a href="../topics/dita-and-dita-ot-resources.html">Resources</a></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
  <h1 class="title topictitle1" id="ariaid-title1">Building output using the <span class="keyword cmdname">dita</span> command</h1>
  
  
  <div class="body taskbody"><p class="shortdesc">You can generate output using the <span class="keyword cmdname">dita</span> command-line tool. Build parameters can be
    specified on the command line or with <span class="ph filepath">.properties</span> files.</p>
    
    <section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><div class="li step p">
        <span class="ph cmd">At the command-line prompt, enter the following command:</span>
        <div class="itemgroup info"><pre class="pre codeblock"><code><span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/bin/<span class="keyword cmdname">dita</span></span> <span class="keyword parmname">--input</span>=<var class="keyword varname">input-file</var> <span class="keyword parmname">--format</span>=<var class="keyword varname">format</var> <span class="ph">[<var class="keyword varname">options</var>]</span></code></pre>
          <p class="p">where:</p>
          <ul class="ul">
            
            <li class="li"><span class="ph filepath"><var class="keyword varname">dita-ot-dir</var></span> is the DITA-OT installation directory.</li><li class="li"><var class="keyword varname">input-file</var> is the DITA map or DITA file that you want to
              process.</li>
            <li class="li">
              <p class="p">
                <var class="keyword varname">format</var> is the output format (transformation type). This argument corresponds to the
                common parameter <span class="keyword parmname">transtype</span>. Use the same values as for the
                  <span class="keyword parmname">transtype</span> build parameter, for example <span class="keyword option">html5</span> or
                  <span class="keyword option">pdf</span>. </p>
              <div class="p" id="using-command-line-tool__d652e292">You can create plug-ins to add new output formats; by default, the following values are
                available:
                
                <ul class="ul">
                  <li class="li"><span class="keyword option">dita</span></li>
                  <li class="li"><span class="keyword option">eclipsehelp</span></li>
                  <li class="li"><span class="keyword option">html5</span></li>
                  <li class="li"><span class="keyword option">htmlhelp</span></li>
                  <li class="li"><span class="keyword option">markdown</span>, <span class="keyword option">markdown_gitbook</span>, and
                    <span class="keyword option">markdown_github</span></li>
                  <li class="li"><span class="keyword option">pdf</span></li>
                  <li class="li"><span class="keyword option">xhtml</span></li>
                </ul>
                <div class="note tip note_tip"><span class="note__title">Tip:</span> See
                  <a class="xref" href="output-formats.html" title="DITA Open Toolkit ships with several core transformations that convert DITA content to different output formats. Additional formats are available from the plug-in registry at dita-ot.org/plugins.">DITA-OT transformations (output formats)</a> for sample command line syntax and more information on each
                  transformation. </div>
              </div>
            </li>
            <li class="li">[<var class="keyword varname">options</var>] include the following optional build parameters:
              <dl class="dl parml">
        
          <dt class="dt pt dlterm">
            <span class="keyword parmname">--debug</span></dt>
          <dt class="dt pt dlterm">
            <span class="keyword parmname">-d</span>
          </dt>
          <dd class="dd pd">Debug logging prints considerably more additional information. The debug log includes all information from
            the verbose log, plus details on Java classes, additional Ant properties and overrides, preprocessing
            filters, parameters, and stages, and the complete build sequence. Debug logging requires additional
            resources and can slow down the build process, so it should only be enabled when further details are
            required to diagnose problems.</dd>
        
        
          <dt class="dt pt dlterm">
            <span class="keyword parmname">--output</span>=<var class="keyword varname">dir</var></dt>
          <dt class="dt pt dlterm">
            <span class="keyword parmname">-o</span>
            <var class="keyword varname">dir</var>
          </dt>
          <dd class="dd pd" id="using-command-line-tool__d652e387">
            <p class="p">Specifies the path of the output directory; the path can be absolute or relative to the current
              directory.</p>
            <p class="p">This argument corresponds to the common parameter <span class="keyword parmname">output.dir</span>. By default, the output
              is written to the <span class="ph filepath">out</span> subdirectory of the current directory.</p>
          </dd>
        
        
          <dt class="dt pt dlterm">
            <span class="keyword parmname">--filter</span>=<var class="keyword varname">files</var>
          </dt>
          <dd class="dd pd">Specifies filter file(s) used to include, exclude, or flag content. </dd>
          <dd class="dd pd ddexpand">
            <p class="p">This argument corresponds to the common parameter <span class="keyword parmname">args.filter</span>. Relative paths are
              resolved against the current directory and internally converted to absolute paths.</p>
            <div class="note note note_note"><span class="note__title">Note:</span> 
              <p class="p">To specify multiple filter files, use the system path separator character to delimit individual file
                paths (semicolon ‘<code class="ph codeph">;</code>’ on Windows, and colon ‘<code class="ph codeph">:</code>’ on macOS and Linux) and
                wrap the value in quotes:</p>
              <p class="p"><code class="ph codeph">--filter="filter1.ditaval;filter2.ditaval;filter3.ditaval"</code></p>
              <p class="p">DITAVAL files are evaluated in the order specified, so conditions specified in the first file take
                precedence over matching conditions specified in later files, just as conditions at the start of a
                DITAVAL document take precedence over matching conditions later in the same document.</p>
            </div>
          </dd>
        
        
          <dt class="dt pt dlterm">
            <span class="keyword parmname">--force</span>
          </dt>
          <dd class="dd pd">Force-install an existing plug-in.</dd>
          <dd class="dd pd ddexpand">Passed as an additional option to the installation subcommand: <span class="keyword cmdname">dita
              install</span>&nbsp;<var class="keyword varname">plug-in-zip</var>&nbsp;<span class="keyword parmname">--force</span></dd>
        
        
          <dt class="dt pt dlterm">
            <span class="keyword parmname">--help</span></dt>
          <dt class="dt pt dlterm">
            <span class="keyword parmname">-h</span>
          </dt>
          <dd class="dd pd">Print a list of available arguments, options, and subcommands.</dd>
        
        
          <dt class="dt pt dlterm">
            <span class="keyword parmname">--logfile</span>=<var class="keyword varname">file</var></dt>
          <dt class="dt pt dlterm">
            <span class="keyword parmname">-l</span>
            <var class="keyword varname">file</var>
          </dt>
          <dd class="dd pd">Write logging messages to a file.</dd>
        
        
          <dt class="dt pt dlterm">
            <span class="keyword parmname">--parameter</span>=<var class="keyword varname">value</var></dt>
          <dt class="dt pt dlterm">
            <span class="keyword parmname">-D</span><var class="keyword varname">parameter</var>=<var class="keyword varname">value</var>
          </dt>
          <dd class="dd pd">Specify a value for a DITA-OT or Ant build parameter.
            <p class="p">The GNU-style <span class="keyword parmname">--parameter</span>=<var class="keyword varname">value</var> form is only available for
              parameters that are configured in the plug-in configuration file; the Java-style <span class="keyword parmname">-D</span>
              form can also be used to specify additional non-configured parameters or set system properties.</p>
            <p class="p">Parameters not implemented by the specified transformation type or referenced in a
                <span class="ph filepath">.properties</span> file are ignored.</p>
            <div class="note tip note_tip"><span class="note__title">Tip:</span> If you are building in different environments where the location of the input
        files is not consistent, set <span class="keyword option">args.input.dir</span> with the <span class="keyword cmdname">dita</span> command and
        reference its value with <code class="ph codeph">${args.input.dir}</code> in your <span class="ph filepath">.properties</span> file.
        
        
      </div></dd>
        
        
          <dt class="dt pt dlterm">
            <span class="keyword parmname">--propertyfile</span>=<var class="keyword varname">file</var>
          </dt>
          <dd class="dd pd">Use build parameters defined in the referenced <span class="ph filepath">.properties</span> file.
            <p class="p">Build parameters specified on the command line override those set in the <span class="ph filepath">.properties</span>
              file.</p></dd>
        
        
          <dt class="dt pt dlterm">
            <span class="keyword parmname">--resource</span>=<var class="keyword varname">file</var>
          </dt>
          <dt class="dt pt dlterm">
            <span class="keyword parmname">-r</span>
            <var class="keyword varname">file</var>
          </dt>
          <dd class="dd pd">Process input with additional resources.
            <div class="p">For example, to process a single topic file with a map that contains key definitions, use a command like
              this:
              <pre class="pre codeblock"><code><span class="keyword cmdname">dita</span> <span class="keyword parmname">--input</span>=<span class="ph filepath">topic.dita</span> <span class="keyword parmname">--resource</span>=<span class="ph filepath">keys.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span></code></pre>
            </div></dd>
        
        
          <dt class="dt pt dlterm">
            <span class="keyword parmname">--temp</span>=<var class="keyword varname">dir</var></dt>
          <dt class="dt pt dlterm">
            <span class="keyword parmname">-t</span>
            <var class="keyword varname">dir</var>
          </dt>
          <dd class="dd pd">Specifies the location of the temporary directory.</dd>
          <dd class="dd pd ddexpand">This argument corresponds to the common parameter <span class="keyword parmname">dita.temp.dir</span>.</dd>
        
        
          <dt class="dt pt dlterm">
            <span class="keyword parmname">--verbose</span></dt>
          <dt class="dt pt dlterm">
            <span class="keyword parmname">-v</span>
          </dt>
          <dd class="dd pd">Verbose logging prints additional information to the console, including directory settings, effective
            values for Ant properties, input/output files, and informational messages to assist in troubleshooting.</dd>
        
      </dl></li>
          </ul></div>
        <div class="itemgroup stepresult">
          <p class="p">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 <span class="ph filepath">out</span> subdirectory of the current
            directory).</p>
          <div class="note tip note_tip" id="using-command-line-tool__d652e711"><span class="note__title">Tip:</span> Add the absolute path for <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var></span><span class="ph filepath">/bin</span> to the <var class="keyword varname">PATH</var> environment variable to run the
              <span class="keyword cmdname">dita</span> command from any location on the file system without typing the path.
            
          </div>
        </div>
      </div></section>
    
    <section class="example"><div class="tasklabel"><h2 class="sectiontitle tasklabel">Example</h2></div>
      <p class="p">For example, from <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span>, run:</p>
      <div class="p">
        <pre class="pre codeblock"><code><span class="keyword cmdname">dita</span> <span class="keyword parmname">--input</span>=<span class="ph filepath">sequence.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span> \
     <span class="keyword parmname">--output</span>=<span class="ph filepath">output/sequence</span> \
     <span class="keyword parmname">--args.input.dir</span>=<span class="ph filepath"><var class="keyword varname">/absolute/path/to/dita-ot-dir</var>/docsrc/samples</span> \
     <span class="keyword parmname">--propertyfile</span>=<span class="ph filepath">properties/sequence-html5.properties</span></code></pre>
      </div>
      <p class="p">This builds <span class="ph filepath">sequence.ditamap</span> to HTML5 output in <span class="ph filepath">output/sequence</span> using
        the following additional parameters specified in the <span class="ph filepath">properties/sequence-html5.properties</span>
        file:</p>
      <div class="p">
        <pre class="pre codeblock language-properties normalize-space show-line-numbers show-whitespace"><code># Directory that contains the custom .css file:
args.cssroot = ${args.input.dir}/css/

# Custom .css file used to style output:
args.css = style.css

# Copy the custom .css file to the output directory:
args.copycss = yes

# Location of the copied .css file relative to the output:
args.csspath = branding

# Generate a full navigation TOC in topic pages:
nav-toc = full</code></pre>
      </div>
      
    </section>
    <section class="section postreq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">What to do next</h2></div>
      
      <p class="p">Usually, you will want to specify a set of reusable build parameters in a
          <span class="ph filepath">.properties</span> file.</p>
    </section>
  </div>
<nav role="navigation" class="related-links"><ul class="ullinks"><li class="link ulchildlink"><strong><a href="../topics/using-dita-properties-file.html">Setting build parameters with .properties files</a></strong><br>Usually, DITA builds require setting a number of parameters that do not change frequently. You can     reference a set of build parameters defined in a <span class="ph filepath">.properties</span> file when building output with the       <span class="keyword cmdname">dita</span> command. If needed, you can override any parameter by specifying it explicitly as an     argument to the <span class="keyword cmdname">dita</span> command.</li><li class="link ulchildlink"><strong><a href="../topics/migrating-ant-to-dita.html">Migrating Ant builds to use the dita command</a></strong><br>Although DITA Open Toolkit still supports Ant builds, switching to the <span class="keyword cmdname">dita</span> command     offers a simpler command interface, sets all required environment variables and allows you to run DITA-OT without     setting up anything beforehand.</li><li class="link ulchildlink"><strong><a href="../topics/using-project-files.html">Publishing with project files</a></strong><br><span class="ph">DITA-OT 3.4 introduces new project files to define publication projects with       multiple deliverables. Projects specify a context, output folder, and publication for each deliverable. A       re-usable context groups source files and filters, and a publication defines an output format with transformation       parameters. You can pass a project file to the <span class="keyword cmdname">dita</span> command to publish multiple deliverables at       once.</span></li></ul><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/building-output.html" title="You can use the dita command-line tool, Ant, or the Java API to transform DITA content to the various output formats that DITA Open Toolkit supports.">Building output</a></div></div><div class="linklist reltasks"><strong>Related tasks</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../topics/dita-command-help.html" title="You can access a list of supported parameters for the dita command by passing the --help option on the command line.">Accessing help for the dita command</a></li></ul></div><div class="linklist relref"><strong>Related reference</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="../parameters/dita-command-arguments.html" title="The dita command takes mandatory arguments to process DITA content. Subcommands can be used to manage plug-ins, or print information about the current configuration. A series of options are available to modify the command behavior or specify additional configuration parameters.">Arguments and options for the dita command</a></li><li class="linklist"><a class="link" href="../parameters/parameters_intro.html" title="Certain parameters apply to all DITA-OT transformations. Other parameters are common to the HTML-based transformations. Some parameters apply only to specific transformation types. These parameters can be passed as options to the dita command using the --parameter=value syntax or included in build scripts as Ant properties.">DITA-OT parameters</a></li><li class="linklist"><a class="link" href="../parameters/internal-ant-properties.html" title="Reference list of Ant properties used by DITA-OT internally.">Internal Ant properties</a></li></ul></div></nav></article></main></body></html>