In HTML Help (CHM) you can create genuine modular help systems with separate help files that are displayed in a single TOC at runtime (when the user views them). Alternatively, you can also combine all your modules to one large help file.
See Choosing the merge method for instructions on how to set the different merge methods for HTML Help.
Publish time merging – one integrated help file
Publish time merging generates one single help file from all your module projects. From the point of view of your output this is no different from working with one single project without modules. With this method the project is only modular while you are working on it, your output is exactly the same as that produced from a single help file without modules.
One of the more practical advantages of publish time merging is that all the modules, including all the child modules, are published in a single quick process when you publish the master project. You don't have to open and publish every module separately as you do for projects configured for runtime merging.
In publish time merging Help+Manual combines all the modules and
creates one big help file when you publish the master module. If you
want to exclude a module you must republish without the module.
Runtime merging – separate help files
When you generate separate help files for each module in your project this is called runtime merging: When the user "runs" the help the separate help files are "merged" and displayed in a single help viewer with a single Table of Contents (TOC) containing all the topics of all the available modules.
Runtime merging produces genuinely modular help systems in HTML Help. The master module containing the main TOC must always be present, but you can include or exclude the other modules from the help simply by including and excluding the help files of the child modules from the directory in which the help is stored. If a module's help file is not present its topics are simply not included in the TOC.
The great advantage of this is the enormous flexibility it gives you. With a little planning you can reduce the work involved in distributing different versions of your help for different versions of your product to almost zero. All you need to do is include or exclude help files from your distribution package.
| Important: | The project filenames and the output filenames of your 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. |
With runtime merging you create separate help files for the master and child
modules (each module must be compiled separately). Help files that are not
present on the user's computer are automatically excluded from the TOC.
Mixing runtime and publish time merging
You specify whether child projects are to be merged at publish time or runtime when you insert the project in the master project. Since this is specified separately for each project it is possible to mix runtime and publish time merging. However, you need to be careful when you do this as it is quite easy to lose track of what you are doing in complex projects with a lot of modules.
Global help window names for runtime merging
When using runtime merging it is advisable to define a global "window name" for all the projects in the modular help system. This improves the performance of links to your help from your applications. When you define a global help window, all calls to the help system will open in the same CHM help viewer. Without a global window, you will get additional help viewers opening when calls are made first to one module and then to another.
The global help window option is set in Configuration > Publishing Options > Microsoft HTML Help > Help Windows. You need to set the same global window name in all projects in the modular help system, including the master project.
Exporting runtime modules to other formats
When you insert a module in runtime mode it will only be published to HTML Help (CHM). If you want to publish 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 published 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.
Advantages and Disadvantages of the Two Merging Methods
The following table summarizes the pros and cons of the two merging methods. Remember that runtime merging is only possible in HTML Help (CHM).
Runtime Merging |
Publish Time Merging |
|||
|---|---|---|---|---|
Advantages |
Disadvantages |
Advantages |
Disadvantages |
|
Truly modular, dynamic help systems. Different versions can be created simply by including and excluding help files in your distribution without re-publishing. |
All the component modules must be published separately. |
Single help file, exactly like those produced from single Help+Manual projects. All the component modules are published automatically in a single quick process. |
You must republish to produce different versions of the help for different product versions. |
|
Duplicate topic IDs and context numbers in modules are not a problem because the output files are truly separate. |
When creating links to the help from your application you must always be careful to link to the correct help file. |
Links to the help from your application are always to the same help file. |
You must be careful to avoid duplicate topic IDs and context numbers in different modules because the modules are merged to a single help file. |
|
Invisible topics of all modules are included automatically because the child modules are published separately. |
Multiple files that must be distributed instead of a single help file. |
A little easier to manage because you can handle all the projects as if they were a single project. |
|
|
See also:
