Calling Merged WebHelp Topics Using Map IDs

Introduction

Greg's merged webhelp projects are set up using the structure and methods described in Merging WebHelp. The rest of this page was written by Greg Minter to whom I am very grateful.

Greg has asked that this caveat be included. Please read it carefully.

I make NO GUARANTEES that this method will work for you. Test it on sample data BEFORE you try it on your real data and make sure you understand how everything is working. It'll take a couple days to get it all if you're not completely familiar with RobohHelp. Make a COPY of your data before testing on that. Make a DUMMY publish location either locally or on your web server. If you destroy your data its YOUR OWN FAULT. Don't blame Peter or me!

So now I will hand you over to Greg!

Platform/Browser Caveats

PC

I have managed to get this working on the PC without problems. I am running Windows XP with SP2 installed. It works with the following browsers:

• Firefox (1.0.7)
• Firefox (1.5.0.3)
• Internet Explorer (6.0.2900.2180.xpsp_sp2_gdr.050301-1519)

Macintosh

I have not been able to get this working on a Macintosh. When I load the index.htm file (see below), the TOC pane displays the TOC for the parent project and the content pane is empty.

Note from Peter Grainge: I believe this may be due to the specific Mac OS system (10.4.5) or specific Mac Browser. I have merged webhelp that works on a Mac.

UNIX

I have not had a chance to test this on a UNIX box.

Step 1 - Setting Up for Merged Webhelp

I use the structure and method described in Merging WebHelp. That is not essential to these instructions but you'll be a lot better off if you understand how everything is working, so I recommend that you read that topic and download the demo first.

Step 2 - Define Map ID Ranges

For each child project, you, as the doc manager, must define an exclusive range for the map IDs. For example, for child1 make the range 1000-1999, for child2, make it 2000-2999. The only requirement is they don't overlap (as these files will be merged).

I decided to keep this as a little text file in my source branch:

/rh_projects/parent/map-id-ranges.txt

It looks something like this:

1000 User Ref
2000 User Guide
3000 User Tutorials

10000 Plug-In 1
11000 Plug-In 2
12000 Plug-In 3

20000 Developer Ref
21000 Developer Guide

Doesn't have to be fancy, you just want to track the range of Map IDs you'll be using in each project. The number is the start of the numbers you will allocate and the text is a short name for the child project.

Be sure to give yourself plenty of room in each project. This setup would give you 1000 entries for each child project. If you end up needing 1100 topics, you'd 'spill over' using this numbering system. If that were to happen, you'd have to reassign map IDs in the project you spill *into*, starting at some unique range and regenerate/republish each affected project. Not good. This could also create a domino effect, with each project bumping upward into the next, so be sure to give yourself room. They're just numbers, after all!

Step 3 - Assign Map IDs

In each child project, assign your context sensitive map IDs using numbers in the ranges you've defined in /rh_projects/map-id-ranges.txt.

Step 4 - Name Your Output Window

I found that everything works better if you create a named window in your project. You do this by clicking on the Project tab in RH, then right click Windows and add a new window. In the Window Properties dialog, turn off Use Default Browser Settings and enable all of the other check boxes you want your target window to have. (I found that checking all 5 gave me the default, flexible browser I expected when viewing web-based help.) Give the window a name and caption. The name is the important item here, it's the name you'll be giving the browser window. To be cross platform friendly, I'd recommend using all lowercase and no spaces. Something like:

online_help_window

While the caption can be:

Online Help for MyCoolApp

Make sure the box is checked next to your new window in "Windows to Display"

This window should be the same across all projects (parent & children)...especially the name.

Step 5 - Save, Generate & Publish

The order in which to generate and publish the parent and children projects is described in Merging WebHelp. Follow those instructions exactly: parent first, then children.

Step 6 - Merging the BSSCDefault.h (MapID) Files

In order to get merged behavior using map ids, you need to create a single .h file for the entire merged project. You'll manage that by copying one of the .h files into the /mergedProjects directory, then appending all the others.

1. Copy:
   /rh_projects/child1/BSSCDefault.h

   to
   /rh_publish/mergedProjects/BSSCDefault.h

2. Open /rh_publish/mergedProjects/BSSCDefault.h in a text editor. It might look like this:
   #define child1.htm 1000

3. Open the file /rh_projects/child2/BSSCDefault.h in a text editor. It might look like this:
   #define child2.htm 2000

4. Copy and paste its contents to the end of /rh_publish/mergedProjects/BSSCDefault.h, so it looks like this:
   #define child1.htm 1000
   #define child2.htm 2000

5. Append the BSSCDefault.h file from each of the other projects to the end of /rh_publish/mergedProjects/BSSCDefault.h, until all the mapIDs are in one big file that looks something like this:
   #define child1.htm 1000
   #define child2.htm 2000
   #define child3.htm 3000
   #define child3a.htm 3001
   #define child3b.htm 3002

6. Save the file in the /mergedProjects directory inside your published output directory:
   /rh_publish/mergedProjects/BSSCDefault.h

At this point, if you open the /rh_publish/mergedProjects directory, you should see the following:
/mergedProjects/
/child1
/child2
/child3
BSSCDefault.h

Step 7 - Testing with RH's CSH Tool

Now you can test your help.

1. In RH, click on the Tools tab, then open the CHS Test Tool.

2. For URL/Help File, choose the start page (for example, index.htm) from your /rh_publish directory.

3. For Window, enter the Name of the window you specified for the projects (for example, online_help_window)

4. Click on the "h" icon and choose the merged help file in the /mergedProjects directory: /mergedProjects/BSSCDefault.h

Step 8 - Testing from a Web Page

If you're calling webhelp from a webpage, you can build a test page pretty easily (without bugging your developers) by following the directions below.

You should first read the RoboHelp Office TechNote "Calling Topics with Two Pane View" which you can find here:

http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=5177075f

At the bottom of that article, there are links to various .zip files which include the API stuff you'll need to hook up CSH in your project. They say that this info can also be found in RH's main help, but I found it packaged much more understandably in these downloads (which seem a little hidden to me).

The webhelp_csh.zip file tells you how to call the help from a web page. To make that connection, you need to do two things:

1. Make a test-lookup.htm page that looks something like this (substitute your own domain, publish directory, and help window name in each link).

<html>
<script type="text/javascript" language=JavaScript1.2 src="RoboHelp_CSH.js">
</script>
<p>
<A HREF='javascript:RH_ShowHelp(0, "http://www.yourdomain.com/rh_publish/index.htm>online_help_window", HH_HELP_CONTEXT, 1000)'>Click Here to Show Topic 1000</a>
<p>
<A HREF='javascript:RH_ShowHelp(0, "http://www.yourdomain.com/rh_publish/index.htm>online_help_window", HH_HELP_CONTEXT, 2000)'>Click Here to Show Topic 2000</a>
<p>
<A HREF='javascript:RH_ShowHelp(0, "http://www.yourdomain.com/rh_publish/index.htm>online_help_window", HH_HELP_CONTEXT, 3000)'>Click Here to Show Topic 3000</a>
<p>
<A HREF='javascript:RH_ShowHelp(0, "http://www.yourdomain.com/rh_publish/index.htm>online_help_window", HH_HELP_CONTEXT, 3001)'>Click Here to Show Topic 3001</a>
<p>
<A HREF='javascript:RH_ShowHelp(0, "http://www.yourdomain.com/rh_publish/index.htm>online_help_window", HH_HELP_CONTEXT, 3002)'>Click Here to Show Topic 3002</a>
</html>

In the example above, I made test links to mapIDs 1000, 2000, and 3000, topics which I know exist in my BSSCDefault.h file.

2. Copy the file 'Robohelp_CSH.js' into the same directory where you save your test-lookup.htm file (note the reference to it in the test-lookup.htm page. I stored this javascript file at the top level, in the /rh_publish directory.

   You can find the Robohelp_CSH.js file in the webhelp_CSH.zip download mentioned above.

Step 9 - Check Out Your Help

If everything loads properly, you should see a tri-pane window with controls across the top, a TOC showing all three child projects, and the default topic displayed in the right hand pane. If you're testing from the CSH Test tool, try selecting different mapIDs. If you are testing from a web page, try clicking on the different links.

Step 10 - Adding New Child Projects

OK, so now you've released your initial help system and the development team comes over and says "Hey, we want to release a plug-in." You say: "No problem."

Here's what to do:

1. Make a new child project.

   If you've already set up using Peter's directory structure, you can copy one of the other child directories, then load it into RH, and File->Rename the project. (If you choose to make a brand new project instead of copying an existing one, you'll need to define a default output window with the same characteristics as the other projects...I found it easier to copy the project, then simply delete the files you won't be using.) For illustrative purposes, let's say you call the project /child4/child_4.xpj

2. Close the /child4 project and open the /parent project. Go to the TOC tab, and click on the New Merged Project icon (the diamond shaped icon) right above the TOC. Choose the child_4.xpj file and you should see the new entry in the TOC. Make sure to order the merged projects, as their order in the parent project will determine their order in the output.
3. Open the /child4 project and create any mappings you'll need. Resave the project.

4. Open the file:
   /rh_projects/child4/BSSCDefault.h

   then copy and append its contents to:
   /rh_publish/mergedProjects/BSSCDefault.h

5. Open the /child4 project and generate & publish it.

6. After publishing the new child project, you'll also need to republish the parent project (that's because a few files get updated when you add a new merged project to the parent project). Make sure to turn off the Republish All option when republishing the parent so that only the changed files have to be published.

That's it.

NOTE: If you try this and find that your TOC doesn't show the new project, make sure to clear out your browser cache.

Step 11 - Adding References to Existing Projects

If you make new references from another child project (e.g., from /child1 into the new project /child4), you'll need to re-generate and re-publish both child projects.

Summary

Benefits

I think this gave me about the most flexible solution within RH. It supports:

• Cross-project sync'd TOC
• Cross-project Index
• Cross-project Search
• CSH lookup using mapID numbers
• Incremental release of new projects

This is as close as I can come to an automatic solution for updatable help. The nice things about it are:

• You can do cross project references
• Cross-browser support
• The book names in the TOC are loaded from the top level book names in the child projects
• You can release help over time for things like plug-ins.
• If you only wanted certain users to get the plug-in help, you could distribute the updated .h file and child project folder, and let them install it locally. (I think the "airplane" help concept might work out nicely here.)

Not Tested Yet:

1. What happens if you have duplicate mapIDs in the merged .h file? I would suspect that help would display the first entry with a matching ID. Easy enough to test, just haven't had time.

Some Notes:

1. Since you have multiple projects, some things (like window output name, conditional tags, CSS files) can't be shared. You'll have to manage these manually if they need to be the same in each project.