Question
Merging CHM projects
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.
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.
AdChoices