Merge Tips from Sean

From: Sean Stagner <...@winprosoft.com>

Subject: Microsoft HTML Help: Solution for context-sensitive help and merged files

I have noticed a dearth of good documentation concerning advanced topics such as how to design and implement modular HTML help. This recently came to my attention as I heard my tech-writer girlfriend exclaiming her impatience at not finding information applicable to this subject. Wishing to save my hearing (and not learn too many new vulgar expressions concerning Microsoft) I decided to step in and help.

She, like many others, use the "standard" [sic] tool of the industry (i.e.RoboHelp 2000). But it is really only a fancy IDE front end for utilizing the Microsoft HTML Help compiler (hhw.exe). The designers of RoboHelp 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>

</OBJECT>

<LI>

</OBJECT>

</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 in Microsoftese. 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!

I can certainly understand my girlfriend's impatience and frustration - no

tech-writers were hired to write the help for Microsoft HTML help, because

the current documentation is so glaringly sparse!

I'm admit I'm not a genius, but I figured this out because I think in C++

terms, and 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.

Good luck all you tech-writers out there! I certainly appreciate all your

hard work, as I read your work everyday in the performance of my job.

Sean Stagner

...@winprosoft.com

Thanks Sean

Page updated

Report abuse