Replacing starcmd scripts with dita

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.

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.

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

\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.

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

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.