RoboHelp 8 and DITA

If you use RoboHelp 8, you can start getting your feet wet with DITA without necessarily buying a DITA authoring tool. You can’t create DITA maps or topics – that capability won’t be available until, presumably, RoboHelp 9. But you can import DITA maps and topics into RoboHelp 8 to see how well it handles DITA features and how well it turns the DITA material into outputs like WebHelp.

The sticking point is that RoboHelp 8 uses the DITA Open Toolkit (OT) to import DITA material. This means you need the properly configured OT on your PC. If you typically work in RoboHelp’s GUI, installing and configuring the OT will be far more techie than you’re used to. The instructions below should help make the process easier. (Note that some version numbers may have changed since I wrote this. In particular, v. 1.4.3 may have been replaced by v. 1.5.)

Download and unzip the OT from:

http://sourceforge.net/projects/dita-ot/files/#

This will create, among other things, a folder called doc that contains the installation instructions.

Then, if you’re a Windows user, follow the instructions at:

C:\ditaot\DITA-OT 1.4.3\doc\ installguide\windows_installing.html

A crucial step is to be sure your environment variables are correct. You’ll know if they aren’t if you try to import a DITA map into RoboHelp and get this message (shortened somewhat here) in RoboHelp’s Output View pane:

C:\DITA-OT1.5\build_preprocess.xml:269: java.lang.VerifyError: (class: topicpull, method: …
...
Inconsistent stack height 1 != 0

Again, this probably means your environment variables aren’t set correctly. To fix them, follow the instructions in the document at:

C:\ditaot\DITA-OT 1.4.3\doc\installguide\ windows_settingenvvariables.html

However, be aware that some of the settings needed for your PC, particularly the JAVA_HOME setting for the folder where you installed the JDK, may differ from those in the setup instructions.

Note also that some environment variables are optional. For example, if you do not plan to output JavaHelp, you can ignore the JHHOME setting. If you do not plan to use the Apache FOP, you can ignore that setting for the CLASSPATH variable. Ditto for the Xalan setting for the CLASSPATH variable.

Note also that some of these settings are long and complex enough that you do not want to type them if you can avoid it. An easier thing to do is to open the environment variable instructions file (… windows_settingenvvariables.html), copy the value of each variable field that you’re modifying and paste it into Notepad, copy the value to be added for that field from the instructions in the …windows_settingenvvariables.html file, and paste it into the code in Notepad, and finally copy the code out of Notepad and paste it into the appropriate variable field. As messy as this sounds at first, it’s actually straightforward with less risk of typographic errors.

Finally, note that I'm not getting into the specifics of variable settings, especially for the JDK, since it will vary depending on which version you have. But email me if you have specific questions and I'll try to answer them.

You’ll know that you’ve set all the environment variables correctly if you try to import a DITA map and get the “import successful” message in RoboHelp’s Output View pane.

How long will this take? If you’re accustomed to commonly working at this level of technical detail, about an hour. If you’re not, plan on two to three hours. This may be a big chunk of time in a crowded schedule, but it’s a small investment in time that can open up a whole new feature set in RoboHelp.

If you’re interested in more information about how help authoring tools (HATs) are starting to support DITA, I’m giving two presentations at Lavacon in New Orleans in late October, one on how to use HATs to work with DITA and one on how to use HATs to create simulated CMSs. If you’re not going to Lavacon, I’d be happy to send you copies of the PowerPoint slides after October 30.