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:
    ssl_xml_before
  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.
    rh_motw_on
  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.
    ssl_xml_diff
    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:
    ssl_search_replace
    …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.

RoboHelp: Search Optimization, Part 1

The background

We have a rather large online help system – about 6000 topics in 40 separate modules – generated using RoboHelp, in WebHelp format, and delivered both on a website and as an MSI.

The problem

The search takes too much – 25-30 seconds when run on the server. If the help is installed locally, the search is much faster, but most of the clients use the website.

The reasons

After a few rounds of testing and a lot of googling, I reached the conclusion that the biggest culprit is the RoboHelp search (but some structural improvements in the content wouldn’t hurt either).

The solutions

Because content changes are more difficult to implement in the short term, I started testing various options of optimizing the search.

Attempt no. 1: No PDF and Word searches

Because each module has a PDF version that contains the same stuff as the online help, I first excluded all such documents from the search.

optimize_search_exclude

Result: no performance improvement. (But I still think it was a good idea, because we are avoiding duplicate content in the searches.

Attempt no. 2: Searching on all terms by default

Because RoboHelp 2015 has a new option for this, I enabled “AND” search by default in all modules.

optimize_search_and

Result: no performance improvement (but I wasn’t expecting one anyway). I don’t know why we had to wait so many years for such an obvious setting, but better late than never, I guess. Now the search should be working like everybody probably imagined it was working already.

Attempt no. 3: Optimizing for LAN

Yeah, it’s not really intuitive, after all we are publishing to the internet. Well, apparently the option kept its name from the dial-up days…

Some background first: to enable the search functionality, RoboHelp generates some files (with names like package_n_xml.js) in the folder whxdata. Every search loads every one of these files… so the more files, the more requests to the server and the slower everything runs. Here is where our option comes in: when the output is optimized for internet, RoboHelp generates more, smaller package files (because this was more efficient in the old days, I guess); when the output is optimized for a local network, RoboHelp generates fewer, larger package files.

optimize_lan

So… I started comparing, after I generated the entire help system with each of the options:

  • A search in Windows for the package*.js string, in the entire help system: the LAN-optimized version has 6 times fewer package files.
    optimize_compare_package
  • A comparison at the merged project level: the LAN-optimized version has 6 times fewer files in the whxdata folder and there are 2 package files instead of 41.
    optimize_compare_folder
  • A comparison in Chrome Developer Tools: in the LAN-optimized version there are 190 requests, compared to 275 in the internet-optimized version.
    requests_optimize_compare

The questions (for which I don’t yet have clear answers):

  • Why aren’t there 6 times fewer requests? After a quick analysis in Developer Tools, I gathered that, for each module, at least 5 requests are sent: packageindex_xml.js, package_0_xml.js, synonym_xml.js, topictableindex_xml.js and topictable_0_xml.js, so there comes a point when the only way of improving the performance is reducing the total number of modules.
  • Why is 5 times more data being downloaded when the content is optimized for LAN, especially considering that fewer requests are sent?

Result: an almost insignifiant performance improvement, far less than I was hoping for.

The final conclusion

After a month of testing, I know way more about the RoboHelp search… and I managed to improve the search by whooping 5 seconds (on days with a good connection).

What next?

Two things:

  • Consolidating modules – fewer modules, fewer files, fewer requests, faster search.
  • Implementing an external search – Google custom search or Zoom Search.