Can someone provide a brief explanation of how Map IDs work?

[TechDocJosh]

I'm trying to figure out how Map IDs actually work. I understand how to assign them in the RoboHelp GUI. But, where is that information stored? And where is it in the output file so the product knows what topic to show? When I look at the .h file, it just lists the map ID and number, as below:

#define ACH5_4   26

#define ACH5_6   27

and so on. Nowhere in this file does it show what .htm file to bring up when called from the product. So this must be stored somewhere in the project file. And that must carry over to the webhelp output folder somewhere, right?

Thanks, Josh

[Willam_van_Weelden]

It's stored in the .ali file. There the map ID is linked to a topic.

There's no need to worry about this, as you can assign topics to Map ID's from withing RoboHelps GUI.

Greet,

Willam

[TechDocJosh]

Wow, what a helpful answer. Because it makes absolutely NO sense to know how a tool works that I use every day.

[Jeff_Coatsworth]

Now, now - Willam was just trying to explain that it can all be managed within RH. The basic explanation is that topics get linked to IDs that can be called from your application - this is known as "Context Sensitive Help" (CSH). There are a variety of methods that can be used to invoke the topic - you'll see them all in your RH install folder's CSH sub-folder. How you get the IDs can flow 2 ways - either you (the author) assign them and then give the .h file to the programmers to use or they assign them and give you a file of IDs for you to assign to your topics.

Have you investigated CSH with the info on Peter Grainge's site (grainge.org)?

[TechDocJosh]

I  understand the basics, and using the Map ID editor. But when I look through the WebHelp output folder, I see no references to IDs, numbers, or aliases. Where does the magic happen? That info must be stored in one of the million RH output files, otherwise when the application calls, how would it know which ID is associated with which alias?

And yes, it can be managed from within RH, but so can a lot of other things that are sometimes better to manage manually, or at least understand how to manage outside of RH. If I'm working with a new developer, it's useful for me to know this stuff.

[Willam_van_Weelden]

Now we're getting somewhere: this is buried within several files, the most important ones are your project start file, whcsh_home.htm and whcshdata.htm and whstart.js. I say the most important, because WebHelp actually supports three different methods for calling help context sensitive.

For a comprehensive overview of available CSH calls for all three methods, see http://www.wvanweelden.eu/articles/context-sensitivity-webhelp-and-flashhelp

You can of course use other methods for managing the CSH, for example using scripting and external programs to generate CSH. But doing this requires rather intimate knowledge of RoboHelp, your requirements and possibly some programming skills from you.

Greet,

Willam

[TechDocJosh]

Thanks, that's helpful. Now I just gotta figure out how development is pointing to those files.

[IMKarla2]

The developers should have the MapIds in their code as "help hooks"--at least that's what they're called here. That is, somewhere at the top of their code, they reference the help file, and then throughout the code, wherever there is a button or link that should open the help, there is a help hook (your MapId) that says, "when this button is clicked, open this topic in that help file." That's what you do in RH or in the ALIfile--you map the ID to their help hook. So, in my case, the developer gave me an HM file that has IDs on it like this:

#define HIDD_CONNECTION_WIZARD_PASSWORD_PAGE

0x20020

and in my ALI file, I have that MapId (alias name) linked to the appropriate topic:

I found that Robohelp needs the #define in front of it in the HM file, so I have to add that when I get it from the developers. (It used to always have that.) I've had to go back and forth several times with development when it's not working right (because they couldn't possibly be wrong!). Here's a tip: In HTML Help Workshop, there is tool that allows you to test each ID to verify that it opens the right topic. If it opens the help to the default topic, that means the developers are using a different ID in the code than what you have in the ALI file. (The help system didn't know which topic to open.) If it opens the wrong topic, then you need to edit the ALI file to point to the correct topic.

I wrote an article about that here: http://grammarparrot.com/2012/07/28/working-with-programmers-to-create-context-sensitive-help/

[Captiv8r]

Hi there

Sorry you didn't like Willam's answer. But he's spot on that RoboHelp helps you out.

Try this. Open the Project Set-up pod. Then click to expand the Context Sensitive Help folder. Then click to expand the Map Files folder.

Now double-click the All Map IDs item. That should give you a dialog to map topics.

You might also be interested in the following link:

Click here to view

Cheers... Rick

[Willam_van_Weelden]

You wanted a short explanation and one line is pretty short in my book. Just check the .ali file and you will see how map id's work in RH. But be careful: meddling with the ali file can wreck your project.

Obviously this data is converted to the output, but how this is done depends on the output you are creating. And every output has it's own way of handling CSH calls and there is no short answer to how those scripts work, but there are some lenghtier ones available. The question then is: what output are you creating?

Greet,

Willam