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

<task id="migrating-ant-to-dita">
  <title>Migrating Ant builds to use the <cmdname>dita</cmdname> command</title>
  <titlealts>
    <navtitle>Migrating Ant builds</navtitle>
  </titlealts>
  <shortdesc>Although DITA Open Toolkit still supports Ant builds, you might want to switch to use the new
      <cmdname>dita</cmdname> command.</shortdesc>
  <taskbody>
    <context>
      <p>Building output with the <cmdname>dita</cmdname> command is often easier than using Ant. In particular, you can
        use <filepath>.properties</filepath> files to specify sets of DITA-OT parameters for each build.</p>
      <p>You can include the <cmdname>dita</cmdname> command in shell scripts to perform multiple builds.</p>
      <note conref="../resources/conref-task.dita#ID/dita-in-path"/>
    </context>
    <steps>
      <step>
        <cmd>In your Ant build file, identify the properties set in each build target.</cmd>
        <info>
          <note>Some build parameters might be specified as properties of the project as a whole. You can refer to a
            build log to see a list of all properties that were set for the build.</note>
        </info>
      </step>
      <step>
        <cmd>Create a <filepath>.properties</filepath> file for each build and specify the needed build parameters, one
          per line, in the format <codeph>name = value</codeph>.</cmd>
      </step>
      <step>
        <cmd>Use the <cmdname>dita</cmdname> command to perform each build, referencing your
            <filepath>.properties</filepath> with the <parmname>--propertyfile</parmname>=<varname>file</varname>
          option.</cmd>
      </step>
    </steps>
    <example>
      <title>Example: Ant build</title>
      <p>Sample build file: <filepath id="samples-dir"
          ><varname>dita-ot-dir</varname>/docsrc/samples</filepath><filepath>/ant_sample/build-chm-pdf.xml</filepath>
        <codeblock outputclass="normalize-space show-line-numbers show-whitespace"><coderef href="../samples/ant_sample/build-chm-pdf.xml"/></codeblock></p></example>
    <example>
      <title>Example: <filepath>.properties</filepath> files with <cmdname>dita</cmdname> command</title>
      <p>The following <filepath>.properties</filepath> files and <cmdname>dita</cmdname> commands are equivalent to the
        example Ant build.</p>
      <p>Sample <filepath>.properties</filepath> file: <filepath conref="../resources/conref-task.dita#ID/samples-dir"
          /><filepath>/properties/chm.properties</filepath></p>
      <p>
        <codeblock outputclass="normalize-space show-line-numbers show-whitespace"><coderef href="../samples/properties/chm.properties"/></codeblock></p>
      <p>Sample <filepath>.properties</filepath> file: <filepath conref="../resources/conref-task.dita#ID/samples-dir"
          /><filepath>/properties/pdf.properties</filepath></p>
      <p>
        <codeblock outputclass="normalize-space show-line-numbers show-whitespace"><coderef href="../samples/properties/pdf.properties"/></codeblock></p>
      <p>Run from <filepath conref="../resources/conref-task.dita#ID/samples-dir"/>:</p>
      <codeblock><cmdname>dita</cmdname> <parmname>--input</parmname>=<filepath>sequence.ditamap</filepath> <parmname>--format</parmname>=<option>htmlhelp</option> \
     <parmname>--propertyfile</parmname>=<filepath>properties/chm.properties</filepath>
<cmdname>dita</cmdname> <parmname>--input</parmname>=<filepath>taskbook.ditamap</filepath> <parmname>--format</parmname>=<option>pdf</option> \
     <parmname>--propertyfile</parmname>=<filepath>properties/pdf.properties</filepath></codeblock>
    </example>
    <example>
      <title>Example: Call the <cmdname>dita</cmdname> command from an Ant build</title>
      <p>In some cases, you might still want to use an Ant build to implement some pre- or post-processing steps, but
        also want the convenience of using the <cmdname>dita</cmdname> command with <filepath>.properties</filepath>
        files to define the parameters for each build. This can be accomplished with Ant’s <xmlelement>exec</xmlelement>
        task.</p>
      <p>This example uses a <xmlelement>dita-cmd</xmlelement> Ant macro defined in the <filepath
          conref="../resources/conref-task.dita#ID/samples-dir"/><filepath>/ant_sample/dita-cmd.xml</filepath> file:</p>
      <p>
        <codeblock outputclass="normalize-space show-line-numbers show-whitespace"><coderef href="../samples/ant_sample/dita-cmd.xml#line=11,21"/></codeblock></p><commit_msg>Clarify advantage of using dita command vs. Ant<commit_after><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA General Task//EN" "generalTask.dtd">
<!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->

<task id="migrating-ant-to-dita">
  <title>Migrating Ant builds to use the <cmdname>dita</cmdname> command</title>
  <titlealts>
    <navtitle>Migrating Ant builds</navtitle>
  </titlealts>
  <shortdesc>Although DITA Open Toolkit still supports Ant builds, switching to the <cmdname>dita</cmdname> command
    offers a simpler command interface, sets all required environment variables and allows you to run DITA-OT without
    setting up anything beforehand.</shortdesc>
  <taskbody>
    <context>
      <p>Building output with the <cmdname>dita</cmdname> command is often easier than using Ant. In particular, you can
        use <filepath>.properties</filepath> files to specify sets of DITA-OT parameters for each build.</p>
      <p>You can include the <cmdname>dita</cmdname> command in shell scripts to perform multiple builds.</p>
      <note conref="../resources/conref-task.dita#ID/dita-in-path"/>
    </context>
    <steps>
      <step>
        <cmd>In your Ant build file, identify the properties set in each build target.</cmd>
        <info>
          <note>Some build parameters might be specified as properties of the project as a whole. You can refer to a
            build log to see a list of all properties that were set for the build.</note>
        </info>
      </step>
      <step>
        <cmd>Create a <filepath>.properties</filepath> file for each build and specify the needed build parameters, one
          per line, in the format <codeph>name = value</codeph>.</cmd>
      </step>
      <step>
        <cmd>Use the <cmdname>dita</cmdname> command to perform each build, referencing your
            <filepath>.properties</filepath> with the <parmname>--propertyfile</parmname>=<varname>file</varname>
          option.</cmd>
      </step>
    </steps>
    <example>
      <title>Example: Ant build</title>
      <p>Prior to DITA-OT 2.0, an Ant build like this was typically used to define the properties for each target.</p>
      <p>Sample build file: <filepath id="samples-dir"
          ><varname>dita-ot-dir</varname>/docsrc/samples</filepath><filepath>/ant_sample/build-chm-pdf.xml</filepath>
        <codeblock outputclass="normalize-space show-line-numbers show-whitespace"><coderef href="../samples/ant_sample/build-chm-pdf.xml"/></codeblock></p></example>
    <example>
      <title>Example: <filepath>.properties</filepath> files with <cmdname>dita</cmdname> command</title>
      <p>The following <filepath>.properties</filepath> files and <cmdname>dita</cmdname> commands are equivalent to the
        example Ant build.</p>
      <p>Sample <filepath>.properties</filepath> file: <filepath conref="../resources/conref-task.dita#ID/samples-dir"
          /><filepath>/properties/chm.properties</filepath></p>
      <p>
        <codeblock outputclass="normalize-space show-line-numbers show-whitespace"><coderef href="../samples/properties/chm.properties"/></codeblock></p>
      <p>Sample <filepath>.properties</filepath> file: <filepath conref="../resources/conref-task.dita#ID/samples-dir"
          /><filepath>/properties/pdf.properties</filepath></p>
      <p>
        <codeblock outputclass="normalize-space show-line-numbers show-whitespace"><coderef href="../samples/properties/pdf.properties"/></codeblock></p>
      <p>Run from <filepath conref="../resources/conref-task.dita#ID/samples-dir"/>:</p>
      <codeblock><cmdname>dita</cmdname> <parmname>--input</parmname>=<filepath>sequence.ditamap</filepath> <parmname>--format</parmname>=<option>htmlhelp</option> \
     <parmname>--propertyfile</parmname>=<filepath>properties/chm.properties</filepath>
<cmdname>dita</cmdname> <parmname>--input</parmname>=<filepath>taskbook.ditamap</filepath> <parmname>--format</parmname>=<option>pdf</option> \
     <parmname>--propertyfile</parmname>=<filepath>properties/pdf.properties</filepath></codeblock>
    </example>
    <example>
      <title>Example: Call the <cmdname>dita</cmdname> command from an Ant build</title>
      <p>In some cases, you might still want to use an Ant build to implement some pre- or post-processing steps, but
        also want the convenience of using the <cmdname>dita</cmdname> command with <filepath>.properties</filepath>
        files to define the parameters for each build. This can be accomplished with Ant’s <xmlelement>exec</xmlelement>
        task.</p>
      <p>This example uses a <xmlelement>dita-cmd</xmlelement> Ant macro defined in the <filepath
          conref="../resources/conref-task.dita#ID/samples-dir"/><filepath>/ant_sample/dita-cmd.xml</filepath> file:</p>
      <p>
        <codeblock outputclass="normalize-space show-line-numbers show-whitespace"><coderef href="../samples/ant_sample/dita-cmd.xml#line=11,21"/></codeblock></p>
{'fraction_non_alphanumeric': 0.14284254623480128, 'fraction_numerical': 0.0016348217022580974, 'mean_word_length': 3.6698473282442747, 'pattern_counts': {'":': 0, '<': 347, '<?xml version=': 2, '>': 347, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 18}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3083969', 'n_tokens_mistral': 3012, 'n_tokens_neox': 2959, 'n_words': 742}