Replacing starcmd scripts with dita

As explained in Why is startcmd deprecated?, the startcmd script is no longer the best way to enter a build process. For those used to using that script as a way to build content, this article explains how to use the new dita command to replace existing processes based on the older batch script.

Example: the many ways to use the dita command

Any copy of startcmd is a shortcut to find and assemble the specific tools required by that release. With dita, you only need to remember where to find that one tool. There are many ways to do this, such as::

  1. In a DOS prompt or shell script, navigate to DITA-OT home directory (where you previously found startcmd), and run bin\dita from there. For example,
    c:\dita-ot-2.1> bin\dita -i \source\my.ditamap -f pdf -o \source\PDF-output
  2. From a DOS prompt or shell script, use a full path to your toolkit and the dita command. For example:
    c:\source> \dita-ot-2.1\bin\dita -i my.ditamap -f pdf -o PDF-output
  3. Create a batch file that sets the toolkit directory and runs a build. A complete batch file (located in the same directory as my.ditamap) could be:
    \dita-ot-2.1\bin\dita -i my.ditamap -f pdf -o PDF-output
  4. ADVANCED, TOTALLY OPTIONAL USAGE: Add DITA-OT’s "bin" directory to your PATH environment variable. Once done, calling dita from anywhere will always run a build. For example, from any directory on the system:
    dita -i my.ditamap -f pdf -o PDF-output
  5. "Hold on to the past" option - not recommended, but if you really like running a batch file to "start" your toolkit, you can still create a much simpler modern equivalent of startcmd and run builds as you did in the past. On Windows, just create a file startdita.bat that sets up the path to your toolkit and opens a DOS prompt. The following does the entire process for a toolkit installed at c:\dita-ot-2.1:
    set PATH=c:\dita-ot-2.1\;%PATH%
    start "DITA-OT" cmd.exe

All of those work equally well. Which works best for you will depend on how you run your builds. I often switch between toolkit versions, so I prefer the first two options. For stable builds with a specific toolkit version, I'd use the third approach. If I only ever used one toolkit version, I might go with the fourth option. I only include the fifth option because it looks so much like startcmd, and illustrates how little "assembly" is now required.

Example: command line build (without your own Ant script or batch file)

The simplest build requires only an input file and a transform type. The sample below use just that, plus an output directory for clarity.

Using startcmd, anybody running a command line build must:
  1. Find the DITA-OT directory
  2. Run startcmd.bat or startcmd.sh
  3. Optional: switch to the source directory
  4. Run a command like the following:
    ant -f \DITA-OT\build.xml -Dargs.input=input.ditamap -Dtranstype=xhtml -Doutput.dir=outputDirectory
Using dita, the same user only needs to remember where to find the DITA-OT directory; no other step is required:
  1. Run a command like the following:
    \DITA-OT\bin\dita -i input.ditamap -f xhtml -o outputDirectory

Example: batch script based on startcmd versus batch script based on dita

A common practice today is to create new batch scripts based on startcmd. The process is something like this:

  1. Copy startcmd.bat to a directory that contains DITA source files
  2. Rename startcmd.bat to something like BuildThisDitamap.bat
  3. Edit BuildThisDitamap.bat to set the toolkit directory (this tells the script how to find your toolkit)
  4. At the end of the batch file, call one or more builds.

With DITA-OT 2.X it's still a good idea to run many builds with batch files, they're just … simpler. Because you don't need to find or assemble any extra tools, each new build is just one line in a batch file.

The copy of startcmd that ships with DITA-OT 2.1.1 is nineteen lines long. To use that as a basis for something like BuildThisDitamap.bat, even stripping out comments (and the "deprecated" message), you'll still end up with:
set DITA_DIR=c:\dita-ot-2.1.1
REM Set environment variables
set ANT_OPTS=-Xmx512m %ANT_OPTS%
set ANT_OPTS=%ANT_OPTS% -Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl
set ANT_HOME=%DITA_DIR%
set PATH=%DITA_DIR%\bin;%PATH%
set CLASSPATH=%DITA_DIR%lib;%DITA_DIR%lib\dost.jar;%DITA_DIR%lib\commons-codec.jar;%DITA_DIR%lib\xml-resolver.jar;%DITA_DIR%lib\icu4j.jar;%CLASSPATH%
set CLASSPATH=%DITA_DIR%lib\xercesImpl.jar;%DITA_DIR%lib\xml-apis.jar;%CLASSPATH%
set CLASSPATH=%DITA_DIR%lib\saxon.jar;%DITA_DIR%lib\saxon-dom.jar;%CLASSPATH%
ant -f %DITA_DIR%build.xml -Dargs.input=input.ditamap -Dtranstype=xhtml -Doutput.dir=outputDirectory
The following batch file does the equivalent of the previous sample with DITA-OT 2.1.1, in just one line:
\dita-ot-2.1.1\bin\dita i- input.ditamap -f xhtml -o outputDirectory

Example: batch script based on an actual ant build

Another common practice is to create a single Ant build file that runs multiple toolkit builds. Some will point out that dita can replace even this (plus, you don't have to write or maintain any Ant code). That said, because they're common, and because in some cases I think they're still useful, I'll compare how this works in DITA-OT 2.X versus older releases.

The old process for setting up Ant builds almost matches the previous example. Instead of calling one transform process at the end of your new batch file, call an Ant build file such as myAntBuildLogic.xml. The batch file based on startcmd is just as long as before:
set DITA_DIR=c:\dita-ot-2.1.1
REM Set environment variables
set ANT_OPTS=-Xmx512m %ANT_OPTS%
set ANT_OPTS=%ANT_OPTS% -Djavax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactoryImpl
set ANT_HOME=%DITA_DIR%
set PATH=%DITA_DIR%\bin;%PATH%
set CLASSPATH=%DITA_DIR%lib;%DITA_DIR%lib\dost.jar;%DITA_DIR%lib\commons-codec.jar;%DITA_DIR%lib\xml-resolver.jar;%DITA_DIR%lib\icu4j.jar;%CLASSPATH%
set CLASSPATH=%DITA_DIR%lib\xercesImpl.jar;%DITA_DIR%lib\xml-apis.jar;%CLASSPATH%
set CLASSPATH=%DITA_DIR%lib\saxon.jar;%DITA_DIR%lib\saxon-dom.jar;%CLASSPATH%
ant -f myAntBuildLogic.xml

With DITA-OT 2.X, you can still call ant directly. Like dita, the ant command shipped in 2.X already knows how to find and use any tool it needs. As with dita, you just need to remember where to find ant. The following batch file for DITA-OT 2.1.1 is the equivalent of the 10 line version based on startcmd:

\dita-ot-2.1.1\bin\ant -f myAntBuildLogic.xml

Advanced example: installing plugins

Some of you may need to add or remove plugins. In earlier releases, the quickest way to do this was usually:
  1. Unzip one or more plugins to the plugins directory in the toolkit.
  2. Run startcmd
  3. From the toolkit directory, run: ant -f integrator.xml

If you are adding a single plugin from a zip file, DITA-OT 2.0 and later offer a cool new shortcut using dita; details are available in the DITA-OT documentation.

If you are adding or removing multiple plugins at once, the process with DITA-OT 2.0 and 2.1 is similar to earlier releases - but you can skip startcmd:
  1. Unzip one or more plugins to the plugins directory in the toolkit.
  2. From the toolkit directory, run: bin\ant -f integrator.xml
Starting with DITA-OT 2.2, a single dita command can add multiple plugins as well:
  1. Unzip one or more plugins to the plugins directory in the toolkit.
  2. From the toolkit directory, run: bin\dita -install