Despite its popularity, the startcmd script delivered with DITA-OT has finally outlived its usefulness. This article is intended for those worried about its eventual removal. My hope is to explain why the script was created, how it was always more a way to hide problems rather than address them, and (most importantly) how Jarno Elovirta finally fixed the problems that caused us to add startcmd in the first place. Without those problems … there is no longer a need to hide them with a script.
DITA Open Toolkit is a toolkit - it's there in the name. With your DITA content as the raw material, you can use DITA-OT to build pretty much anything. The basic toolkit comes stocked with tools to create XHTML, PDF, and a few other basic outputs. Plug in a few of your own tools, and possibilities are endless.
The problem with DITA-OT 1.0 was that it was like getting only part of what you need:
Once you collected the missing tools, you had to assemble them yourself by setting up environment variables. Among other steps, the DITA-OT 1.0 installation instructions included the following:
This put the toolkit beyond the reach of many authors. (Most of those used to modifying environment variables still prefer to avoid it.) It's as if you picked up a toolkit, and opened it to find instructions on where to obtain (and assemble!) your own hammer and screwdriver.
The first attempt at simplification was a new bundled package that included Ant, Saxon, FOP, and more. With that package came startcmd.bat (for Windows) and startcmd.sh (for Mac or Linux). These scripts hid DITA-OT's complexity without changing how the toolkit works. They still did everything listed in the DITA-OT 1.0 install guide. And they did it over and over:
While the original toolkit was missing essential tools, the bundled package added those tools - but didn't tell them how to work together. Effectively, the new package put all of the previously-missing (but still disassembled) tools into secret drawers in your toolkit. startcmd was a shortcut that told DITA-OT where to find those tools and how to put them together - a process repeated every time you ran a build.
dita -i inputFile.ditamap -f html5 -o outputDir
Even better, thanks to brilliant work by Jarno Elovirta, dita also addresses the original toolkit problem - it eliminates the need to find or assemble tools. The toolkit is complete and ready to use; all you need to do is remember how to find it. Finally, the dita command knows where to find both the screws and the (fully functional) screwdriver.
Given the history of startcmd as the Tool That Made Builds Easy, I expect concern about its eventual removal. But at this point, what is it doing for you? The answer is … not much. It helps you find the toolkit, so you can run ant without any path. On Windows, it also opens up a new command prompt. And … that's it, really. It still sets a bunch of environment variables, but the toolkit itself no longer needs them.
Can this be helpful? Sure. Is it familiar? Absolutely. Is it necessary? No - you can do the same builds you have today from anywhere on your system, as long as you remember where you put your toolkit.
For any given release, startcmd only knows how to find and assemble the tools bundled with that release. If you copy startcmd and edit it to run a specific build, what happens when you run that batch script with the next version of the toolkit? If that version requires a new tool, your build will fail. If a new toolkit comes with pliers, an old batch file that can only find the hammer and screwdriver needs to change.
With dita, all that matters is that single command. When the next toolkit adds a fancy set of pliers, a batch script that calls dita still works. When a later DITA-OT requires a hacksaw, bottle opener, wire cutters, and shiny red stapler, a batch script that calls dita still works.
As familiar as startcmd might be, we shouldn't fear moving on. That script was always a kludge - an effective one, which is why it lasted so long as the normal way of doing business. But that was all it ever was - a patch that hid complexity, without addressing the complexity itself.
Thanks to Jarno’s generous work over the last couple years, that kludge is no longer necessary. We no longer need to reassemble our toolkit every time we want to build something. The tools are all there, and delivered in working order. All we need to do is tell it to build.