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 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 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 |
|
