5 Replies Latest reply on Aug 18, 2008 1:49 PM by Dee70

    Merging CHM projects

    NL_Derek-GsBV5a Level 1
      Introduction: You want a help system distributed over several CHM files. The topic map means that you may enter via any one of the CHMs but, once in the help system, you want access to the complete ToC. RoboHelp does not provide this by default; here is how to arrange it.

      The underlying concepts: You have one "master" CHM which contains the complete ToC but no topics; and any number of "slave" CHMs containing the topics. Use baggage trick #1 to include the master ToC in each slave. Each slave ToC must be contained in a book in the master ToC (RH hhc bug), but you can have several ToCs per slave (baggage trick #2). All CHMs must use the same window and it must be a global window (prefix $global_). All CHMs must be in the same directory at runtime (Common location).

      RH hhc bug: The ToC you define in RoboHelp is stored in a file ProjectName.hhc; when you generate the project a file called ProjectName.hhc will be included in the CHM file. These two files are not the same. This means that (1) if your merged projects are not contained in books in the master ToC you will get errors (invalid HTML tag) because the hhc file inside the master CHM <ul> and </ul> tags are unbalanced. Also (2) the ToC to be included in the slave CHMs must be the one extracted from the master CHM, not the one from the master project directory.

      How baggage files work: When user runs the CHM file, its contents are unpacked to a temporary location (MSIT-whatever). These contents include the topics, images and also the baggage files. The baggage file included will be whatever is in the project directory at generate time. Not all the files in RoboHelp's baggage list will be included (see elsewhere for quirks of the baggage system).

      Decompiling CHM files: All (?) Windows systems include the program hh.exe which is run to display CHM files. You can also use this program in a DOS window to decompile CHMs; the syntax is:
      hh -decompile DirectoryToReceiveDecompiledFiles FileToBeDecompiled.CHM
      The directory will be created if necessary; old files will be silently overwritten. The same functionality is available with a pretty GUI in the HTML Help Workshop, which you can download free from microsoft.com.

      Baggage trick #1: Create all slave ToCs and generate the CHMs; include the slave ToCs in the master ToC (File > New > MergedProject). Generate and then decompile the master CHM (hh -decompile master master.chm) and include the decompiled master.hhc as a baggage file in each slave. In each slave, ProjectSetUp > Windows > $global_window > Properties > Advanced > Destinations > TableofContents and specify master.hhc (this file will be available because you included it as a baggage file). Now regenerate all slaves (see Caveat #2).

      Baggage trick #2: The slave ToC will be included in a book in the global ToC; this means one book per slave CHM. You may not have partitioned your project in this way. If necessary, create several ToCs in the slave; each ToC will result in a file xxx.hhc in the project directory. Include all these as baggage files in the slave, and generate it. When you include the CHM as a MergedProject you can select the ToC you want.

      Common location for CHMs: you can save copying by generating all CHMs in one location (SSLs > HTMLhelp > Properties > OutputFolder). I have a project directory containing subdirectory Output along with Master, Slave1, Slave2 etc.

      Caveats: (1) Browse sequences and Search are not globalized, if you open a slave CHM you will only have access to the Browse and Search of that CHM. (2) If you change the master ToC you will have to regenerate the master, decompile it, copy the hhc to each slave, and regenerate each slave (this can be automated). (3) There are apparently restrictions on using names containing underscores; I have not tested this. (4) The whole process is sufficiently complex that I recommend creating a test database to try it out.

      Conditional Build Tags: I have not tested this, but it should be possible to define several ToCs in the master and use them as appropriate.

        • 1. Merging CHM projects
          NL_Derek-GsBV5a Level 1
          Book with Link and Home button

          It is possible to use the "Book with Link" function in the Master ToC; simply link to a Remote Topic in the normal way.

          If you use the "Home" button to link to a page in the Master project you will need to add something like "Master.chm::/HomePage.htm" to the Home field in Windows > $global_window > Properties > Advanced > Destinations

          Finally an extra caveat. Error reporting is minimal; for example, I typed Master:chm (colon instead of period) and got no error message, just a dead link.
          • 2. Re: Merging CHM projects
            NL_Derek-GsBV5a Level 1
            Topics in Master
            The above method does not work when there are topics in Master.chm. The reason is that they are entered as local topics in the master ToC Master.hhc. The easy way out of this is to have no topics in the master, only (one or more) ToCs. However if you already have topics in your master and do not want to move them, you will have to convert each ToC entry to a remote topic.

            This is easier than it sounds; open the Properties window for the ToC Entry; at the bottom you see "Link to:" and the name of the topic like "My_Folder\My_Topic.htm".
            Edit this to "Master.chm::/My_Folder\My_Topic.htm" (note the mix of forward and backslashes); RoboHelp will now see it as a remote topic. You will have to do this for each and every local entry in the ToC, but with judicious use of Ctrl-C and Ctrl-V it goes quite quickly.
            • 3. Re: Merging CHM projects
              Dee70 Level 1
              I appreciate this post, as getting our merged chm projects to work together seamlessly has proven to be very difficult. The approach we're using now is similar to what you describe here, but results in multiple windows opening on top of each other, rather than the TOC clicks keeping the user within the same window. I am trying to make a few changes based on what I'm reading here in hopes of fixing this issue; however I am having difficulty applying the global window. Currently all of our help projects use a window called Main. I have updated those to $global_Main, but now when I try to click a topic in the TOC of a chm file I get this error message: "The window name "main" passed to HH_GET_WIN_TYPE has not been specified." Do you know what might be causing that? Is there a specific procedure I need to follow in order to update to using a global window?
              • 4. Re: Merging CHM projects
                Pete Lees Level 2
                Hi, Dee70, and welcome,

                One possible explanation for the error message is that you may have specified "main" as the default window for the TOC itself, or even for the individual TOC entries. In either case, "main" takes precedence over "$global_main", even if "$global_main" is the default window for the help project. So, you may need to check the properties of your TOC and of the entries in it and change all the window assignments to "$global_main" — or else delete these assignments so that the default window for the project is used instead.

                • 5. Re: Merging CHM projects
                  Dee70 Level 1
                  Thanks for the tip. I've been meaning to follow up to explain how I fixed the issue. It did have to do with the default window settings for the TOC and Index. I was able to fix it within the single source layout settings for HTML Help following these steps:

                  1. On the HTML Help Options - Microsoft HTML Help window, in the Additional Options area, click Edit.
                  2. On the HTML Help - Advanced Settings window, on the Index tab, make sure the Default Window is set to $global_Main.
                  3. Select the TOC Styles tab, and make sure the Default Window is set to $global_Main.

                  In most of my help projects, these were the settings by default; there were a few though that were not set to this. Once fixed, the error no longer appeared.