se/SE/stuff/dita-ot-3.3.3/docsrc/resources/conref-task.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->

<task id="ID">
  <title>Conref file for tasks</title>
  <taskbody>
    <context>
      <p id="semver-info">DITA-OT releases follow
        <xref keyref="semver"/> guidelines. Version numbers use the
            <codeph><varname>major</varname>.<varname>minor</varname>.<varname>patch</varname></codeph> syntax, where
          <varname>major</varname> versions may include incompatible API changes, <varname>minor</varname> versions add
        functionality in a backwards-compatible manner and <varname>patch</varname> versions are maintenance releases
        that include backwards-compatible bug fixes.</p>
      <p id="semver-plugins">Custom plug-ins developed for a previous <varname>major</varname> version may require
        changes to work correctly with recent toolkit versions. Most plug-ins should be compatible with subsequent
          <varname>minor</varname> and <varname>patch</varname> versions of the <varname>major</varname> release for
        which they were originally developed.</p>
      <dl>
        <dlentry>
          <dt>Standard Path / Directory Names</dt>
          <dd><filepath id="ot-dir"><varname>dita-ot-dir</varname></filepath></dd>
          <dd><filepath id="dita-cmd"><varname>dita-ot-dir</varname>/bin/<cmdname>dita</cmdname></filepath></dd>
          <dd><filepath id="samples-dir"><varname>dita-ot-dir</varname>/docsrc/samples</filepath></dd>
        </dlentry>
        <dlentry>
          <dt>Plug-In Info</dt>
          <dd>
            <ul>
              <li id="plug-in-id"><filepath><varname>plug-in-id</varname></filepath> is the unique ID of the plug-in, as
                defined in the plug-in’s configuration file (<filepath>plugin.xml</filepath>).</li>
              <li id="plug-in-zip"><filepath><varname>plug-in-zip</varname></filepath> is the
                  <varname>filename</varname> or <varname>URL</varname> of the plug-in’s distribution ZIP file
                (optional).</li>
              <li><ph id="plugin-integrate-all">If no <varname>filename</varname> or <varname>URL</varname> argument is
                  provided, the installation process reloads the current set of plug-ins from the
                    <filepath>plugins</filepath> 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
                <filepath>plugins</filepath> directory. Any plug-ins added or removed in the process will be listed by
                their plug-in ID.</ph></li>
              <li><note id="plugin-remove-subdir" type="attention">The <parmname>--uninstall</parmname> option also
                  removes the corresponding subdirectory from the <filepath>plugins</filepath>
                folder.<indexterm>uninstalling</indexterm></note></li>
            </ul>
          </dd>
        </dlentry>
      </dl>
    </context>
    <steps>
      <step>
        <cmd>
          <!-- Used in installation topic & Release Notes -->
          <ph id="download-ot">Download the <filepath>dita-ot-<keyword keyref="maintenance-version"/>.zip</filepath>
            package from the project website at <xref keyref="download.dita-ot"/>.</ph>
        </cmd>
      </step>
      <step>
        <cmd id="open-terminal">Open a command prompt or terminal session, and then change to the directory where DITA
          Open Toolkit is installed.</cmd>
        <info>
          <ul id="basic-variables">
            <li id="novice-variables-1"><filepath conref="#ID/ot-dir"/> is the DITA-OT installation directory.</li>
            <li id="novice-variables-2"><varname>input-file</varname> is the DITA map or DITA file that you want to
              process.</li>
            <!-- ↓ excerpt-variables ↓ -->
            <li id="novice-variables-last" audience="novice">
              <p id="common-format-info">
                <varname>format</varname> is the output format (transformation type).
                This argument corresponds to the common parameter
                <parmname>transtype</parmname>.
                Use the same values as for the <parmname>transtype</parmname> build
                parameter, for example <option>html5</option> or <option>pdf</option>.
              </p>
            </li>
            <!-- ↑ end-excerpt ↑ -->
            <li id="expert-variables-last" audience="expert">
              <p conref="#ID/common-format-info"/>
              <p id="transtypes">You can create plug-ins to add new output formats; by default, the following values are
                available:
                <indexterm>transtype<indexterm>list</indexterm></indexterm>
                <ul>
                  <li><option>dita</option></li>
                  <li><option>eclipsehelp</option></li>
                  <li><option>html5</option></li>
                  <li platform="windows"><option>htmlhelp</option></li>
                  <li><option>markdown</option>, <option>markdown_gitbook</option>, and
                    <option>markdown_github</option></li>
                  <li><option>pdf</option></li>
                  <li><option>tocjs</option></li>
                  <li><option>troff</option></li>
                  <li><option>xhtml</option></li>
                </ul>
                <note type="tip">See <xref keyref="output-formats"/> for sample command line syntax and more information
                  on each transformation.
                </note>
              </p>
            </li>
            <li id="options">[<varname>options</varname>] include the following optional build parameters:
              <parml conref="../parameters/dita-command-arguments.dita#dita-command-properties/dita_build_options">
                <plentry>
                  <pt/>
                  <pd/>
                </plentry>
              </parml></li>
          </ul>
        </info>
        <stepresult id="running-ditaot-results">
          <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 <filepath>out</filepath> subdirectory of the current
            directory).</p>
          <note id="dita-in-path" type="tip">Add the absolute path for <filepath conref="#ID/ot-dir"
              /><filepath>/bin</filepath> to the <varname>PATH</varname> environment variable to run the
              <cmdname>dita</cmdname> command from any location on the file system without typing the path.
            <indexterm><cmdname>dita</cmdname> command<indexterm>PATH environment variable</indexterm></indexterm>
          </note>
        </stepresult>
      </step>
      <step>
        <cmd>Extending pre-processing</cmd>
        <info>
          <note id="tip-extend-before-after-preprocessing" type="tip">For maximum compatibility with future versions of
            DITA-OT, most plug-ins should use the extension points that run <b>before</b> or <b>after</b>
            pre-processing.</note>
          <note id="caution-extend-within-preprocessing" type="caution">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 <b>within</b> the preprocessing stage should only be used if absolutely
            necessary.</note>
        </info>
      </step>
    </steps>
    <postreq>
      <note type="tip" id="template-properties">Copy <filepath conref="#ID/samples-dir"
          /><filepath>/properties/template.properties</filepath>; this template describes each of the properties you can
        set.</note>
      <note type="tip" id="pass-input-dir">If you are building in different environments where the location of the input
        files is not consistent, set <option>args.input.dir</option> with the <cmdname>dita</cmdname> command and
        reference its value with <codeph>${args.input.dir}</codeph> in your <filepath>.properties</filepath>
        file.
        <indexterm><cmdname>dita</cmdname>
          command<indexterm><option>args.input.dir</option></indexterm><indexterm>.properties file</indexterm></indexterm>
        <indexterm>args.input.dir</indexterm>
      </note>
    </postreq>
  </taskbody>
</task>