RoboHelp: Batch automation (rhcl.exe)

Although it doesn’t seem to be too well-known, the command line version of RoboHelp can be extremely useful for automating help builds partially or completely.

What is rhcl.exe?

The name of the utility stands for RoboHelp Command Line and enables you to generate an SSL without opening RoboHelp itself. For small documentation systems, there’s not much effort in double-clicking an .xpj, but if you have 20 modules, you might be spending more time waiting for the modules to load than actually building the help.. and this is where rhcl comes in.

How is it used?

Very simply, because it only has a few parameters (which I won’t go over, because they are available in Adobe’s documentation.)

A command line could look like:

rhcl c:\sources\project1\project1.xpj -l WebHelp -o c:\builds\project1

In translation, first you have the name of the executable, then (without any parameter) the path where the xpj of the project you want to generate is located, then (with the parameter -l) the name of the layout to generate, and finally (with the parameter -o) the location where the files should be generated.

For what I need at work, these parameters are enough. If you want, you can also use rhcl to publish a layout (using the option -p) or to generate logs (using the option -g), but I haven’t worked with either of these a lot.

My batch looks something like this:

Tips & tricks/Troubleshooting

  • If your command lines start with rhcl, the .bat file needs to be saved in the same folder as rhcl.exe. If, instead of simply rhcl, you use the absolute path to the executable (for example C:\Program Files (x86)\Adobe\Adobe RoboHelp 2015\RoboHTML\rhcl.exe), you can save the .bat file anywhere on your hard drive.
  • If the path contains spaces, it needs to be between double quotes.
  • rhcl is probably not very high on Adobe’s priority list, so it is not always properly tested. In RoboHelp 2015, if you tried to generate the help using rhcl and you had conditional build tags excluded from the SSL, the output was not correct (all tagged content was excluded, even if it appeared included in the SSL settings). The bug was fixed in update 2.
  • Some modules refuse to be generated by batch, without any obvious reason. I don’t have a solution for this, other than generating the module manually (from the RoboHelp interface).
  • In RoboHelp 2015, if you can’t generate anything by batch, install the KB2758694 and KB954430 Microsoft updates.

RoboHelp: Making Bulk SSL Changes

RoboHelp’s interface is pretty intuitive, and once you understand what each option does it’s not difficult to generate an online help system. But what do you do if you have to make a lot of changes – like, for example, modifying a setting in WebHelp for 40 modules? The “simple” option is to open each module, double-click the SSL, navigate to the corresponding wizard page, make the change, save, open the next module… and so on, 40 times. The smarter option is realizing that (like most of RoboHelp’s files) the SSL is a relatively-simple-to-manipulate XML.

This method can be used for any of the settings visible in the GUI (and even for some that are not visible). In the following example I will assume that I have several modules, with at least one SSL defined for each, and that I’m trying to deactivate Mark of the Web for all of them.

In short, we will compare the XML with Mark of the Web turned on and the XML with Mark of the Web turned off and we will then use search & replace to change the option in all modules.

  1. From the source folder of one of the RoboHelp projects, open the file <SSL_name>.ssl in a text editor (I use Notepad++). You will get something like this:
  2. Open an empty document or tab and copy the entire contents of the file in it. You need to do this because the next steps will change the initial XML and you need both versions for the comparison.
  3. In RoboHelp, open the respective project and double-click the same SSL you used at step 1.
  4. Change the options as needed – in my case, I cleared Mark of the Web. (You can change multiple options at the same time, but you risk getting confused, so it’s safest to take them one by one.)
  5. Save the SSL. The XML at step 1 is immediately modified and you now have two versions of the same file – a before and an after.
  6. Identify the modified row. In Notepad++, I use a plugin called Compare. If I select Plugins > Compare > Compare, Notepad++ compares the last two files opened and highlights the changes.
    Be careful though, because (for reasons that escape me) some rows are rearranged the moment the SSL is saved, so you will see a lot of apparent changes that are actually irrelevant to what we are trying to do. Either way, the files are not big and it’s fairly easy to find the row with the modified value by simply scrolling and eyeballing it.
    As you can see, <element name=”m_bSupportMOTW” value=”1″ /> in the initial file means that Mark of the Web is on, while <element name=”m_bSupportMOTW” value=”o” /> means that it’s off.
  7. Replace the old row with the new one in all relevant SSLs. In Notepad++, that can look like this:
    …which translates as :

    • Replace <element name=”m_bSupportMOTW” value=”1″ /> with <element name=”m_bSupportMOTW” value=”o” /> 
    • …in all files called WebHelp.ssl
    • …located in D:\technical_documentation or one of its subfolders.

Tada! It all took 5 minutes in total, and you can continue by using a script to regenerate the entire help with the new option.