Download
RoboHTML 2000 Source Files (234K)
|
||||||||||||||
|
This TOC hides a merged help system |
|
|
|
The compiled TOC shown here is a bit of sleight of hand. It appears to be a single TOC of "Books and Pages". It is actually a combination of three separate .chm files that have been merged. The books, Merge 1 and Merge 2 are actually merge1.chm and merge2.chm that show up in the TOC of a third "master" file we've called mergemaster.chm |
As more authors discover the benefits of creating modular help systems by merging indexes and TOCs of multiple help projects, some have hit the wall on how to pull it off. RoboHTML ver. 7 required that you hand-edit your .HHC and .HHP files and summon HTML Help Workshop to recompile the work. (See this RH version 7 merge procedure here.) Thankfully, RoboHTML 2000 makes this unnecessary. However, getting the TOC to display the books and pages the way you would expect is a little more involved.
We'll go through the steps and show you the pitfalls and workarounds along the way.
1. What is a master help project and why would you want one?
As noted in the RoboHELP 2000 help file, "You can create a master help project that includes individual projects combined together. This feature is useful if you have several writers working on individual projects that must be combined into a larger, master project."
Each individual .CHM file remains its own help project, but the tables of contents and indexes are combined. The books and pages in the TOC file (.HHC) are merged and when users select a page, the topic it is linked to opens in the HTML Help viewer. The keywords in the indexes are combined into the master help project's index and sorted alphabetically. When users select a keyword from the index, the appropriate .CHM file is displayed in the HTML Help viewer.
This strategy can be useful:
-
When you want to issue "updates" to a help system
-
When customers purchase additional "plug-ins", add-ons, or applications that are part of a suite.
-
When different persons or teams work on smaller parts of a larger help system or knowledge base.
2. Combining Table of Contents (TOC) files:
Keep the following in mind when using external TOC files with master projects:
-
Use underscores instead of spaces: The names of secondary .CHM and .HHC files cannot include spaces.
-
Beware Binary confusion: Unlike merged indexes which are saved in binary format, external TOC files are not saved in binary format in the Master .CHM. However, they don't have to be binary in the sub-CHMs.
3. In the "Mergemaster" project:
From File | Project Settings | Index tab, check Binary Index.
4. From File | Project Settings | TOC Styles tab, Uncheck Binary TOC.
5. Under the Project Settings | Advanced tab, Add each .chm to be merged
6. Secondary chms are copied to the master project folder.
After Step 5, if you look in the Windows Explorer, you'll see that each secondary .chm file has been copied from its project folder into the "master" project folder (here shown as Mergemaster). For mergers to work, all chms in the system must be in the same folder.
7. From the File | New | External TOC menu, Add External TOCs to the master project
8. Important: With the TOC Composer tab selected:
Click File | New | Book and create a book for the Master TOC even if you don't have any "pages" in the master project.
9. The TOC Takes Tweaking
The RoboHTML Online Help topic (Combining contents (TOC) files) cautions: "External TOC references cannot stand as their own top-level books in the master project's table of contents. If you add them at the top level, they will not work properly from the Contents tab in the HTML Help viewer." It will take experimenting with "drag 'n drop" or using the arrow icons to get your final TOC to behave the way you want it.
10. Add at least one Keyword in the Master Project Index or else the Indexes will not show up for the rest of the .CHMs!
This can be very frustrating because it depends on the version of HHCTRL.OCX you're using. Versions prior to 1.3 did not require this step. Somehow, this extra step crept in with the 1.3 and 1.31 versions. Find out the version on your computer
Anything lower than 4.74.8702 is older than 1.3. For more info, visit Robert Chandler's Helpware.
11. Here's what it should look like:
|
This in the TOC Composer... |
Looks like this in the .chm |
|
|
|
12. Watch out for pages "outside" of books
Do not merge external TOCs that have "pages" outside books.
13. Nice to know:
If you recompile a "sub" .chm, you do not need to recompile the master file as long as you copy the "sub" .chm files into the master folder.
14. Back up your HHC! TOC Composer often forgets your settings after you close and reopen your project.
Good News! The TOC Composer
corruption (described below) has been fixed
in
RoboHELP Office Version 9
Word from eHelp Corporation (formerly Blue-Sky Software) is that "there is a problem with the .chm displaying merged .hhc files underneath other books. This occurs when including external .hhc files in the TOC using RoboHelp's TOC tool.
"The best results can be obtained by merging the files the same way as version 7 (by editing the .hhc files manually). However, you don't need to compile with HHW (Microsoft Compiler) as long as you don't edit the contents again in Robohelp 2000. Once you edit the contents, the .hhc will be corrupted again. Keep a backup of the .hhc at all times. This should help with the loss of your changes in the .hhc when closing the project.
While we submit issues to R&D which are reviewed and considered for future releases, we still are limited by the MS compiler (HHW) on some problems related to the TOC display."
