243 lines
No EOL
22 KiB
HTML
243 lines
No EOL
22 KiB
HTML
<!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="generator" content="DITA-OT"><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="keywords" content="macOS, command, dita, Linux, Windows, command, using"><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.6</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="ol steps"><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 syntax-bash"><code><span class="ph filepath"><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"><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__d1183e290">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__d1183e385">
|
||
<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">
|
||
|
||
<p class="p">Specifies filter file(s) used to include, exclude, or flag content. 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">As of DITA-OT 3.6, the <span class="keyword parmname">--filter</span> option can also be passed multiple times:</p>
|
||
<p class="p"><code class="ph codeph">--filter=filter1.ditaval --filter=filter2.ditaval --filter=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> <var class="keyword varname">plug-in-zip</var> <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.</dd>
|
||
<dd class="dd pd ddexpand">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.</dd>
|
||
<dd class="dd pd ddexpand">Parameters not implemented by the specified transformation type or referenced in a
|
||
<span class="ph filepath">.properties</span> file are ignored. <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.</dd>
|
||
<dd class="dd pd ddexpand">Build parameters specified on the command line override those set in the <span class="ph filepath">.properties</span>
|
||
file.</dd>
|
||
|
||
|
||
<dt class="dt pt dlterm">
|
||
<span class="keyword parmname">--repeat</span>=<var class="keyword varname">N</var>
|
||
</dt>
|
||
<dd class="dd pd">Repeat the transformation <var class="keyword varname">N</var> number of times.</dd>
|
||
<dd class="dd pd ddexpand">This option can be used by plug-in developers to measure performance. To run a conversion five times, for
|
||
example, use <span class="keyword parmname">--repeat</span>=<span class="keyword option">5</span>. The duration of each execution will appear in
|
||
the console when the final transformation is complete.
|
||
<pre class="pre codeblock syntax-bash multi-platform"><code>$ <span class="keyword cmdname">dita</span> <span class="keyword parmname">--input</span>=<span class="ph filepath">docsrc/samples/sequence.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span> <span class="keyword parmname">--repeat</span>=<span class="keyword option">5</span>
|
||
1 11281ms
|
||
2 4132ms
|
||
3 3690ms
|
||
4 4337ms
|
||
5 3634ms</code></pre>
|
||
</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">Convert partial documentation sets by processing input with additional resources.</dd>
|
||
<dd class="dd pd ddexpand">For example, to process a single topic file with a map that contains key definitions, use a command like
|
||
this:
|
||
<pre class="pre codeblock syntax-bash"><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>
|
||
</dd>
|
||
<dd class="dd pd ddexpand">To convert a chapter map to HTML5 and insert related links from relationship tables in a separate map,
|
||
use:
|
||
<pre class="pre codeblock syntax-bash"><code><span class="keyword cmdname">dita</span> <span class="keyword parmname">--input</span>=<span class="ph filepath">chapter.ditamap</span> <span class="keyword parmname">--resource</span>=<span class="ph filepath">reltables.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">html5</span></code></pre>
|
||
</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>
|
||
</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 syntax-bash multi-platform"><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 subcommands and 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><div class="linklist relinfo"><strong>Related information</strong><br><ul class="linklist"><li class="linklist"><a class="link" href="https://www.oxygenxml.com/events/2015/dita-ot_day.html#Why_startcmd_is_not_your_friend" target="_blank" rel="external noopener" title="The startcmd batch script made it possible for many to easily use DITA-OT, but whether you realize it or not, it's no longer really necessary. I'll briefly explain where it came from, why it was always more of a kludge than a Feature, and how better DITA-OT designs mean it's no longer needed.">Why "startcmd" is not your friend</a></li></ul></div></nav></article></main></body></html> |