Setting Up an Ant Script for Running the Word-to-DITA Transform

How to set up an Ant task to run the Word-to-DITA transform against DOCX files.

You can set up an Ant script to run the transform against a specific Word document. A typical script looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<project name="Single Word Doc to Map and Topics 01" default="transformMyDoc">

  <property file="build.properties"/>
  <property file="${user.home}/.build.properties"/>
  <property file="${user.home}/build.properties"/>
  
  <!-- This property should be set in one of the included files above
       to reflect the location of Toolkit on your machine:
    -->
  <property name="dita-ot-dir" location="c:\DITA-OT1.5"/>
  
  <dirname property="myAntFile.dir" file="${ant.file}"/>
  
  <tstamp/>
  
  <target name="transformMyDoc">
    
    <property name="word.doc" 
      location="${myAntFile.dir}/word2dita_single_doc_to_map_and_topics_01.docx"/>
    
    <basename  property="doc.base.name" file="${word.doc}" suffix=".docx"/>
  
    <ant antfile="${dita-ot-dir}/build.xml" target="dita2word2dita">
      <!-- Set this to the filename of the DOCX file to be transformed: -->
      <property name="args.input" 
        location="${word.doc}"/>
  
      <!-- Change w2d.style-to-tag-map to point to your style-to-tag map document: -->
      <property name="w2d.style-to-tag-map" 
          location="${myAntFile.dir}/style2tagmap.xml"/>
      
      
      <property name="w2d.root.output.filename" 
          value="${doc.base.name}.ditamap"/>
      
      <!-- Specify output.dir to set to the output directory to contain the generated DITA files: -->
      
      <property name="output.dir" location="${myAntFile.dir}/../dita"/>
      <property name="w2d.clean.output.dir" value="true"/><!-- Clean output directory before doing generation -->
      <property name="w2d.debug.xslt" value="true"/><!-- Turn XSLT debug messages on -->
    </ant>
    <ant antfile="${dita-ot-dir}/build.xml" target="dita2xhtml">
      <property name="args.input" 
        location="${myAntFile.dir}/../dita/${doc.base.name}.ditamap"/>
    </ant>
  </target>  

</project>

The text in bold is what you would change to reflect your documents.

Note the initial <property> elements that import a file named build.properties. This approach lets you put this script anywhere and use the build.properties file to set the location of your Toolkit, defined in the Ant property dita-ot-dir. (See Getting Started With The Word2DITA Transform for more details on this one-time setup task.)

If you name this file build.xml in an appropriate directory (e.g., the same directory as the Word document), you can run this Ant script from the command line like so:

c:\workspace\myworddoc\> ant

You can also specify the Word document as a command-line parameter:

c:\workspace\myworddoc\ > ant -Dword.doc=c:/workspace/anotherworddoc/some-document.docx

TODO: It should be possible to use Ant to convert a set of documents in one go but I haven't worked out the details for that yet.

If you want to get really sophisticated you can extend your Ant script to run the Toolkit against the DITA files you just generated, for example, to generate HTML as a way to validate the generated files. To do that you would add this <ant> element after the <ant> element that runs the Word-to-DITA transform:

      <ant antfile="${dita-ot-dir}/build.xml" target="dita2xhtml">
        <property name="args.input" 
          location="${myAntFile.dir}/../dita/${doc.base.name}.ditamap"/>
      </ant>

You can, of course, add any other normal Toolkit arguments you might want to add.