Merged Microsoft HTML Help (CHMs)

What's covered?

This page should be read in conjunction with the page for main instructios for merging help. It covers only what is different with merged Microsoft HTML help and was written for the Classic versions of RoboHelp. Some of the content though will remain valid for the new UI versions.

See Merged_Help for further merged help information.

CHM filenames

Avoid the use of underscores, the hash symbol and suchlike in the names of the CHM files you create. They have been found to cause problems with merged Microsoft HTML help. Stick with alphanumeric characters and no spaces.

Structure

You do not have to use the same structure as is described in the Merged WebHelp content above. Nevertheless, I recommend that you do as it does keep things tidy and it will also help if you have to create WebHelp at some point in the future.

The reason you do not have to apply the same structure is that the links between topics in different child projects are created in a different way, as described below. The link is relying on the name of the CHM file and the location of the topic within the target CHM file. It does not require the relative path.

Setting up the merge: Parent project redirect

You do not need the redirect topic described in Step 5 of the WebHelp instructions, indeed you must not use that method for this type of help. You will need a parent with at least one topic that is seen by the end user and is set as the default topic.

• If you are only creating merged Microsoft HTML help, then create a normal topic instead of creating the blank redirect topic.
• If you are creating both types of merged help, then create two default topics and apply conditional build tags to them so that only the required one is used in each output.

Setting up the merge: The parent project TOC

When setting up the parent TOC for merged WebHelp, as described in Step 5 above, it is not necessary for the child projects to have been generated. All that matters is that the child projects have been created.

• When merging Microsoft HTML help, it is necessary for the CHM files to have been created before you set up the parent TOC.
• I still recommend you generate the CHM files to a folder outside of any of the projects; the generate folder, in my example. In the first page of the wizard, make sure you generate the output from all the projects into that one folder or the merge will not work.

After you have generated each CHM file to this folder, open the parent project and click the HTML tab shown in Figure 6 and browse to the folder where the CHM file was generated and select each CHM file in turn. When prompted, click Yes and allow the CHM file to be imported.

If you are using RoboHelp 7 or later and have to create both types of merged help, you can have more than one TOC; so you could create one for the WebHelp layout and one for the Microsoft HTML help.

Finally, generate the parent project to the generate folder. If you open that CHM file, you should see your merged project. The merge is set up, and links can now be created between the projects.

Links between topics in different projects

The links between topics in different projects are created in a different way, which is bad news if you have to create both merged WebHelp and merged Microsoft HTML help. If you need to output both types of help, you will have to create both types of link and then apply conditional build tags.

To create cross-project links, you need to have your default layout set to Microsoft HTML help. Then, when you click the Link To field in Figure 5. you will see an additional option, Remote Topic. When you select that, you will be asked if you want to import the target CHM file into the source project; you must select Yes. Choosing the topic to which you want to link is straightforward.

If you do not pause to get your mind around this part of these instructions, you could become confused later in the development of your help when you want to create more links:

• Before you added the reference to the child projects in the parent TOC, you had to generate a CHM file for each project to the generate folder. So that folder has a copy of each CHM file that exists in the merge.
• When you added each child CHM file to the parent TOC, that imported a copy of each CHM file into the parent. So the parent root folder has a copy of each CHM file that exists in the merge as well as the generate folder.
• When you created the first link from one project to another, a copy of the CHM file was imported. So now each project has copies of some or all of the other projects' CHM files.

Now, you want to create another link to a topic in one of the other projects; to which CHM file do you navigate?

• If you have already created a link to a topic in the target project, when you select Remote Topic to start the process of creating the link, the CHM file you imported earlier will be the default offered. The easy option is to select that CHM file. If you know the topic is in that CHM file, that's OK. If it is a topic that has been added since, then you have to go to the target project and generate a new CHM file to the generate folder. Then, in the project where you want the link, you now select Remote Topic and browse to the newly generated CHM file. That version will get imported, and you can then select your topic.
• If in doubt, update the CHM files in the generate folder regularly and always browse to those copies.

Right now that may sound very confusing, but once you have created a few links, you will find it much easier. In short, as long as the copy you browse to has the topic you want to link to, it shouldn't matter which one you use when creating links.

The Index

In a merged CHM setup, the index of the parent project must contain at least one index term. The indexes in all the projects must be binary indexes.

What you supply

You supply the parent CHM file always and whichever child projects you want the user to have. You take the copies from the generate folder, and they must always be in the same folder on the user's PC. If a CHM file is not in that folder, it will not appear in the TOC, its index entries will not display, and the topics will not be found by the search.