HTML Help - Using Merge

| Overview | A Demo Project | Step 4? | $Global_ |
| Other Tips & Tricks | Linking Between Modules | Context Ids |
| Secondary Windows | Other Secondary Windows
| Known Bugs | Others Say |

Last update: 1-Jan-2004 (updated Context Ids)

See also: Belarusian Translation (thanks Bohdan Zograf)


Overview

This document will help you to get merged CHM files working.

Many thanks to Michael (the wiz) Müller-Hillebrand in Germany for making it work when all the others couldn't. Also to Kate Pearson at Varian Australia for the word-smithing.

Modular help benefits

Modular help problems

Back To Top


A Demo Project

The following demo project will be used to illustrate how CHM files can be merged. The demo project consists of the following:

1x Master chm file (Master.chm)
2x Slave chm files (SiteA.chm & SiteB.chm).

When you open the demo project, you should see the following:

1. Download the demo project (code for this demo).

2. Download further demos (Another example: code & documentation).

Step 1 - Master Table Of Contents (TOC)

Lets assume we have 3 modules, each with its own Table of Contents (.HHC) file. The first step is to merge all of the 'slave' .HHC files into the 'master' .HHC file (We are calling the Master module, the module the others merge into).

Instructions:
Step 1a:
Open the Master.HHC (master contents file) by double clicking it in Explorer. This will open HH Workshop and enable you to edit Master.HHC.

Step 1b:
Right click on a TOC item and select "Insert File". Enter the SiteA contents file as "SiteA.CHM::\SiteA.HHC".

Step 1c:
Repeat Step 1b, this time adding the SiteB contents file "SiteB.CHM::\SiteB.HHC".

That's the master TOC done. The slave HHC files require no special changes.

insertfile.gif (6467 bytes)

 

Step 2 - The [MERGE FILES] statement

Open Master.HHP project file and add a [MERGE FILES] section containing the names of all other CHM files (do not add the projects own CHM file). 

Instructions:
Step 2a:
Open Master.HHP in workshop. Open the "Project Options" dialog and select the "Merge Files" page tab. Using the "Add" button, add SiteA and SiteB CHM files to the list. Do not add Master CHM.

If you want SiteA.CHM and SiteB.CHM to open the same as Master.CHM proceed to Step 2b.

Step 2b:
Repeat Step 2a for all modules. Again make sure that you don't include a projects own CHM in its own merge list.

project1.gif (2114 bytes)

project2.gif (3112 bytes)

 

The 3 HHP project files should now all contain a reference to each of the other project's CHM files.
<Master.HHP>
[MERGE FILES]
SiteA.CHM
SiteB.CHM
<SiteA.HHP>
[MERGE FILES]
Master.CHM
SiteB.CHM
 
<SiteB.HHP>
[MERGE FILES]
Master.CHM
SiteA.CHM

Step 3 - Slave Windows Definitions

If you want SiteA.CHM and SiteB.CHM to open with the same TOC as Master.CHM then these additional steps are required.

Master.HHP is straightforward and has the following window definition:
[WINDOWS]
TP=,"Master.HHC" ,"Master.HHK", "Master.htm"....

To make a slave use the master HHC Table of Contents we use the following syntax:

"masterCHM::\masterHHC".

windowtypes.gif (5268 bytes)

Master CHM window definition.

SiteA

We have given SiteA, two window definitions.  Use "TP=" to use the master CHM TOC.  Use "TP2=" definition to use the SiteA.HHC TOC.

You can create as many window definitions as required.
 

<SiteA.HHP>

[WINDOWS] 
TP=,"Master.CHM::\Master.HHC", "SiteA.HHK","index_a.htm"....

TP2=,"SiteA.HHC","SiteA.HHK", "index_a.htm","index_a.htm"....

SiteB

The SiteB "TP" window definition displays the SiteB TOC. To view the master TOC for SiteB use the "TP2" window definition.

Note: The .HHP file "Default Window=TP" sets the window definition to use when the CHM is opened.

<SiteB.HHP>

[WINDOWS]
TP=,"SiteB.HHC", "SiteB.HHK", "Index_B.htm"....

TP2=,"Master.CHM::\Master.HHC", "SiteB.HHK", "index_b.htm"....

 

Summing Up

Remember the 3 steps.

  1. The Master.HHC TOC file should "include" all other HHC files.

     
  2. Master.HHP should have a [Merge Files] section listing all other
    CHMs. This merges all Index (.HHK) and FTS (Full-text search) at runtime.

    Optionally, each slave .HHP project can also have a [Merge Files] section listing all other
    CHMs. This makes a slave have the same Index and FTS as the Master.

  3. If you want the master and slaves to display a common TOC, then each slave .HHP window definition should reference the Master.HHC stored in the Master.CHM file:

    TP=,"masterCHM::\masterHHC", "my.HHK", "myHomePage.htm"....
     

Back To Top


Step 4?

Q. In a merged help system, can the application open a topic in a slave module via the master chm?
A. No.  You must specify the module that contains the topic.
EG. "slaveA.chm::/slaveA_topic.htm" .
The following wont work. "master.chm::/slaveA_topic.htm".

Yes, if you use context help ids.

$Global_

Q. How can I force all modules to open in a single window?
A. Prefix all window definition names with "$global_".
In the examples above we would use "$global_TP" not "TP".

This is what Ralph Walden from KeyWorks says about "$global_".
http://www.keyworks.net/keyhh.htm

<<<
Because of the way HTML Help 1.2 handles unnamed window types, you may still get multiple windows when HTML Help 1.2 is installed, particularly when working with multiple help systems (e.g., merged CHM files). To resolve this problem, declare a window type whose name begins with the prefix "$global_" in each CHM file. For example:

file1.chm::/file1topic1.htm>$global_task
file2.chm::/file2topic1.htm>$global_task

The $global_" prefix tells HTM LHelp that the window type can be used by any CHM file once the initial window type has been opened.
>>>

Back To Top


Other Tips & Tricks

General Tips

  1. All CHM files should be installed to the same folder.
  2. You can install any number of Slave CHMs but the Master CHM must always be installed if you want the slaves to reference the master Table Of Contents.
  3. Each project must enable the "Binary Index" in order for index merge to work.
    - A binary index will not be created if you select 1.0 as the version in the Compatibility box > Compiler tab > Project Options dialog or if the Create a binary index check box is cleared.
    - Also Rick Stone reminded me that the Master index must contain at least one index term in order for the merge to work.
  4. Similarly "Binary TOC" must be _disabled_ otherwise merge will not work.
  5. Include HHC works recursively, so you can have groups of optional modules.  I.E. HHC files including HHC files that include other HHC files and so on.
  6. Merging of Index and ALink keywords. This does _not_ work recursively,  because they do not know about the TOC inclusions. If you want to have a  unified Index or cross-module ALinks you have to tell every CHM file which others might be available belonging to the same project. Again: Do _not_ merge yourself.
  7. Another idea: If you have identical keywords from several files, HTML Help uses the <title> tags in the list of targets. We extended the title of each topic with the title of the module itself (the "book"), leading to:  <title>This fine topic title (This fine book title)</title>.
  8. An include statement in a HHC file can refere to a standalone HHC file. The HHC file should be placed in the same folder as the CHM files.

Back To Top


Linking Between Modules

| Simple Links | ALinksALinks Tutor | Related Topics | Related Topics Tutor |


Simple Links

Use the anchor link for simple inter-module links.

Example: <a href="ms-its:SiteA.chm::/Index.htm">Link Text</a>

Tip: IE3 developers should use the "mk:@MSITStore:" prefix

This method is OK if the CHM is definitely installed, however some modules of a merged help system may not be installed.

Back to Index


ALinks

Assign an identifier to any topic in your help system and link to the topic using that identifier.  If more than one topic shares the same identifier then the link will display a jump list. The real power of ALinks is that they do not require you to specify the name of the target CHM file. Nifty!

Advantages

Disadvantages

Summing up: Use ALinks to handle your See Also jump lists.  For single links, where the target CHM is known, use Related Topics (see below) which require simpler coding.

Back to Index


ALinks Tutor

1. To setup the target topic
  1. Open the target HTML document in Workshop.
  2. Position the cursor to where you want to insert the code.
  3. Select "Edit > Compiler Information" from the main menu.
  4. Select "ALink Names" page tab from the "Compiler Information" dialog.
  5. Click Add button and enter a unique text id for this topic. Example: "my_topic_id".
  6. Click OK and OK to accept these changes.

The following code is inserted into your document

<Object type="application/x-oleobject" classid="clsid:1e2a7bd0-dab9-11d0-b93a-00c04fc99f9e">
<param name="ALink Name" value="my_topic_id">
</OBJECT>

 

2. To create the link to the topic
  1. Open the HTML document in Workshop.
  2. Position the cursor to where you want to insert the link code.
  3. Select "Tags > HTML Help Control" from the main menu.
    Alternatively click on the Wizards hat in the toolbar.
  4. Select "ALink Search" from the dropdown and enter a unique name.
    EG. "my_alink"
  5. Click Next and fill in the other fields.  Make sure add the ALink name you defined in step one.

The following code is inserted into your document

<OBJECT id=my_alink type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=4,73,8252,0">
<PARAM name="Command" value="ALink">
<PARAM name="Item1" value="">
<PARAM name="Item2" value="my_topic_id">
</OBJECT>

Lastly if you chose to define a button link then the job is done. Compile, open and test your CHM.

If you want to activate the code from a link then use
<a href="javascript:my_alink.Click();">Some Hyper Text Here<a>

Special Note:

To divert the user to another page if the link fails then add the following optional line to the above code.

<PARAM name="Default Topic" value="filenotfound.htm">

This tip was provided by "Marta Arriazu" <M.Arriazu(AT)Lantek.es>
Thank goodness someone reads the documentation.

Back to Index


Related Topics

Don't let the name fool you.  These links are simple to code and are perfect for creating inter-module links.

Advantages

Disadvantages

The next section will show you how to code related topics.

Back to Index


Related Topics Tutor

Here's how to setup a Related Topics link using Workshop. Once you know what you are doing you can simply paste the code into any HTML editor.

1. To Add a Link
  1. Open the HTML document in Workshop.
  2. Position the cursor to where you want to insert the link code.
  3. Select "Tags > HTML Help Control" from the main menu.
    Alternatively click on the Wizards hat in the toolbar.
  4. Select "Related Topics" from the dropdown and enter a unique name.
    Example: "my_link"
  5. Click Next and uncheck options to use popup lists and dialogs
  6. Click Next.  If you are using a button link then enter the button text and click Next again.

From the add / edit links page. Click add to open the "Add/Edit Related Topics" dialog.

  1. Enter any title text. It will never be seen, since we are only entering one link and have disabled jump popups and dialogs (above).
  2. Enter the File/URL
    Example: "SiteA.chm::/Index.htm"
  3. Enter an Alternate URL and click OK to accept the changes.
    Example: "CHMFileNotFound.htm"
  4. If you want to display the topic in a secondary window then enter the window name. Note: The window definition must be set up in the target CHM not the calling CHM. Click Next and Finish.

The following code is inserted into your document

<OBJECT id=mylink type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=4,73,8252,0" width=100 height=100>
<PARAM name="Command" value="Related Topics">
<PARAM name="Button" value="Text:Relative Topic Jump">
<PARAM name="Item1" value="This text never seen;SiteA.chm::/Index.htm;CHMFileNotFound.htm">
</OBJECT>
 

8-dec-2005:

Removed the ms-its: or mk:@MSITStore: prefix. This causes a popup error in newer versions of HTML Help. Here's the old code:

<PARAM name="Item1" value="This text never seen;ms-its:master.chm::/topic.htm">

2. Lastly if you chose to define a button link then the job is done. Compile, open and test the CHM.

If the target CHM file is not installed the help system will display the Alternate file "CHMFileNotFound.htm" where you can tell the user how to install the extra help module.

If you want to activate the code from a normal hyper link use
<a href="javascript:mylink.Click();">Some Hyper Text Here<a>


Merge & Context Help IDs

We all know how to set up our projects for Context calls from the main application (see how_to_context.htm). People tend to come unstuck with merged help systems. ie. How does an application make a context call to a slave topic though the master CHM.

The following examples show context mapping info from a Master .HHP file.

Bad Solution #1:

This will fail. The system assumes that the topic is in the current CHM (Master).

[ALIAS]
IDH_MyTopic=slave1_topic.htm

[MAP]
#define IDH_MyTopic 1000

Solution #1:

The ULR contains the full path to the slave topic. Since the latest critical update (hhctrl.ocx 5.2.3735.x) we have found that the indexes do not merge using this technique. Only the master index shows in the index navigation page tab.

So this is a good solution if you do not use an index tab. Also Marc Islam (MSFT) points out that you must use $Global_ if you want TOC auto-sync to work correctly.

[ALIAS]
IDH_MyTopic=ms-its:SlaveA.chm::/slave1_topic.htm

[MAP]
#define IDH_MyTopic1000

Solution #2:

This strange URL format fixed our TOC auto-sync problem for a while. However since the latest critical update (hhctrl.ocx 5.2.3735.x) TOC auto-sync is completely broken even when using $Global_. Recent tests by various authors also reveal that some days the Index merges correctly and some days it does not -- We can't explain this discrepancy in results. So stick with Solution #1 if you have no index.

[ALIAS]
IDH_MyTopic=ms-its:master.chm::/SlaveA.chm::/slave1_topic.htm

[MAP]
#define IDH_MyTopic1000

Solution #3:

You could configure each slave CHM to use the Master TOC and merge with all other CHMs (We showed this in Step 3 of the Demo Project above). Thus each Slave when opened directly will have the same content as the Master.  Define all your Slave1 mappings in Slave1 .HHP and open Slave1 CHM when making a context call to a Slave1 topic. Problem with this approach is your application would need to deal with several CHMs instead of making Context calls though a single CHM (master). Also information such as favourites and window size and position are not merged. This info is saved under the CHM file name.

Solution #4:

1-Jan-2003: Finally some solutions that work.

Back to Index | Back To Top


Secondary Windows

Secondary windows  are a snap when using Related Links and TOC Links. Simply fill in the name of the Window Definition you want to use using Workshop.

Note: Secondary window support broke in HH 1.2 for ALinks and KLinks. The word is that they are fixed again in HH 1.21.

Before reading further you should read the section above on Related Topics.

Q. Do secondary windows work in a standalone CHM?
I can only link to a secondary window if the target is a different CHM.
A. Always specify the target CHM file in the path, even if the source and the target CHMs are the same.

Example:

I want to link from a topic in master.chm to another topic in master.chm using the window defined as "TP2". The link path should be set to "ms-its:master.chm::/topic.htm".

<OBJECT id=mytopic5 type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=4,73,8252,0">
<PARAM name="Command" value="Related Topics">
<PARAM name="Button" value="Text:Relatve Topic - Secondary Window in same CHM">
<PARAM name="Window" value="TP2">
<PARAM name="Item1" value="This text never seen;master.chm::/topic.htm">
</OBJECT>

8-dec-2005: Removed the ms-its: prefix. This causes a popup error in newer versions of HTML Help. Here's the old code:

<PARAM name="Item1" value="This text never seen;ms-its:master.chm::/topic.htm">

Q. How do I display my own error message when a link fails because the CHM is not found?
A. Fill in the Alternate URL field. 

With Related Topics and TOC entries you may specify an Alternate URL link. If the primary link fails because the module is missing then the Alternate file is displayed.

For ALinks and KLinks you need to add this line by hand. Workshop does not help you to do this.

<PARAM name="Default Topic" value="filenotfound.htm">

Q. Will the secondary window fall behind the main window?
A. No the secondary window will stay on top.
You may be able to effect the window behavior by changing the window definition style.
Q. Can I remove the button bar and/or the page tabs from the secondary window?
A. To remove the button bar go into workshop, edit the window definition and uncheck all button options. To remove the page tabs do the same and switch off the navigation pane.
Q. Where should I define the window definition. In the calling module or in the target module?
A. Always define it in the target chm containing the topic.
Q. I always get a "Window Type XXX not found" error?
A. Try prefixing all window type names with "$GLOBAL_".

<PARAM name="Window" value="$GLOBAL_TP2">

Q. When I click my create secondary window link a second time, the topic displays in the main window not in the secondary window. What's happening?
A. In some situations you need to first close the secondary window.

Other Secondary Windows

Forget about multiple CHMs for a second and lets quickly look at other ways to produce secondary windows. 

  1. IE window using target="label"

    The easiest way to show a secondary window is to set a target. Especially useful when linking to pages on the internet where you need status bar info.

    Example: <a href="somepage.htm" target="_blank">Click me</a>

    Click me to see an example

  2. window.open()

    This method also opens an IE window but you gave control over size and look of the window (hide toolbars, status line etc).

    Example: window.open("Sample.htm",null, "height=200,width=400,status=yes,toolbar=no,menubar=no,location=no");

    See MS Web Reference.

    Click me to see an example

  3. Other methods

    window.showModelessDialog()
    window.showModalDialog()
    window.showHelp()

See also my rough notes on using ShowHelp()

See also the great examples (HelpTips.zip ) by Simon Jones.

Back To Top


Known Bugs

1. HH 1.2 does not merge the Favorites tab items.
2. Merged help HHC and HHK items containing Bookmarks don't work.

There appears to be a problem with linking from HHC and HHK items that contain bookmarks (in merged help systems). Links from the TOC and Index tabs will open the file up in the right hand pane, but will not jump down to the specified bookmark.

I actually have no problems with the Index tab "as long as I do not have spaces in the bookmark name". Others report that all is OK when opening the CHM containing the bookmarks but if other modules
are opened then the links fail.

Hopefully fixed in HH 1.21

3. RoboHelp creates bad HHC and HHK files.

May or may not be a problem.

4. Window definitions

Leta Herman was getting errors whenever she clicked on TOC items. We found that if we removed lines like
<param name="WindowName" value="Main"> from all the HHC and HHK files it helped.

5. Adding HHC Include statements

There is a bug in HTML Help Workshop that makes editing a HHC file very difficult.
The bug is this. The Include items should be displayed one step to the right.

Example:

The following will pull the include file in at TOC level 3 instead of TOC level 2 as specified.

Folder
    Folder
    Include CHM::\HHC
Folder

The biggest problem here is that we cannot include files at TOC level 1.  It just doesn't work.

The Fix:

  1. To get includes to show at TOC level 1 you must edit the HHC in notepad and make sure that the include statement is outside the <UL> tag block.

    Example:

    <UL>
    ...
    </UL>
    merge info
    <UL>
    ...
    </UL>

  2. You can use a 3rd Party tool that does the job properly.

    Example: Virtual Media's HDK or FAR V2.0.5
    See http://helpware.net/FAR/index.html

Back To Top


Others Say

Great Tips from George Farkas <george(AT)NOSPAM.DRTAX.CA>
(Nice overview from George Farkas)

 

Great Tips from -- Sean Stagner <stagner(AT)NOSPAM.mediaone.net>
(How to setup context help with merge. Includes a RoboHelp 2000 perspective)

 

Tip from Kelly Holmes<kelly.holmes(AT)NOSPAM.ni.com>
Kelly Holmes notes that when you click on a link to another CHM module, the link color does not change to the visited color. There is no fix that we know of.

 


From: "Leigh, Daniel" <daniel.leigh(AT)NOSPAM.sterling.com>
Subject: Merged help file tip
Date: Wed, 19 May 1999 18:03:50 -0500

Robert,

A further refinement to your merged help file tips. Maybe you know this already, but I recently discovered that the [MERGE FILES] section accepts #include statements. So you can say:

[MERGE FILES]
#include MyFileList.txt

Now you only have to maintain one list of merged files and just #include it in each project.
(Your instructions on the web page explicitly state not to include a project's own CHM in its own merge list. I'm not sure why: I haven't discovered any problems with it so far).

 


From: "Mills Perry" <Mills_Perry(AT)no_spam_aal.org>
Subject: Merged helps on Read-Only Media
Date: 07 Oct 1999 

When you open a merged compiled help file (.chm) for the first time, it creates in the same directory as the .chm file an index file with a .chw suffix. The .chw file contains merged kwords. The CHW file will not be created if HTML Help cannot write to that directory. Without the .chw file, your index tab will not display a merged index if you have multiple .chms, and your included TOCs will not include. Other things may not work properly either, but these are the most visible issues.

HOW TO PROPERLY PUBLISH READ-ONLY

1. You need to create the .chw file by opening the master .chm file. You can do this in multiple ways:

a. Open the master .chm in your development environment and move the generated .chw along with the new/changed .chms as part of your company's change management process.
b. Have somebody with write access to the network directory where the production .chms reside manually open the master .chm file to generate the .chw.
c. Write a program to automatically regenerate the .chw after any.chms get changed. This program just needs to call the HTML Help API to display the master .chm's index, and pause long enough for the index to generate before terminating.

2. The .chw must be regenerated any time any merged .chm is updated, no matter how trivial the update. If this is not done, your TOC includes  will fail, and your indexes will not merge.

<From Rob Chandler> 

A couple of things to add to this CHW discussion

1. If you do not have an Index tab or Keywords then chw files are not produced.

2. You must click on the index tab to create the CHW file.

3. If your slave CHMs contain klink/index merge then these must be run once as well to create their CHW files.

4. MS HTML Help creates the chw file uncompressed (for speed). However they can be compressed. A 50MB MSDN CHW file is reduced to 5MB. Compression simply removes the dead space from the IStorage file. The shareware utility FAR can compress Chw files.

 

Back To Top


From:    Yuko Ishida <ishida(AT)NOSPAM.KEIYU.COM>
Subject: HH 1.3+CSS+multi-print
Date:    Sun, 20 Feb 2000 14:22:18 +0900

Robert Chandler:  Great tip from Yoko for getting multi page printing to work under HH1.3.

Toying with Windows 2000 Help, I noticed that the topic is linked to css files with MS-ITS syntax.

<LINK REL="stylesheet" MEDIA="screen" TYPE="text/css"
HREF="MS-ITS:ntshared.chm::/coUA.css">

Eureka! I created the following help and linked html files to test.css.

test.hhp
test.chm
         -html folder
             -topic1.html
             -topic2.html
         -css folder
             -test.css

<LINK REL="stylesheet" TYPE="text/css"
HREF="MS-ITS:test.chm::/css/test.css">

And css works in multi-page print mode. Apparently this only works with HH 1.3. When I try the same method with HH 1.21, multi-print fails. 

One of very few virtues of 1.3?

 

Back To Top


From: "Matthew Ellison" <matthew.ellison(AT)email.com>
Subject: Any way to disable the context menu for the HTML Help TOC?

--My testing showed that the maximum number of files that you can merge
(i.e. the maximum number of files that you can list within the [Merge Files] section of the .hhp file) is 1148. Any higher than that, and the compilation breaks down. This seems rather an arbitrary number -- do you know if it depends on the resources of the computer on which you are compiling?

Rob: My guess is if you went to an XP Pro PC with more memory you would get further ;-) Ralph?

--Consider the following merged HTML Help system

main.chm
sub.chm
*sub.chm (where * is any set of characters)

sub.hhc and *sub.hhc are included within main.hhc. Only sub.chm is listed within the [Merge Files] section of main.hhp. If you compile, select any topic from *sub.chm from the merged TOC, and then attempt to select any topic from sub.chm the topic is not found.

The moral is either ensure that you list all sub-CHMs within [Merge Files] or avoid naming pairs of sub-CHMS in this way
name1.chm
*name1.chm

Rob: Thanks Mathew. Interesting: yes renaming files, rebooting all help when weird things happen. :-)

Rob: PS. More info... Paul O'Rear [MS] queried some of the guys who used to work with HTML Help collections (Visual Studio 6). The most the help team ever merged was around 800-900. They never saw a problem with this number. Also Chris from Emerson reports that search of slave text failed after adding 1105 items to the [MERGE FILES] section of the .HHP project file. He was testing with only a few CHMs. So the problem is the Compiler (Workshop) rather than the runtime system.

Back To Top