300 lines
No EOL
22 KiB
HTML
300 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"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Conref file for tasks</title></head><body id="ID"><header role="banner"><div class="header">
|
||
<p>DITA Open Toolkit</p>
|
||
<hr>
|
||
</div></header><nav role="toc"><ul></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
|
||
<h1 class="title topictitle1" id="ariaid-title1">Conref file for tasks</h1>
|
||
<div class="body taskbody">
|
||
<section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
|
||
<p class="p" id="ID__semver-info">DITA-OT releases follow
|
||
<a class="xref" href="https://semver.org" target="_blank" rel="external noopener">semantic versioning</a> guidelines. Version numbers use the
|
||
<code class="ph codeph"><var class="keyword varname">major</var>.<var class="keyword varname">minor</var>.<var class="keyword varname">patch</var></code> syntax, where
|
||
<var class="keyword varname">major</var> versions may include incompatible API changes, <var class="keyword varname">minor</var> versions add
|
||
functionality in a backwards-compatible manner and <var class="keyword varname">patch</var> versions are maintenance releases
|
||
that include backwards-compatible bug fixes.</p>
|
||
<p class="p" id="ID__semver-plugins">Custom plug-ins developed for a previous <var class="keyword varname">major</var> version may require
|
||
changes to work correctly with recent toolkit versions. Most plug-ins should be compatible with subsequent
|
||
<var class="keyword varname">minor</var> and <var class="keyword varname">patch</var> versions of the <var class="keyword varname">major</var> release for
|
||
which they were originally developed.</p>
|
||
<dl class="dl">
|
||
|
||
<dt class="dt dlterm">Standard Path / Directory Names</dt>
|
||
<dd class="dd"><span class="ph filepath" id="ID__ot-dir"><var class="keyword varname">dita-ot-dir</var></span></dd>
|
||
<dd class="dd ddexpand"><span class="ph filepath" id="ID__dita-cmd"><span class="keyword cmdname">dita</span></span></dd>
|
||
<dd class="dd ddexpand"><span class="ph filepath" id="ID__docsrc-dir"><var class="keyword varname">dita-ot-dir</var>/docsrc</span></dd>
|
||
<dd class="dd ddexpand"><span class="ph filepath" id="ID__samples-dir"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span></dd>
|
||
<dd class="dd ddexpand"><span class="ph filepath" id="ID__samples-absolute"><var class="keyword varname">/absolute/path/to/dita-ot-dir</var>/docsrc/samples</span></dd>
|
||
|
||
|
||
<dt class="dt dlterm">Plug-In Info</dt>
|
||
<dd class="dd">
|
||
<ul class="ul">
|
||
<li class="li" id="ID__plug-in-id"><span class="ph filepath"><var class="keyword varname"><plug-in-id></var></span> is the unique ID of the
|
||
plug-in, as defined in the plug-in’s configuration file (<span class="ph filepath">plugin.xml</span>).</li>
|
||
<li class="li" id="ID__plug-in-zip"><span class="ph filepath"><var class="keyword varname">plug-in-zip</var></span> is the
|
||
<var class="keyword varname">filename</var> or <var class="keyword varname">URL</var> of the plug-in’s distribution ZIP file
|
||
(optional).</li>
|
||
<li class="li" id="ID__plug-in">the optional <span class="ph filepath"><var class="keyword varname"><plug-in></var></span> argument is one of
|
||
the following:
|
||
<ul class="ul">
|
||
<li class="li">the unique <var class="keyword varname">ID</var> of the plug-in as defined in the plug-in registry at
|
||
<a class="xref" href="https://www.dita-ot.org/plugins" target="_blank" rel="external noopener">dita-ot.org/plugins</a> (or a local registry)</li>
|
||
<li class="li">the remote <var class="keyword varname">URL</var> of the plug-in’s distribution ZIP file</li>
|
||
<li class="li">the name of a local ZIP <var class="keyword varname">file</var></li>
|
||
</ul>
|
||
</li>
|
||
<li class="li"><span class="ph" id="ID__plugin-integrate-all">If no <var class="keyword varname">ID</var>, <var class="keyword varname">URL</var>, or
|
||
<var class="keyword varname">file</var> argument is provided, the installation process reloads the current set of
|
||
plug-ins from the <span class="ph filepath">plugins</span> directory (or any custom locations defined via the
|
||
<span class="keyword parmname">pluginsdir</span> property in the <span class="ph filepath">configuration.properties</span> file
|
||
in the <span class="ph filepath">config</span> directory). This approach can be used to add or remove multiple
|
||
plug-ins at once, or any individual plug-ins you have already copied to (or removed from) the plug-in
|
||
directories. Any plug-ins added or removed in the process will be listed by their plug-in
|
||
ID.</span></li>
|
||
<li class="li"><div class="note attention note_attention" id="ID__plugin-remove-subdir"><span class="note__title">Attention:</span> The <span class="keyword cmdname">uninstall</span> subcommand also
|
||
removes the corresponding plug-in directory from the <span class="ph filepath">plugins</span> folder.
|
||
</div></li>
|
||
<li class="li"><div class="note note note_note"><span class="note__title">Note:</span>
|
||
<span class="ph" id="ID__pre-subcommands-2-4-ph">In earlier versions of DITA-OT (2.4–3.4), use the double-hyphen option
|
||
syntax <span class="keyword cmdname">dita</span></span>
|
||
<span class="keyword parmname">--uninstall</span>. <span class="ph" id="ID__pre-subcommands-2-0-ph">In DITA-OT 2.0–2.3, use the
|
||
single-hyphen form: <span class="keyword cmdname">dita</span></span>
|
||
</div></li>
|
||
</ul>
|
||
</dd>
|
||
|
||
</dl>
|
||
</section>
|
||
<section><div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
|
||
<span class="ph cmd">
|
||
|
||
<span class="ph" id="ID__download-ot">Download the <span class="ph filepath">dita-ot-<span class="keyword">3.6</span>.zip</span>
|
||
package from the project website at
|
||
<a class="xref" href="https://www.dita-ot.org/download" target="_blank" rel="external noopener">dita-ot.org/download</a>.</span>
|
||
</span>
|
||
</li><li class="li step stepexpand">
|
||
<span class="ph cmd" id="ID__open-terminal">Open a command prompt or terminal session.</span>
|
||
<div class="itemgroup info">
|
||
<ul class="ul" id="ID__basic-variables">
|
||
<li class="li" id="ID__novice-variables"><var class="keyword varname">input-file</var> is the DITA map or DITA file that you want to
|
||
process.</li>
|
||
|
||
<li class="li" id="ID__novice-variables-last">
|
||
<p class="p" id="ID__common-format-info">
|
||
<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>
|
||
</li>
|
||
|
||
<li class="li" id="ID__expert-variables-last">
|
||
<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="ID__transtypes">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="../topics/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" id="ID__options">[<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="ID__d1175e739">
|
||
<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" id="ID__running-ditaot-results">
|
||
<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>
|
||
</li><li class="li step stepexpand">
|
||
<span class="ph cmd">Extending pre-processing</span>
|
||
<div class="itemgroup info">
|
||
<div class="note tip note_tip" id="ID__tip-extend-before-after-preprocessing"><span class="note__title">Tip:</span> For maximum compatibility with future versions of
|
||
DITA-OT, most plug-ins should use the extension points that run <strong class="ph b">before</strong> or <strong class="ph b">after</strong>
|
||
pre-processing.</div>
|
||
<div class="note caution note_caution" id="ID__caution-extend-within-preprocessing"><span class="note__title">CAUTION:</span> The internal order of preprocessing steps is
|
||
subject to change between versions of DITA-OT. New versions may remove, reorder, combine, or add steps to
|
||
the process, so the extension points <strong class="ph b">within</strong> the preprocessing stage should only be used if absolutely
|
||
necessary.</div>
|
||
</div>
|
||
</li></ol></section>
|
||
<section class="section postreq"><div class="tasklabel"><h2 class="sectiontitle tasklabel">What to do next</h2></div>
|
||
<div class="note tip note_tip" id="ID__template-properties"><span class="note__title">Tip:</span> Copy <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span><span class="ph filepath">/properties/template.properties</span>; this template describes each of the properties you can
|
||
set.</div>
|
||
<div class="note tip note_tip" id="ID__pass-input-dir"><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>
|
||
</section>
|
||
</div>
|
||
</article></main></body></html> |