Merging HtmlHelp Projects
Previous Topic  Next Topic 

Before you go and dissect your carefully crafted 500 page project into multiple projects please take a few moments to run through this tutorial so that you understand the concept completely first.


In this scenario we have a holiday company who want to showcase their specialized holiday destinations which are categorized as "Cheap and Cheerful" and "Ghastly Expensive". They want most of their clients to see the "Cheap and Cheerful" destinations but only some of their clients will want to see both and some will want to only see the "Ghastly Expensive" options. So they create two projects as follows:-


Master Project

  1. Select "File | New Project" and type in a new Project name of "Holidays", a Title of "Great Holidays" and whatever folder you choose, but remember this folder, as we will need it in a moment.
  2. Add a new Heading and call it "Cheap and Cheerful Destinations" and two new Topics beneath it called "Iraq" and "Afghanistan"
  3. Select "Project | Project Settings" and click on the "Merging" tab, then check the option "This Project is part of a Merged Project".
  4. Select "Project | HtmlHelp Compiler Options" and on the "General" tab, check the option "Create a binary Index" and un-check the option "Create a binary TOC"
                
  5. Now compile and see what you've created.


Slave Project

  1. Select "File | New Project" again and type in a new Project name of "GhastlyExpensive" (no spaces), a Title of "Great Holidays" and the same folder as you chose for the Master Project. Note: You can choose a different project and then simply copy the compiled files to the Master Project folder after compiling, but keeping the folders the same cuts out this step.
  2. Add a new Heading and call it "Ghastly Expensive" and two new Topics beneath it called "Hawaii" and "Antarctica"
  3. Select "Project | Project Settings" and check the option "This Project is part of a Merged Project".
  4. Select "Project | HtmlHelp Compiler Options" and on the "General" tab, check the option "Create a binary Index" and un-check the option "Create a binary TOC" and set up all options exactly the same as for the Master Project. For now they should be. But it is important that if you make any changes to one Projects settings, that they be reflected in all the other projects that are merged together.

    A drawback of having both Projects share the same directory is that if you create a Topic that has the same Context String as in the other Project, then whichever Project is compiled last will overwrite the Topic with the same name in the other Project. In one sense this forces you to maintain unique pages for each Project, but if you don't want to manage this, create separate Project folders and copy the compiled help file to the Master Project folder.
  5. Now compile and notice the contents and index.


Merge the Two!

Now let's go back to the Master Project and add in our Slave Project:


  1. Select "File" and the last entry should be "Holidays", select it and the Master Project will open.
  2. We will now tell the Project about the files we want Merged together. Select "Project | HtmlHelp Compiler Options" and click on the "Advanced" tab, then on the "[Merge Files]" tab and type in all Slave Projects. In our scenario we type in "GhastlyExpensive.chm" and click [OK]


  3. Now we will tell the Master Project to merge the Contents files of the Slave Projects. On the "Help Text" tab, in Contents, move to the last entry and select "Insert | Merge another Contents" and type in the compiled Project name followed by "::/" and the Slave Project's contents file name, i.e.:-
        GhastlyExpensive.chm::/GhastlyExpensive.hhc
  4. Now compile. You should see that the Contents for the Master Project now show both Projects as in the screen shot below. If you check the Index you will see that it has also merged and you can search across all Slave projects too. If you have any problems please go back over all the steps to see what went wrong.


Possible Problems with Merging

The current version of Microsoft HtmlHelp v1.4 has some bugs in Merging. We advise that you place your Merge Contents at the first level of the tree in Fast-Help, but you will notice that it is indented below the last entry in your Master Project. This is a bug. If you try to place your Merged Contents at any other level it will act erratically.


Another issue is spaces in file names, merging does not like it, so please name your Slave Project compiled files without spaces.