Context Ids in Merged Help (1)
9-Oct-2003: Since installing HHCtrl.ocx Version
5.2.3735.x this technique fails. The Indexes are not merged.
Instead see the new solution at: How_to_merge_ctx2.htm.
Old solution follows...
We all know how to set up our projects for Context calls from the main
application (if you don't then see how_to_context.htm).
People tend to come unstuck with merged help systems. ie. Linking to a slave
topic using context Ids. In how_tomerge.htm#ContextHelpIDs
we suggested adding a mapping section to the master.hhp like master.chm/slave.chm/path.
However Laurence Farrugia reports that although this worked, it broke the TOC autosync.
Marc Islam (MS Program Manager, Microsoft NUI Help) explored the problem
for us and posted this excellent solution to the authoring newsgroup. It
involves using Global Window Types and duplicating the WINDOWS, MAP and ALIAS sections
across all HHP files.
|From: Marc Islam[MSFT]
Date: Wed, 20 Aug 2003 18:12:24 GMT
Subject: RE: Autosynchronize TOC in merge doesn't work
USING A GLOBAL WINDOW DEFINITION
I was able to get both Context IDs and Autosync to work using Global
Window definitions, as discussed on Step 4 of
- Both my master.chm and slave.chm define a global window definition
called "$global_mastwin". I created the window definition in master.hhp
to set up the window the way I like it. I then opened master.hhp in a
text editor, and copied the entire window definition from its [windows]
section into the [windows] section of slave.hhp.
- The URL that I specify for my context IDs do not include "master.chm::/"
in the string.
- When calling the HTMLHELP( ) API with the HH_HELP_CONTEXT command,
always specify the global window definition "$global_mastwin". This will
keep all of the navigations occurring in the same window. The URL
specified in the context ID, ms-its:slave.chm::/topic.htm" will resolve
correctly with the URL specified in slave.hhc and AUTOSYNC will work.
Furthermore, autosync will work from all other navigation points (links,
alinks, klinks, index, full text search)
Tip: A small improvement we added to our demo (download link above)
was to use #include statements in the [MAP] and [ALIAS] sections so that all .HHP
files were forced to use identical Mapping info.
Marc continues on to explain why TOC autosync breaks using ID_SLAVE1=ms-its:master.chm::/slave.chm::/topic.htm.
|ADDING MASTER.CHM TO THE URL IN THE ALIAS SECTION
As a review for others, check out :
workaround describes how to add items to the ALIAS section to get context
IDs which map to slave.chm to open in the same window as master.chm.
For example: ID_SLAVE1=ms-its:master.chm::/slave.chm::/topic.htm
WHY SYNC IS BROKEN using this method:
When you navigate to this topic using the context ID, the URL that IE
navigates to ends up being fully qualified as
ms-its:c:\windows\help\master.chm::/slave.chm::/topic.htm (you can use the
Jump To URL command from the context menu to see the actual URL used to
When HTML Help syncs to a node in the TOC, it parses the navigation URL to
get the filename and path. It will start with the first filename through
the end of the URL and use it to compare with the URLs in the TOC. To get
the sub string, it gets the filename immediately preceding the first
occurance of "::", in this case "master.chm::/slave.chm::/topic.htm"
Since "master.chm::/slave.chm::/topic.htm" does not exist for any node in
the TOC, no sync occurs.
Topic Displayed: master.chm::/slave.chm::/topic.htm
TOC Node: topic.htm
Also, when you use a context ID lookup and immediately add the topic to your
Favorites list, the navigation URL is saved, e.g.
ms-its:c:\windows\help\master.chm::/slave.chm::/topic.htm. As before, this
URL will not sync to a node in the TOC unless the node's URL matches the
GETTING SYNC TO WORK
if you use this method To get the sync to work for this topic, you can
author the node in
SLAVE.HHC to match the URL you used to create the context ID:
<param name="Local" value="ms-its:master.chm::/slave.chm::/topic.htm">
ISSUES WITH THIS METHOD
1) opening SLAVE.CHM by itself and using the TOC to navigate to topic.htm
will fail unless you add master.chm to the [MERGE FILES] section of
SLAVE.HHP *and* master.chm is available for HTML Help to load into
memory. This is because master.chm exists in the URL specified in the HHC
2) Relative links to this topic from other help topics will fail to sync
since the navigation URL will be resolved as slave.chm::/topic.htm which
won't match the URL in the TOC. For example, if slave.chm::/default.htm has
a link to topic.htm authored as <a href="topic.htm">Jump to Topic</a>, the
TOC will not sync. The href would have to be authored using the same URL <a
3) The TOC will fail to sync when the topic is accessed through the keyword
index, unless you author the topic directly in the SLAVE.HHK file *and* use
the URL "ms-its:/master.chm::/slave.chm::/topic.htm" If you are using the
compiler's default option to "Create a binary Index" *and* author the
keyword directly in topic.htm, the URL associated with topic.htm will be "slave.chm::/topic.htm",
and sync will fail.
4) The TOC will fail to sync when the topic is accessed using Full Text
Search. I haven't actually tried this, but I'm 100% convinced it won't work
<whew> I hope that all made sense. Please let me know if you have
questions about either of these two methods. Many thanks for bringing this
to our attention. I'll send mail to the Helpware folks to see if we can
update the demo.
Program Manager, Microsoft NUI Help