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

Many thanks to 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

• Large help systems can be broken into smaller sub-systems while still presenting a single help system to the user.
• Merged help is 'smart'. Only those modules installed will show in the help window.

Modular help problems

• Cross module hyper-links need special formatting.
• HH 1.2 does not merge the Favorites tab items.
• Bookmarks in the TOC don't work (hopefully fixed in HH 1.3x).
• All chm files must be compiled with "non-Binary TOC" and "Binary Index". The old MSDN chms were different.

Back To Top

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:

• If you open any CHM you will get the same thing, a single unified help system with common TOC, Index and Search
• SiteB is configured to show the SiteB TOC as default. A second window definition is used to show the full TOC.
• Each module has a different window title. In the final project you would probably want to make all titles the same so that the user is unaware that they are using a modular help system.

1. Download the demo project (merge.zip - code for this demo).

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

Remember the 3 steps.

1. The Master.HHC TOC file should "include" all other HHC files.
3. Master.HHP should have a [Merge Files] section listing all other
4. CHMs. This merges all Index (.HHK) and FTS (Full-text search) at runtime.
5. Optionally, each slave .HHP project can also have a [Merge Files] section listing all other
6. CHMs. This makes a slave have the same Index and FTS as the Master.
7. 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:
8. TP=,"masterCHM::\masterHHC", "my.HHK", "myHomePage.htm"....

Back To Top

Back To Top

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.
4. - 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.
5. - Also Rick Stone reminded me that the Master index must contain at least one index term in order for the merge to work.
6. Similarly "Binary TOC" must be _disabled_ otherwise merge will not work.
7. 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.
8. 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.
9. 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>.
10. 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

| Simple Links | ALinks | ALinks 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

• ALinks don't need to know the target CHM where the topic resides.
• ALinks have no text to translate. The identifier is invisible to the user.
• ALinks can be made to perform like a normal hyperlink.
• Create dynamic See Also jump lists. Only installed modules will contribute to the jump list.
• Can display an alternative topic if the primary link is not found.

Disadvantages

• A pain to setup. Each target topic requires special code.
• In large help systems if the target CHM is not specified, then there may be a small delay while help searches for matching topics.

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

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

• Simple to setup. No Special code required in the target document.
• Can display an alternative topic if the primary link is not found.
• Displays HTML Help secondary windows.
• In fact Relative Topics may be the only way to show secondary window in HH 1.2.
• Can be activated from a standard hyperlink.
• For single item jumps you can bypass the normal popup jump list.
• For single item jumps there is no text to translate.

Disadvantages

• For multiple item jump lists text translation is required.

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.

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

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.

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.

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.

• Context Ids in Merged Help

Back to Index | Back To Top

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.

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

1. IE window using target="label"
   1. 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.
   2. Example: <a href="somepage.htm" target="_blank">Click me</a>
   3. Click me to see an example
2. window.open()
   1. This method also opens an IE window but you gave control over size and look of the window (hide toolbars, status line etc).
   2. Example: window.open("Sample.htm",null, "height=200,width=400,status=yes,toolbar=no,menubar=no,location=no");
   3. See MS Web Reference.
3. Other methods
4. window.showModelessDialog()
5. window.showModalDialog()
6. window.showHelp()

See also my rough notes on using ShowHelp()

Back To Top

Back To Top

Great Tips from George Farkas

(Nice overview from George Farkas)

Great Tips from -- Sean Stagner

(How to setup context help with merge. Includes a RoboHelp 2000 perspective)

Tip from Kelly Holmes

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

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

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

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

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