bn
/
se


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137
							<!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 2018"><meta name="DC.rights.owner" content="(C) Copyright 2018"><meta name="DC.Type" content="task"><meta name="description" content="Although Ant builds are still supported in the DITA Open Toolkit, you might want to switch to use the new dita command."><meta name="DC.Relation" scheme="URI" content="../topics/build-using-dita-command.html"><meta name="DC.Format" content="HTML5"><meta name="DC.Identifier" content="migrating-ant-to-dita"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Migrating Ant builds to use the dita command</title></head><body id="migrating-ant-to-dita"><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.0</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/alternative-input-formats.html">Authoring formats</a></li><li><a href="../topics/building-output.html">Building output</a><ul><li><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 class="active"><a href="../topics/migrating-ant-to-dita.html">Migrating Ant builds</a></li></ul></li><li><a href="../topics/publishing-with-ant.html">Using Ant</a></li><li><a href="../topics/output-formats.html">Output formats</a></li></ul></li><li><a href="../parameters/index.html">Setting parameters</a></li><li><a href="../topics/extending-the-ot.html">Customizing DITA-OT</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">Migrating Ant builds to use the <span class="keyword cmdname">dita</span> command</h1>
  
  
  <div class="body taskbody"><p class="shortdesc">Although Ant builds are still supported in the DITA Open Toolkit, you might want to switch to use the new
      <span class="keyword cmdname">dita</span> command.</p>
    <section class="section context"><div class="tasklabel"><h2 class="sectiontitle tasklabel">About this task</h2></div>
      <p class="p">Building output with the <span class="keyword cmdname">dita</span> command is often easier than using Ant. In particular, you can
        use <span class="ph filepath">.properties</span> files to specify sets of DITA-OT parameters for each build.</p>
      <p class="p">You can include the <span class="keyword cmdname">dita</span> command in shell scripts to perform multiple builds.</p>
      <div class="note tip note_tip"><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>
    </section>
    <div class="tasklabel"><h2 class="sectiontitle tasklabel">Procedure</h2></div><ol class="ol steps"><li class="li step stepexpand">
        <span class="ph cmd">In your Ant build file, identify the properties set in each build target.</span>
        <div class="itemgroup info">
          <div class="note note note_note"><span class="note__title">Note:</span> 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.</div>
        </div>
      </li><li class="li step stepexpand">
        <span class="ph cmd">Create a <span class="ph filepath">.properties</span> file for each build and specify the needed build parameters, one
          per line, in the format <code class="ph codeph">name = value</code>.</span>
      </li><li class="li step stepexpand">
        <span class="ph cmd">Use the <span class="keyword cmdname">dita</span> command to perform each build, referencing your
            <span class="ph filepath">.properties</span> with the <span class="keyword parmname">--propertyfile</span>=<var class="keyword varname">file</var>
          option.</span>
      </li></ol>
    <div class="example"><h2 class="title sectiontitle">Example: Ant build</h2>
      
      <div class="p">Sample build file: <span class="ph filepath" id="migrating-ant-to-dita__samples-dir"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span><span class="ph filepath">/ant_sample/build-chm-pdf.xml</span>
        <pre class="pre codeblock"><code>&lt;?xml version="1.0" encoding="UTF-8" ?&gt;

&lt;project name="build-chm-pdf" default="all" basedir="."&gt;

  &lt;property name="dita.dir" location="${basedir}/../../.."/&gt;

  &lt;target name="all" description="build CHM and PDF" depends="chm,pdf"/&gt;

  &lt;target name="chm" description="build CHM"&gt;
    &lt;ant antfile="${dita.dir}/build.xml"&gt;
      &lt;property name="args.input" location="../sequence.ditamap"/&gt;
      &lt;property name="transtype" value="htmlhelp"/&gt;
      &lt;property name="output.dir" location="../out/chm"/&gt;
      &lt;property name="args.gen.task.lbl" value="YES"/&gt;
    &lt;/ant&gt;
  &lt;/target&gt;

  &lt;target name="pdf" description="build PDF"&gt;
    &lt;ant antfile="${dita.dir}/build.xml"&gt;
      &lt;property name="args.input" location="../taskbook.ditamap"/&gt;
      &lt;property name="transtype" value="pdf"/&gt;
      &lt;property name="output.dir" location="../out/pdf"/&gt;
      &lt;property name="args.gen.task.lbl" value="YES"/&gt;
      &lt;property name="args.rellinks" value="nofamily"/&gt;
    &lt;/ant&gt;
  &lt;/target&gt;

&lt;/project&gt;</code></pre></div></div>
    <div class="example"><h2 class="title sectiontitle">Example: <span class="ph filepath">.properties</span> files with <span class="keyword cmdname">dita</span> command</h2>
      
      <p class="p">The following <span class="ph filepath">.properties</span> files and <span class="keyword cmdname">dita</span> commands are equivalent to the
        example Ant build.</p>
      <div class="p">Sample <span class="ph filepath">.properties</span> file: <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span><span class="ph filepath">/properties/chm.properties</span><pre class="pre codeblock"><code>output.dir = out/chm
args.gen.task.lbl = YES
args.breadcrumbs = yes</code></pre></div>
      <div class="p">Sample <span class="ph filepath">.properties</span> file: <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span><span class="ph filepath">/properties/pdf.properties</span><pre class="pre codeblock"><code>output.dir = out/pdf
args.gen.task.lbl = YES
args.rellinks = nofamily</code></pre></div>
      <p class="p">Run from <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span>:</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">htmlhelp</span> \
     <span class="keyword parmname">--propertyfile</span>=<span class="ph filepath">properties/chm.properties</span>
<span class="keyword cmdname">dita</span> <span class="keyword parmname">--input</span>=<span class="ph filepath">taskbook.ditamap</span> <span class="keyword parmname">--format</span>=<span class="keyword option">pdf</span> \
     <span class="keyword parmname">--propertyfile</span>=<span class="ph filepath">properties/pdf.properties</span></code></pre>
    </div>
    <div class="example"><h2 class="title sectiontitle">Example: Call the <span class="keyword cmdname">dita</span> command from an Ant build</h2>
      
      <p class="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 <span class="keyword cmdname">dita</span> command with <span class="ph filepath">.properties</span>
        files to define the parameters for each build. This can be accomplished with Ant's <code class="keyword markupname xmlelement">&lt;exec&gt;</code>
        task.</p>
      <p class="p">This example uses a <code class="keyword markupname xmlelement">&lt;dita-cmd&gt;</code> Ant macro defined in the <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span><span class="ph filepath">/ant_sample/dita-cmd.xml</span> file:</p>
      <pre class="pre codeblock"><code>  &lt;macrodef name="dita-cmd"&gt;
    &lt;attribute name="input"/&gt;
    &lt;attribute name="format"/&gt;
    &lt;attribute name="propertyfile"/&gt;
    &lt;sequential&gt;
      &lt;exec executable="${dita.dir}/bin/dita"&gt;
        &lt;arg line="--input=@{input} --format=@{format} --propertyfile=@{propertyfile}"/&gt;
      &lt;/exec&gt;
    &lt;/sequential&gt;
  &lt;/macrodef&gt;</code></pre>
      <div class="p">You can use this macro in your Ant build to call the <span class="keyword cmdname">dita</span> command and pass the
          <span class="keyword parmname">input</span>, <span class="keyword parmname">format</span> and <span class="keyword parmname">propertyfile</span> parameters as
        follows:
        <pre class="pre codeblock"><code>&lt;dita-cmd input="sample.ditamap" format="pdf" propertyfile="sample.properties"/&gt;</code></pre>
      </div>
      <p class="p">This approach allows you to use Ant builds to perform additional tasks at build time while allowing the
          <span class="keyword cmdname">dita</span> command to set the classpath and ensure that all necessary JAR libraries are
        available.</p>
      <div class="note note note_note"><span class="note__title">Note:</span> The attributes defined in the Ant macro are required and must be supplied each time the task is run. To set
        optional parameters in one build (but not another), use different <span class="ph filepath">.properties</span> files for
        each build.</div>
      <div class="p">Sample build file: <span class="ph filepath"><var class="keyword varname">dita-ot-dir</var>/docsrc/samples</span><span class="ph filepath">/ant_sample/build-chm-pdf-hybrid.xml</span>
        <pre class="pre codeblock"><code>&lt;?xml version="1.0" encoding="UTF-8" ?&gt;

&lt;project name="build-chm-pdf-hybrid" default="all" basedir="."&gt;

  &lt;description&gt;An Ant build that calls the dita command&lt;/description&gt;

  &lt;include file="dita-cmd.xml"/&gt;&lt;!-- defines the &lt;dita-cmd&gt; macro --&gt;

  &lt;target name="all" depends="pre,main,post"/&gt;

  &lt;target name="pre"&gt;
    &lt;description&gt;Preprocessing steps&lt;/description&gt;
  &lt;/target&gt;

  &lt;target name="main"&gt;
    &lt;description&gt;Build the CHM and PDF with the dita command&lt;/description&gt;
    &lt;dita-cmd input="../sequence.ditamap" format="htmlhelp" propertyfile="../properties/chm.properties"/&gt;
    &lt;dita-cmd input="../taskbook.ditamap" format="pdf" propertyfile="../properties/pdf.properties"/&gt;
  &lt;/target&gt;

  &lt;target name="post"&gt;
    &lt;description&gt;Postprocessing steps&lt;/description&gt;
  &lt;/target&gt;

&lt;/project&gt;</code></pre>
      </div>
    </div>
  </div>
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../topics/build-using-dita-command.html" title="You can generate output using the DITA Open Toolkit dita command-line tool. Build parameters can be specified on the command line or with .properties files.">Building output using the dita command</a></div></div></nav></article></main></body></html>