HTML Help - Merging

Merging HTML Help files

Topic status automatically displays here - do not remove.

Add me to your favorites!Bookmark this topic  Print me!Print this topic

HTML Help Workshop allows you to merge two or more compiled help files so that they appear as a single entity at runtime. There are two types of integration:

HTML help provides the flexibility to merge one or the other or both. Both use different methods of integration.

You could include a separate TOC file which displays an alternate contents, depending upon whether it is present or not. Or you could only merge the indexes and not the TOCs if you wish. When creating HTML help, we use and recommend using both together. That way we can produce individual product specific modular help which will also merge and display as one unified help if the user has more than one product module (with separate help) installed together.

The only requirement to display the modular helps as one merged help is that the individual compiled help modules (CHMs) be physically located in the same directory folder. The beauty of this system is that if a help module isn't there, it doesn't display in the merged help, so inversely, only those help modules which are present are displayed in the merged help.

Also, the merge occurs only at run-time (when the help is launched), thus allowing us to update and replace individual modules at any time without having to replace the whole kit and caboodle every time we need to update some little thing.

Note Authors Note

I thought caboodle was spelt with a "K" as in Kaboodle. Apparently not!
caboodle: (n. informal) The lot, group, or bunch; donated the whole caboodle.

In the Plant2Business project (I worked on when I was with Citect) for example, this capability was used to make the independent Installation help accessible from the installation splash screen, while also being incorporated (merged) into the Server Manager help. This eliminated the need for duplicate source files.

To enable merging of HTML help modules, both parent and child help project files must be configured to permit HTML help merging. See how to enable HTML Help run-time merging.

You merge HTML help indexes and full-text search files (if enabled) by adding a [Merge Files] section to the parent help project file using HTML Help Workshop. See how to merge HTML Help indexes and full-text search lists.

You merge TOCs by adding a merge file entry to the parent TOC file using HTML Help Workshop. See how to merge HTML help TOCs.

Important Important

Tip Tip

To link between topics across merged Help modules, use the following syntax in the link: 

<A HREF="ms-its:HelpFileName.chm::/topic.htm">

 

Back to Top

To enable HTML Help run-time merging:

To enable run-time merging of HTML help modules, both parent and child project files must have binary index files and be compatible for HTML Help version 1.1 or later.

Tip Tip

The following procedure makes changes to the HTML Help Project file (.HPJ) so you'll need to check it out of VSS if stored there.

  1. In HHW, open the help project file (<HelpProjectName>.HPJ).
  2. On the Project tab, click on the properties button (xyz).

    This will display the Project Options dialog. Click the Compiler tab.

    xyz

  3. Select "1.1 or later" from the Compatibility list.
  4. If you want the file to have full text search capability and display the Search tab in the run-time help viewer, check the Compile full-text search information field.
  5. If you want the file to collate index entries from the source HTML topics, or the index to merge with another at run-time, check the Create a binary Index field.
  6. Click OK. Save the project and compile it. Run the compiled help and view the Index tab. Confirm that it displays properly.
  7. Repeat this procedure for every HTML help module which are to be merged together at run-time. Store the compiled help modules in the same run-time folder directory.

If you wish to merge HTML help indexes and full-text search files (if enabled), see how to merge HTML Help indexes and full-text search lists. If you wish to merge TOCs see how to merge HTML help TOCs.

Back to Top

To merge HTML help indexes and full-text search lists:

Important Important

Tip Tip

The following procedure makes changes to the HTML Help Project file (.HPJ) so you'll need to check it out of VSS if stored there.

  1. In HHW, open the parent help project file (<HelpProjectName>.HPJ).
  2. On the Project tab, click on the properties button (xyz).

    This will display the Project Options dialog. Click the Merge Files tab.

    xyz

  3. Click the Add button.

    This will display the Add Merge File dialog.

    xyz

  4. Click the Browse button, navigate to and select the compiled help module (.CHM file) you would like to merge into this help project.

    Important Important

    The file you select must be located in the same directory at run-time as the Help you are merging with.

  5. Click OK, and OK again.

    The project file will now list the Help file you selected in the [MERGE FILES] section.

    xyz

  6. Save the project and compile it. Run the compiled help and view the Index.

    The first time run will create the merged index and full-text search list file <HelpFileName>.CHW in the help folder. Check that the indexes have merged appropriately.

    Note Note

    Merged index entries are case sensitive. "Server" and "server" are not the same and will display separately.

Back to Top

To merge HTML help Table Of Contents (TOC):

The merging child TOC can consist of a TOC in another compiled help, or a separate TOC file. It will only display merged in the run-time compiled help if it exists in the same folder as the parent help when the parent help is run-up.

Important Important

Tip Tip

The following procedure makes changes to the HTML Help Contents file (.HHC) so you'll need to check it out of VSS if stored there.

  1. In HHW, open the parent help project file (<HelpProjectName>.HPJ) and click on the Contents tab.
  2. Right-click on the item immediately above where you want the inserted TOC to display, and select Insert File from the popup menu. The Include File dialog will display.

    xyz Caution

    Merged HTML help files do not display an include child TOC when placed at the very top of the parent TOC. Nor does the child TOC display properly in the merged parent TOC unless the child TOC has a book as its top entry.

  3. Identify the TOC you would like to include using the following syntax: 
    HelpFileName.CHM::\ContentsFileName.HHC

    For example, the Include File dialog for the Plant2Business Server Manager Help which merged the Install help is:

    xyz

  4. Click OK. HTML Help Workshop will display a dialog indicating that it cannot find the specified file. When asked if you want to include the file anyway, select Yes.

    The example above will result in the following "INCLUDE:" entry being added to the TOC.

    xyz

    Tip Tips

    • You can use the arrows to the left of the TOC to reposition the include entry if it is in the wrong location or at the wrong level.
    • Interestingly enough, the parent TOC can contain empty book placeholders for the include child TOC, with the Include statement beneath the book. If the Include TOC file is not available, the parent book won't display. That is, it will only display if the included TOC file is present in the same help file folder at run-time when the parent help is run-up.
  5. Save the project and compile it. Run the compiled help and view the Contents.

    Check that the included TOC displays in the correct place.

Back to Top

See Also

Jump to site home page Lotech Solutions' Tips, Tricks, and Procedures

Back to Top