Sharing DITA-OT in OS X & Boot Camp

If you’re using the DITA Open Toolkit on Mac OS X, you can’t generate compiled HTML Help (CHM) files directly, since Microsoft only offers the HTML Help Workshop for Windows.

But if you also run Windows on your Mac via Boot Camp, you can set up a single installation of the Open Toolkit on your Windows partition and use it to generate output from either operating system environment.

Essentially, you boot into Windows (via VMware, Parallels, or directly) and set up the toolkit there as usual.

Once you have the toolkit running under Windows, create a copy of the Ant build file for your project, adjust the paths for access from Mac OS X and save it under a new name in the DITA-OT directory on your Windows partition. (You’ll call this file later from the Terminal to build your project output on the Mac.)

Back on Mac OS, set up the environment variables required by the toolkit.

You can do this by editing the .bash_profile file in your home directory, or if you don’t like editing hidden UNIX files by hand, you can use freeware such as RCEnvironment or SSHKeychain, which provide a simple dialog that allows you to define environment variables like in Windows.

(In the background, both tools simply write to the ~/.MacOSX/environment.plist file. SSHKeychain also serves as a nice Mac equivalent to PuTTY, but that’s another story…)

The key here is to use the absolute path to the toolkit installation on the Boot Camp partition. For example, if your Windows partition is named BOOTCAMP and the toolkit lives there at C:\DITA-OT1.4.1, you might set the DITA_HOME variable like this:

DITA_HOME=/Volumes/BOOTCAMP/DITA-OT1.4.1

You can then define the other variables relative to the toolkit directory with entries like this:

ANT_HOME=$DITA_DIR/tools/ant

Note: If you use either of the aforementioned tools to edit ~/.MacOSX/environment.plist, you’ll need to use the full paths for the remaining variables, as $VARIABLE values are not expanded when this file is read.

Once the variables are all set, you’ll need to log in to OS X again to activate them.

Then with a command like this, you can build output from the Terminal using the Mac version of the build file you edited above:

ant -f your-mac-build-file.xml html

To build CHM output, switch to Boot Camp, run startcmd.bat in the DITA-OT directory, and enter something like this on the command line:

ant -f your-windows-build-file.xml chm

If both your build files are set to share an output folder on your Mac, your files will land in the same place, no matter which operating system you build them on.