open topic in merged chm file in master chm file window

Question

I would like to open topic in merged chm file in master chm file windows. I have main chm file of application help. So this main chm file includes sub chm file. And I would like to open the topic in sub (merged) chm file in the window of main chm file by calling htmlhelp function.

The following is header file in main chm project.And operation\ACORD_geometry.chm is merged chm file. Now I'm using Adobe robohelp.

[ALIAS]
  IDH_operation_geometry=operation\ACORD_geometry.chm:\HID_geometrytab_functions.htm

[MAP]
  #define IDH_operation_geometry    9001

And I call htmlhelp function by following way. But The topic don't open. .\help\3DFEMGeo.chm is main chm file.

HtmlHelp(Application.Handle, '.\help\3DFEMGeo.chm', HH_HELP_CONTEXT, 9001);

Please teach me the way to open topic in the sub chm.

Answer 1

Creating modular help systems has some benefits by merging indexes and TOCs of multiple help projects, but overcoming the wall is difficult some times. Some parts of the following instructions have been posted many years ago by Sean Stagmer. For context-sensitive help see also content and links at the bottom:

http://www.help-info.de/en/Help_Info_HTMLHelp/hh_context-id.htm

Long story short (HTH - please try for your needs and environment):

// *** BEGIN CODE SNIPPET
...
HID_TOPIC_ID1="ms-its:Master.chm::/SubHelpSubject1.chm::/Topic_1.htm#Topic1"
HID_TOPIC_ID2="ms-its:Master.chm::/SubHelpSubject2.chm::/Topic_2.htm#Topic2"
...
// *** END CODE SNIPPET

And the stories long version:

RoboHelp e.g. and many other Help Authoring Tools (HAT's) are a IDE front end for utilizing the Microsoft HTML Help compiler (hhw.exe). The designers of RoboHelp's older versions did a pretty good job of separating the technical aspects of building an HTML compiled help file, but left out several features available if you used the underlying tool directly. Specifically, modular help. I assume that most people who investigated this topic learned about adding the following to their help project file (the .hhp) to begin designing a modular HTML help system:

// *** BEGIN CODE SNIPPET
[MERGE FILES]
SubHelpSubject1.chm
SubHelpSubject2.chm
...
// *** END CODE SNIPPET

Now, tackling the subject of context-sensitive help AND merged files in a modular design adds a new twist: How can the topic ID be mapped to the appropriate merged HTML file? Being modular, the topic ID is not in the master/host help file, but is instead integrated into it through the merged sub-help project's .chm file. This is accomplished by placing the following code in the master/host master's TOC file:

// *** BEGIN CODE SNIPPET
...
<LI>
<OBJECT type="text/sitemap">
  <param name="Name" value="SubHelpSubject1">
</OBJECT>
<OBJECT type="text/sitemap">
  <param name="Merge" value="SubHelpSubject1.chm::\SubHelpSubject1.hhc">
</OBJECT>
<LI>
<OBJECT type="text/sitemap">
  <param name="Name" value="SubHelpSubject2">
</OBJECT>
<OBJECT type="text/sitemap">
  <param name="Merge" value="SubHelpSubject2.chm::\SubHelpSubject2.hhc">
</OBJECT>
...
// *** END CODE SNIPPET

With these two additions (the MERGE FILES statement and the addition to the TOC file) the correct resolving of topic id's to their help topic information is complete, EXCEPT that you notice that the HTML help window shows ONLY the TOC for the sub-help project it mapped to! The master/host TOC doesn't show up at all. What gives?

The answer lies in the alias file for the master/host project. Being a good little HTML help content developer, you knew to map the topic id of interest to the appropriate sub-help file by modifying the simple alias syntax like this:

// *** BEGIN CODE SNIPPET
...
HID_TOPIC_ID1=Topic_1.htm
HID_TOPIC_ID2=Topic_2.htm
...
// *** END CODE SNIPPET

...to this:

// *** BEGIN CODE SNIPPET
...
HID_TOPIC_ID1="ms-its:SubHelpSubject1.chm::/Topic_1.htm#Topic1"
HID_TOPIC_ID2="ms-its:SubHelpSubject2.chm::/Topic_2.htm#Topic2"
...
// *** END CODE SNIPPET

That little 'ms-its:' thing is very much like the 'http:' or 'ftp:' text you type into a web browser: it's known as an Asynchronous Pluggable Protocol from Microsoft. The '::/' portion of it is a reference; a kind of 'level of indirection' or 'reference alias' in C++ parlance. So, to solve the problem of having the context-sensitive help topic BOTH map to the correct help topic html text AND keep the TOC synchronized with the master, you must add an additional level of indirection to make it work, as shown below:

// *** BEGIN CODE SNIPPET
...
HID_TOPIC_ID1="ms-its:Master.chm::/SubHelpSubject1.chm::/Topic_1.htm#Topic1"
HID_TOPIC_ID2="ms-its:Master.chm::/SubHelpSubject2.chm::/Topic_2.htm#Topic2"
...
// *** END CODE SNIPPET

This can be read as meaning this: "When displaying the help topic HID_TOPIC_ID1 information, open Master.chm, then navigate to SubHelpSubject1.chm's HTML file Topic_1.htm, then move down the page to the bookmark Topic1."

Hooray! Your topic pops up, and the master/host TOC is visible as well!

Like thinking in C++ terms the alias file looks very much like how we would reference functionality in a C++ class:

Result = BaseClass::SubClass1::Subclass2::DoFunctionCall();

As a side note, this syntax is being replaced by XML - HTML help will reference a 'Collection' as specified in a collection file (.col), which has XML entries in it. Much easier to read and follow than the obtuse PERL-like syntax in the alias file.