More Advanced Procedures > Working with Modular Help Systems

In HTML Help and the obsolete Winhelp format you can create genuine modular projects with separate help files that are displayed in a single TOC. This is called "runtime merging". Alternatively, you can also combine all your modules to one large help file, just like the output from a single project. This is called "publish-time merging".

Choosing the merge method is only relevant for Winhelp and HTML Help formats. All other output formats use publish-time merging only, merging all the modules in your project to create output that is exactly the same as output generated from a single project.

See Runtime and publish time merging in the Reference section for full details of the capabilities of these two different output methods for modular projects in HTML Help and Winhelp.

You can set the merge method separately for every child project you insert. You choose the merge method when you insert the child project.

Important:

The project filenames and the output filenames of the HLP or CHM files must be identical. The references between the child and the master help files are based on the filenames and if project and output filename don't match the references will be invalid.

Choosing the merge method while inserting a child project:

•	Select Merge content on publishing or Merge content at runtime when you are inserting the child project in your master project.

Changing the merge method after inserting the child project:

To change the merge method just remove the module from the TOC and re-insert it with the other merge method. You cannot change the merge method of a module without removing it from the TOC first.

1.	Select the main module item in the Project Explorer and press DELETE or select Add Topic > Delete in Project > Manage Topics. This does not delete the project on the disk, it only removes it from the TOC of the master.

2.	Insert the same module again, selecting the other merge method.

When you insert a module in runtime mode it will only be exported to HTML Help and Winhelp. If you want to export the same module to other formats you must insert it in your TOC a second time in publish-time mode. When you do this you should also set the include options for each version so that the correct version gets exported automatically depending on the output format you choose:

Setting the include options:

Just right-click on the main module "node" (spiky green icon) in the TOC, select Include in Builds in the context menu and then set the include options appropriately. Make sure that you set the options so that it is not possible to export both versions together!

You can also access the include options in Manage Topics > Change in the Project tab. See Conditions and Customized Output for more details on using include options.

In HTML Help you can specify what happens when the user tries to open the child CHM module directly instead of the master module.

1.	Open the Configuration section of the child module in the Project Explorer and select Publishing Options > HTML Help > Extended .HHP Settings.

2.	In the section If this is a child file, merged at run time select the Table of Contents you want to open when the user opens the file directly.

If you select the master file TOC option opening the child file will be exactly the same as opening the master file – the entire integrated TOC of the master file will be displayed. Otherwise the child file will open on its own, just like any other HTML Help file.

If you are using runtime merging in Winhelp you may find that the offset (indentation) of the child project's TOC within the master project's TOC is not correct. You can adjust this with the TOC offset setting.

1.	Open the Configuration section of the child module in the Project Explorer and select Publishing Options > Winhelp > Modular Help Options.

2.	Adjust the TOC Offset to the value corresponding to the indentation you want to use for the child module. A value of 1 is one level of indentation, 2 is two levels and so on..