In Microsoft HTML Help CHM files 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 HTML Help. 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.
Master projects in runtime HTML Help (CHM) projects
In modular HTML Help (CHM) projects in which the child projects are merged in runtime mode, the master project must contain at least one topic and the default topic must be set in the master project. If you don't do this you will get an error opening the main CHM and the indexes of the child CHMs won't be available. (This is caused by uncorrected bugs in the Microsoft HTML Help system.)
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 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 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 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 . You need to set the same global window name in all projects in the modular help system, including the master project.
If you use this option the global help window name must begin with $global_, followed by an identifier consisting only of alphabetic characters. You must use the same global name in all the projects.
Examples of valid global window names:
$global_main_mycompany
$global_widgethelp
Important – make sure your window name is unique!
Don't use the standard $global_main name! If you do it is quite possible that some other software on the user's computer will also be using that name and then your help could open in their help window!
|
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 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 section of the child module in the Project Explorer and select
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.
|
See also:
Modular Projects (Reference)
