Creating JavaHelp with RoboHelp 10

When you generate JavaHelp with RoboHelp, RoboHelp has to “know” where certain Java files are located. You’d think that would be as simple as pointing to the locations within RoboHelp’s interface, but it’s not. Instead, I have to edit the computer’s Environment Variables to point to JAVA_HOME, JAVAHELP_HOME, and JHHOME, and I have to edit the RoboHelp “SingleSource” registry settings.

The company I work for is really great about providing me with the resources that I need to do my job effectively. Two of the things every technical writer ALWAYS needs is more RAM and more storage. I’ve worked here 6 years and I’m on my fourth computer upgrade, because of the need to add more RAM, a bigger hard drive, or a new operating system. The downside of this is having to reconfigure my computer four different times. For the average “knowledge worker,” reconfiguring the computer is no big deal. You might have to set up Microsoft Word with the settings and templates that you use most often, copy files from the old hard drive to the new, etc. If you use RoboHelp, it’s not always so simple. This is especially true if you have to generate JavaHelp.

RoboHelp uses a file named java.exe to generate JavaHelp and a file named hsviewer.jar to open the JavaHelp so that you can view it after you generate it. RoboHelp also uses several other JAR files, and you must tell it where they are. To do this, you must edit the computer’s Environment Variables and Registry settings.

CAUTION! If you have never edited the Environment Variables or the Registry on your work computer, I suggest that you get your IT department involved in this process. After all, if you break it, they’re the ones who will have to fix it.

(The procedure below is for a Windows 7, 64-bit computer. Your OS may differ, but the steps will be very similar.)

To get RoboHelp to generate JavaHelp, this is what I do:

  1. Download the latest JDK from http://www.oracle.com/technetwork/java/javase/downloads/index.html. (Because hackers LOVE to screw with us, the JDK is updated frequently.)

  2. Install the JDK and note the location in which the JDK is installed. For this procedure, let’s say it’s installed at C:\Program Files\Java\jdk1.7.0_25.

  3. If JavaHelp 2.0 is not in the JDK, you can download the JavaHelp system build from https://javahelp.java.net/. (Right-click “here” at the very bottom of that page, then save javahelp2_0_05.zip to your hard drive.)

  4. Extract the files from the ZIP file, and then copy the folder named jh2.0 to the root of C.

  5. Open the Control Panel (Start > Control Panel), then click System.

  6. On the left side of the Control Panel, click Advanced system settings. The System Properties dialog box appears.

  7. Click Environment Variables. The Environment Variables dialog box appears.

  8. Under User Variables, edit or create JAVA_HOME, JAVAHELP_HOME, and JHHOME as follows:

  • Set JAVA_HOME to C:\Program Files\Java\jdk1.7.0_25 (or current version)

  • Set JAVAHELP_HOME to C:\jh2.0\javahelp

  • Set JHHOME to C:\jh2.0\demos\bin

  1. Under System variables, scroll down to and click Path, then click Edit.

  2. Within the Path statement, add or edit the following paths. (Add a semicolon between paths, no spaces. You can just add it to the end if it’s not there already. Copying the Path to a Notepad document might help if it’s a long path.)

  • C:\Program Files\Java\jdk1.7.0_25\bin (JAVA_HOME has to point to the folder that contains java.exe)

  • C:\jh2.0\demos\bin (JHHOME has to point to the folder that contains hsviewer.jar)

  1. Click OK to save the changes.

  2. Click OK to close the System Properties.

  3. Close the Control Panel.

  4. Click Start, then click Run, and type regedit.exe in the Open box. The Registry Editor appears.

  5. Expand nodes until you get to the following node:

HKEY_CURRENT_USER\Software\Adobe\RoboHelp\10.00\SingleSource\

Creating JavaHelp2

  1. Double-click to open each item in the right pane to edit the data, as needed. They should read as shown below. (Edit JavaHelpJdkHome and JavaHelpJdkVersion to reflect the installed version. This will change when you install new versions of Java.)

  • JavaHelpHome = C:\jh2.0

  • JavaHelpJdkHome = C:\Program Files\Java\jdk1.7.0_25 (current version, as above)

  • JavaHelpJdkVersion = 1.7

  • JavaHelpRunTimeFiles = javahelp\lib\jhall.jar;javahelp\lib\jhbasic.jar;javahelp\lib\jh.jar;javahelp\lib\jsearch.jar;demos\bin\hsviewer.jar;

  • JavaHelpVersion = 2.0

(I’m not sure what the effects of the other items are on generating JavaHelp, but I know that I had to edit the ones above to get RoboHelp to generate JavaHelp.)

  1. I always reboot the computer just to be sure the new values are read in.

  2. Open your RoboHelp project and attempt to generate JavaHelp. If RoboHelp pauses to ask you questions about JavaHelp, that means something is not right. Make sure your Path statement points to the correct location, and JAVA_HOME, etc. are all configured correctly.

Stupid Things RoboHelp Does

Stupid Things RoboHelp Does

Update: I updated to RoboHelp version 8. So much improved over version 7! The Search improvements alone are worth the upgrade! (12-25-2011: Version 9 was released this year (?) and I’m told it has many improvements, but I have not tried it.
———————
The meat and potatoes of a “real” technical writer’s job is making context-sensitive help files that are embedded in software applications, often in addition to Web-based help and printable user guides. There are numerous “single-source” applications that you can use to, in theory, compose once and generate the several types of help you need (PDF, CHM, Web-based, JavaHelp, Oracle Help, etc.). I’ve used a variety of these so-called single-source authoring tools, and none of them is truly single-source. If you don’t have to meet any specific requirements, then RoboHelp, Flare, Doc-To-Help, AuthorIT, Notepad, and such will likely provide what you need. But if your output must meet specific requirements, that single-source authoring tool will need your creative and research skills to figure out how to “fix” the output.

For a help authoring tool, RoboHelp has notoriously bad help. Meaning, when you click Help in RoboHelp, I very rarely find the help I need. If you search the Internet for help, you will find numerous experienced RoboHelp users with awesome Web sites to provide some of the more common tips, as well as tips for very advanced users (e.g., Peter Grainge’s Site, RoboWizard, Google Groups).
Below are a few tricks I’ve discovered while using RoboHelp. Come back here from time to time as I find other stumbling blocks. Unfortunately, by the time I figure out how to fix the problem, I’m usually in a hurry to get past it and don’t think to document what I did. But it always manages to find me again. There are many, many, many more that I’ve never documented, but when I stumble across them again, I’ll add them here. :-/

Perhaps you have a better solution? If so, please let me know in the comments.
Below are real problems/needs that I encountered and the solutions that worked best for my situation. I encourage you to experiment with the code (after judicious backing up and copying) to find the solution that works for you.

Problem/Need: I had been fighting doing merged chms because it’s more complicated for print and I like having the WebHelp all in one project. But as the project got bigger, it became clear that it would be much easier to manage the project in pieces with merged helpsets, so I bit the bullet a while back and did it. Today I wanted to link topics between merged helpsets and FINALLY found a clue. The info I found online finally worked after I played with the link (based on what I knew from linked JavaHelp).
Solution: Without any help from RoboHelp’s help, I found that when you insert the hyperlink, in the Hyperlink dialog box, you can click the Link to arrow, then click Remote Topic. Then the Select Remote Topic dialog box opens, in which you can select the merged helpset’s chm (which you’ve already copied to the Source folder), then click the topic filename. The link is similar to a normal “a href” link, but with the filename of the chm, 2 colons, and a forward slash in front of the htm. The code looks like this:
<a HREF=”gs_com_api.chm::/Setting_the_expiration_date_for_a_user_account.htm”>Setting
the Expiration Date for a User Account (SetExpirationDate)</a>

In this example, the text the user sees look like this:
Setting the Expiration Date for a User Account (SetExpirationDate)
When I clicked the eyeglasses icon (preview) it didn’t work, but when I compiled, it actually worked.

Problem/Need: WebHelp does not appear correctly in Google Chrome (the TOC, Glossary, Index, Search tabs are blank)
Solution: Adobe posted a fix on their support pages (within ONE DAY of complaining!): Chrome fix

Problem/Need: A topic named “Using the Software with IIS” was not coming up in a search for “IIS.” I suspected the stop words were preventing it from appearing, so I deleted “is” from the stop words. Nope, didn’t fix it. Then I found RoboHelp’s stop words file and edited that. Nope, didn’t fix it. Then I edited the stop words file from the generated help. That fixed it. But when I regenerate, it will over write it.
Solution: I really hate it when apps try to think for me! I removed the stop words from the project FOR A REASON, and when I generated, the stop words reappeared in the project. So when I edited RoboHelp’s stop words file, the stop words had already been added back to the project. I saved my “clean” stop words file away from the generation folder, but it would be nice if RoboHelp just let me do the thinking. 😕