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.

[ALIAS]
IDH_GlossPage=ms-its:master.chm::/SlaveA.chm::/html/gloss.htm

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]
Organization: Microsoft
Date: Wed, 20 Aug 2003 18:12:24 GMT
Subject: RE: Autosynchronize TOC in merge doesn't work
Message-ID: <UNZ9ea0ZDHA.396@cpmsftngxa06.phx.gbl>
Newsgroups: microsoft.public.helpauthoring

<snip>

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 http://www.helpware.net/htmlhelp/how_to_merge.htm#step%204

  1. 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.
     
  2. The URL that I specify for my context IDs do not include "master.chm::/" in the string. 
    For example:
      Instead of: 
        [ALIAS]
        ID_SLAVE1=ms-its:master.chm::/slave.chm::/topic/.htm

      Use: 
        [ALIAS]
        ID_SLAVE1=ms-its:slave.chm::/topic/.htm
     
  3. 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 :
http://www.helpware.net/htmlhelp/how_to_merge.htm#ContextHelpIDs. This 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 navigate)

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
navigation URL.

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

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 href="ms-its:master.chm::/slave.chm::/topic.htm">

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 (no workaround).


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


Cheers,
Marc Islam
Program Manager, Microsoft NUI Help