Merging Help - Adobe RoboHelp 8

What's covered? This topic is about how to create merged webhelp. The original version appeared on the site in 2004 when the method was devised to overcome a little hurdle that had been set up by the way RoboHelp worked then. That problem was fixed in Adobe RoboHelp 7 but the method has other advantages so I still recommend it. The feedback that I have had tells me that it is regarded as the simplest method around. I use it for a merge involving some 12,000 topics in over 700 folders, so it's also robust! I have also been told that Adobe Technical Support point users to this page. The screenshots are from Adobe RoboHelp HTML 8 and some of the options are only available in that version. See the Merged Help topic for earlier versions. RoboHelp for Word can be used to generate webhelp but it is not designed to create merged webhelp. Click here if that is what you want to do. For the first time, this version of the article contains a section on merged Microsoft HTML Help (CHMs). If you need to merge AIR Help, see Merging Help - Adobe RoboHelp 9, the method is the same.

 

If you have read other versions of this article, please note that the redirect method has been revised to handle a change made in Firefox 3.0.9

Merged WebHelp Why structure is important The table of contents How this method works The structure and the basics Step 1: Create the structure Step 2: Create the parent project Step 3: Create the child projects Step 4: Develop your help and create links Step 5: Update the parent project Step 6: Generate and publish the parent project Step 7: Generate and publish the child projects Step 8: Forcing the TOC to synchronise Step 9: Check for broken links Step 10: Test Step 11: Delivery The RoboHelp 8 Wizard

Merged Microsoft HTML help (CHM files) CHM filenames Structure Setting up the merge: Parent project redirect Setting up the merge: The parent project TOC Links between topics in different projects What you supply     Calling the help

 

Merged WebHelp

Why structure is important

When you create links between topics in a single project, the relative path between those topics will remain unchanged in the output, as otherwise they would not work. The same has to be true when creating merged help. The folder structure of the generated and published files is:

• Parent Project
• Merged Projects
• Child One
• Child Two
• Child Three etc.

The same structure is needed for your source projects so that you can create links between them. While you can have content in your parent project, it is much simpler if all content is contained in the child projects so that the parent is effectively nothing more than a shell.

The table of contents

Before you read too much further, you need to consider how you want the TOC to be structured.

You cannot have the book for one child project nested within the book for another child project. That is a limitation of merged WebHelp generally rather than of this method. You can, however, nest a child project within a book in the parent project.

Because this method works by putting all the content in projects at child level, there is no book in the parent TOC into which you can nest a child project. The TOCs for each child will appear one under the other.

There is a method of merging that does give you the ability to nest a child project within a book in the parent project. However, as described in another article, it is a more complex method and I do not recommend it unless you are hell-bent on this requirement. It is a more time-consuming method and prone to errors.

How this method works

As with other forms of merged help, one project must be designated as the parent. There's nothing though to say that the user has to see the parent project! When merged WebHelp is opened by running the start page, what you normally see is shown Figure 1.

Figure 1. The conventional way of viewing merged WebHelp.

What my method does is open the help via the parent project, as it must, but then immediately switch to one of the child projects. So what the user sees is shown in Figure 2:

Figure 2. With this method, the user sees a topic from one of the child projects, rather than the parent.

From then on, all the content is in child projects, making the creation of cross-project links simpler. How that is done is described in the following sections.

A ZIP file containing a working example can be downloaded. I have set all the file dates and times to be the same. This will enable you to identify any files you change. The ZIP file must be extracted to retain the folder structure. When you open the projects, you will see a warning about external links, just click OK.

I strongly recommend that you work on the download first. It is kept simple so that you can easily see what is going on.

As always, before you start using a new method on your live projects, do back them up first.

The structure and the basics

So that you can set things up easily when working on the source files, you need the folder structure shown in Figure 3 for your projects.

Figure 3. Use this model structure for your merged help projects.

In this model, you put all the topics that would be regarded as parent project topics in the child_1 project. The parent project in this setup contains only one topic that the user will never see. When the help is opened by calling the start page of the parent project, what happens is that the toolbar and navigation pane display, then the default topic for the parent project starts to open but a redirect in it calls the default topic for child_1. That is what the user sees.

Step 1: Create the structure

Create a structure for the source projects similar to the one shown in Figure 3. You can call the folders whatever you want. I simply use "parent" and "projects" so that alphabetically, the order is the parent first and then the children.

Step 2: Create the parent project

1. Create a WebHelp project. I use "parent" as the project name and the file name for the only topic in this project. Avoid spaces in your project names.
2. Open the default topic that RoboHelp creates and remove all text, including the topic heading.
3. Select the skin you require and edit that as necessary. Remember, it is this skin that you will see for the whole merged output. Any skin for a child project is only seen if that project is opened independently of the merged output.
4. If any of your child projects will have a browse sequence, it is essential that you create one for this project. I know there is only one topic that can go in it. The user will never see this browse sequence, but unless you create it, the checkbox to enable browse sequences will be disabled when you generate the help. If the parent browse sequence is not enabled, the child browse sequences will not work.
5. For now, close this project.

Step 3: Create the child projects

First, create the main child project, which is simply a child project containing what would otherwise have been in the parent project. Typically, this will be an introduction to the product, how to use the help, and other such topics. The default topic for this project is the one you will later set up to be the "default" for the merged help. This project is created in its own folder within the projects folder.

Next, create any other child projects you require. These are also created in their own folders within the projects folder.

Step 4: Develop your help and create links

To create the links:

1. Highlight the text that will be the link.
2. Select Insert > Hyperlink or the hyperlink icon.
3. Click the "Link To" dropdown shown in Figure 4 and select File.
4. Browse to and highlight the required file and click Open (or double click the required file). The absolute path will be shown in the "Link To" field. There is no need to amend it. After you click OK, RoboHelp will amend the path to a relative path (double click the link if you want to check this).

When creating links between projects, you may get a warning about links to external files. That is normal, and I have selected the "Do not display again" option. Note, however, that you cannot reverse that option anywhere, except by reinstalling RoboHelp!

Figure 4.  "Link to" is where you create links. You may see the warning shown.

Note re Unix
When you publish a single WebHelp project with the "Use Lowercase Filenames" option selected, RoboHelp changes both the filenames and any links to lowercase.
When you publish each project in a merged help setup with the "Use Lowercase Filenames" option selected, RoboHelp will change all the filenames to lowercase, but links to files will only be changed to lowercase if the link is to a file in the project you are publishing. So, all the filenames will be lowercase, but some of the links will still be mixed case. This mismatch causes broken links on a Unix box.
You must ensure the case is the same for the files and links in your output. I ensure that all file names are lowercase from the start.
This mismatch is not an issue on Windows systems.
See the sister article for RoboHelp 7 for more information.

Step 5: Update the parent project

The next step is to create the references to the child projects and add the redirect in the only topic in this project. Reopen the parent project.

Set up the parent project TOC

The parent project has no TOC as such, but this is where you tell the parent what children it has! Here we follow the RoboHelp instructions for including the TOC from the child project(s).

1. Click the Insert Merged Project icon (highlighted blue in Figure 5)
   
   
   
   Figure 5. Clicking the Insert Merged Project icon brings up this dialog box.
2. The Merged Project dialog box will appear. Make sure the FlashHelp/WebHelp tab is displayed. The project name will be blank at this point.
3. Navigate to the XPJ file for the child and click Open.
   
   
   
   Figure 6. Select a child project from the Open dialog box.
4. Repeat steps 1–3 until all the child projects are shown in the TOC as shown in Figure 7. The order of the references is the order in which their TOCs will appear in the merged help.
   
   
   
   Figure 7. The child projects shown in the parent project's TOC.

Add the redirect

This section has been amended following changes made in Firefox 3.0.9.

Previously I have recommended using a meta tag as below to redirect from the parent topic to Child 1 with a 0 second delay.

<meta http-equiv="refresh" content="0;URL=./mergedProjects/child_1/child_1_topic.htm" />

Changes made in Firefox 3.0.9 mean that the TOC will not display using a zero delay. Changing the value to 1 second as below allows the TOC to display

<meta http-equiv="refresh" content="1;URL=./mergedProjects/child_1/child_1_topic.htm" />

but it will not synchronise until after the user has clicked some topics and that is not really satisfactory. Fortunately a quick look at some javasript sites found a script that, with a few changes, provides an alternative method that allows the TOC to both display and synchronise. It also works in Internet Explorer.

1] Remove the redirect.

2] Click in the box below, press CTRL + C and paste the following above the </head> tag. You will need to amend the path to point to the topic in Child 1 that you want to be the default.

3] Amend the body tag as below. Change the timeout if required, it is set in milliseconds. If your body tag already has an onload event, add a semi colon after it and do not repeat the onload= part.

<body>

Background color

It is important that the topic to which the user will be redirected and the parent topic have the same colored background. If the two topics have different colors, the redirect may be detected.

Step 6: Generate and publish the parent project

You can generate to the !SSL! folder within your parent project, but I recommend that you generate to a folder outside the project; it avoids a lot of confusion and some problems that regularly crop up on the forums. In the download project, I have set things up to generate to a folder called generate. You can name it whatever you prefer.

You do not have to publish each time you generate and you can skip step 6 in this section for now if you wish. I will explain more about publishing later.

1. Start the Single Source Layout for WebHelp so that you see the first page of the wizard. By default it will appear as in Figure 8.
   
   
   
   Figure 8. Page 1 of the Single Source Layout for WebHelp.
2. Change the Output folder and filename. The folder I have selected is outside the project folders. It's cleaner that way, with source in one folder and output quite separate. The start page file name will be projectname.htm by default. I prefer to rename it as index.htm. That is a standard name for a website and one familiar to your developers. It helps them identify the start page. Notice that I have not selected Use Lowercase File Names (see Figure 9). As already explained, that does not work across a merge, so if you want lowercase filenames, set them up that way rather than using this method.
   
   
   
   Figure 9. Leave Use Lowercase File Names unchecked.
3. Leave everything in the Content section unchanged.
4. Use whichever options you require in Additional Options. I suggest you check the Add Mark of the Web option while you are setting things up.
5. Go through the next two pages of the wizard, leaving the defaults unchanged for now. Once you are familiar with merged WebHelp, you can use whatever options you require.
6. The last page of the wizard is where you set up publishing. Not everyone needs to publish. If you are not sure, see Step 11: Delivery. If you do need to publish, click New and enter the required location in the New Destination dialog box (see Figure 10). The name can be whatever you want.
   
   
   
   Figure 10. The Publishing dialog box.
7. Click Finish and the Parent project will be generated. You can then publish if you set up a server path. (It can be a local drive for this purpose.)

Step 7: Generate and publish the child projects

When you generated the parent project, it will have created a structure like the one in Figure 11, except the child project folders will be empty at this stage.

Figure 11. Generating the parent project produces this folder structure.

Follow the same steps as for generating and publishing the parent, except that you point to the appropriate child folder; for example,

C:\rh8\generate\mergedProjects\child_1. Don't forget you also need to check the browse sequence options for the relevant child projects.

Care re mergedProjects

In the above example, you will see that the "P" in mergedProjects is uppercase. I recommend that you do not change this. Sometimes developers will insist on all lowercase paths and filenames, and if you encounter this you should explain that the capital "P" is forced by RoboHelp and that the workarounds risk breaking the help. If this is not accepted, then see the RoboHelp 7 version of this article for further information.

Step 8: Forcing the TOC to synchronise

Provided you select Automatically in the Synchronise TOC option, once the help has been opened, the topics displayed will synchronise with the TOC. However, when you open the help, you may find the first topic displayed does not synchronise, particularly with larger projects. Thanks to Jose Badeau, there is now a fix if you encounter this problem.

You need to edit a file called whthost.js. You will find this in both the generated output and the published output. You only need to tweak the file in the published output unless you supply the generated output to the developers.

Open the whthost.js file in a text editor. Find the function realPutData().

The end of the function will look like this:

checkFillStub();
}

Edit it to look like this:

checkFillStub();
// fix to force sync
top[1].frames[0].frames[0].syncWithShow();
}

That forces the TOC to synchronise every time, including when you open the help. If you use the generated output, you will need to make that change every time you generate. If you use the published output, in limited testing the change seems to stick, but it would be advisable to check for it each time you publish.

Step 9: Check for broken links

RoboHelp does not check external links, which includes links between the child projects, so you may want to consider a website link-checking utility.

Step 10: Test

Go to either your rh8_publish folder (or rh8_generate if you skipped publishing) and double-click the start page; index.htm, if you followed my example. Watch very carefully: what happens is that the default topic does open but immediately redirects to the default topic for child_1. You will probably not even notice it.

If you want to test that, apply a bright red background to the parent default topic, then you will see it! That is also why I suggested giving this blank topic the same color background as the "default" topic to help mask its transitory appearance.

The parent default topic cannot be accessed, as there is no TOC for the parent project, you did not index that topic, and there is no text the search engine can find.

There it is: merged WebHelp with easily created links—all ready for delivery.

Step 11: Delivery

Generating and publishing: what's the difference?

Generating is about RoboHelp converting the content of your source files to code that can be interpreted by different browsers.

Publishing is about taking those output folders and files and putting them onto a server. In doing this, RoboHelp makes various checks, and if you select not to republish all, it will just update what has changed. You can copy the generated files to the server outside RoboHelp if you wish, but you then have the task of making sure you update the right files, or updating everything. In many companies, you will simply zip up the generated folders and files and the developers will update the server.

There will be differences between the dates and times of the generated files and the published files, as generating always creates new files, whereas publishing will only create new files if you select to republish all or if the file content has changed.

This means that if you elect to update the server outside of RoboHelp, you will not be able to easily identify what has changed in the generated folder, because all the files will be new, even though only some have changed. RoboHelp's publishing process, however, can track what has changed, so it knows what needs to be updated on the server.

What if all the projects are not required in a particular installation?

Take a copy of the full merged WebHelp output and delete from the copy the folders for the projects that are not to be installed. It really is that simple. Take a copy of rh_generate from the download, delete the folder for Child 3, and then open the help. You will see that the TOC no longer shows the book for that project and the index no longer shows its topics. Also, any links from topics to the deleted child will break. You need to consider that in your design. In some cases, it may mean you do need to generate a new output after removing those links from the source.

The RoboHelp 8 wizard

Earlier in this article, I deliberately skipped over many of the fields in the wizard. I wanted you to focus on getting a project up and running. I hope you have now reached the stage where we can look a bit more closely at the various features available and expand on what you need to know. This section will also be useful if you are familiar with merging and just want to learn a bit more about doing so with RoboHelp 8.

Starting with the first page of the wizard (see Figure 12), I'll note the features and offer recommendations:

Figure 12. The first page of the wizard sets many of the key parameters for your project.

• Don't confuse the Start Page with your Default Topic. They are not the same thing. The Start Page is what opens the WebHelp. The Default Topic is what displays in the topic frame.
• The Use Lowercase File Names option is not recommended for merged help. It will force all filenames in the project being generated to lowercase, and it will change the links to topics within that project to lowercase. It will not change the links to topics in other child projects. When you generate those, this option will change the filenames there, so there will be a mismatch between link and topic. If the help is on a Unix box, that will cause a broken link.
• The Conditional Build Expression option will apply only to the project being generated, not to other projects. That is desirable.
• The skin for the Parent will apply to projects within the merge unless you open the child independently of the merge. Then the skin will be whatever you selected when generating that project.
• RoboHelp 7 introduced the ability to have more than one TOC, Index and Glossary. Select the required one here.
• Variables were introduced in RoboHelp 6. If you want to change any values, click the Edit button. It is only disabled in Figure 12 because no variables have been set up.
• Use the Add Mark of the Web option in Additional Options while you are working locally, but note that links to PDF files may not work locally.
• Apply to all Topics is new in RoboHelp 8 and lets you apply a Master Page and / or CSS (Cascading Style Sheet) that will override whatever is set in your topics. I have not tested this with merged WebHelp but as long as you apply the same Master Page and / or CSS, I see no reason why it should not work.

The next page of the wizard (see Figure 13) covers toolbar buttons, navigation options, and other settings.

Figure 13. Set toolbar buttons, navigation and additional options in the second page of the wizard.

• If you add any new toolbar buttons to the skin, make sure you select them when you set up this page. By default, they will be listed, but not checked.
• The Show Navigation Pane Link in Topics option is what causes the default text of Show to appear if you go to Windows Explorer and double-click a topic. It will also appear if your developers call the help incorrectly for merged WebHelp. See Calling WebHelp for more information on that.
• For a long time people have asked how to remove the RoboHelp logo. Now you have to add it in deliberately. You can also change the image in the skin.
• The Show Merged TOC in Child Project option is new in RoboHelp 8. Previously if you opened a child topic other than through the parent, you would only see the Table of Contents for that child project. By selecting this option, users will see the full merged TOC.

The third page of the wizard (see Figure 14) offers navigation pane and speed optimization options.

Figure 14. Set options for the Navigation pane and speed optimization on the third page of the wizard.

• I suggest you leave the default DHTML option unchanged unless you have specific requirements.
• By default, speed is optimized for website delivery. Generally, though, it has been found that TOC synchronization works better if set to Local PC or Intranet.

The final page of the wizard (see Figure 15) covers publishing options.

Figure 15. Set your publishing location and related options on the final page of the wizard.

• Note that the Check for Deleted Files option in the wizard does not delete topics from the server; it simply checks for files that have not changed, but are missing from the server.
• If you leave Republish all unselected, only updated topics and internal files will be published to the server.

 

Merged Microsoft HTML help (CHM files)

So what is different with merged Microsoft HTML help?

CHM filenames

Avoid the use of underscores, the hash symbol and suchlike in the names of the CHM files you create. They have been found to cause problems with merged Microsoft HTML help. Stick with alphanumeric characters and no spaces.

Structure

You do not have to use the same structure as is described in Step 1 above. Nevertheless, I recommend that you do as it does keep things tidy. It will also help if you have to create WebHelp at some point in the future.

The reason you do not have to apply the same structure is that the links between topics in different child projects are created in a different way, as described below. The link is relying on the name of the CHM file and the location of the topic within the target CHM file. It does not require the relative path.

Setting up the merge: Parent project redirect

You do not need the redirect topic described in Step 5 above, indeed you must not use that method for this type of help. You will need a parent with at least one topic that is seen by the end user.

• If you are only creating merged Microsoft HTML help, then create such a topic instead of creating the blank redirect topic.
• If you are creating both types of merged help, then create two single source layouts, one for each type of help, and apply conditional build tags.

Setting up the merge: The parent project TOC

• When setting up the parent TOC when merging WebHelp, as described in Step 5 above, it is not necessary for the child projects to have been generated. All that matters is that the child projects have been created.
• When merging Microsoft HTML help, it is necessary for the CHM files to have been created before you set up the parent TOC.

I still recommend you generate the CHM files to a folder outside of any of the projects; the generate folder, in my example. In the first page of the wizard, make sure you generate the output from all the projects into that one folder or the merge will not work.

After you have generated each CHM file to this folder, open the parent project and click the HTML tab shown in Figure 6 and browse to the folder where the CHM file was generated and select each CHM file in turn. When prompted, click Yes and allow the CHM file to be imported.

If you are using RoboHelp 7 or later and have to create both types of merged help, you can have more than one TOC; so you could create one for the WebHelp layout and one for the Microsoft HTML help.

Finally, generate the parent project to the generate folder. If you open that CHM file, you should see your merged project. The merge is set up, and links can now be created between the projects.

Links between topics in different projects

The links between topics in different projects are created in a different way, which is bad news if you have to create both merged WebHelp and merged Microsoft HTML help. If you need to output both types of help, you will have to create both types of link and then apply conditional build tags.

To create cross-project links, you need to have your default layout set to Microsoft HTML help. Then, when you click the Link To field in Figure 5. you will see an additional option, Remote Topic. When you select that, you will be asked if you want to import the target CHM file into the source project; you must select Yes. Choosing the topic to which you want to link is straightforward.

If you do not pause to get your mind around this part of these instructions, you could become confused later in the development of your help when you want to create more links:

• Before you added the reference to the child projects in the parent TOC, you had to generate a CHM file for each project to the generate folder. So that folder has a copy of each CHM file that exists in the merge.
• When you added each child CHM file to the parent TOC, that imported a copy of each CHM file into the parent. So the parent root folder has a copy of each CHM file that exists in the merge.
• When you created the first link from one project to another, a copy of the CHM file was imported. So now each project has copies of some or all of the other projects' CHM files.

Now, you want to create another link to a topic in one of the other projects; to which CHM file do you navigate?

• If you have already created a link to a topic in the target project, when you select Remote Topic to start the process of creating the link, the CHM file you imported earlier will be the default offered. The easy option is to select that CHM file. If you know the topic is in that CHM file, that's OK. If it is a topic that has been added since, then you have to go to the target project and generate a new CHM file to the generate folder. Then, in the project where you want the link, you now select Remote Topic and browse to the newly generated CHM file. That version will get imported, and you can then select your topic.
• If in doubt, update the CHM files in the generate folder regularly and always browse to those copies.

Right now that may sound very confusing, but once you have created a few links, you will find it much easier.

What you supply

You supply the parent CHM file always and whichever child projects you want the user to have. You take the copies from the generate folder, and they must always be in the same folder on the user's PC. If a CHM file is not in that folder, it will not appear in the TOC, its index entries will not display, and the topics will not be found by the search.

Calling the Help

Calling merged help will also require some changes, so make sure you liaise with your developers before changing things. If they have not factored in the time to deal with their side of things, you might not be flavor of the month!

Donations

If you find the information and tutorials on my site save you time figuring it out for yourself and help improve what you produce, please consider making a small donation.

Topic Revisions

Date	Changes to this page
26 May 2011	First image renumbered and some references to images corrected.
20 Jun 2009	Complete rewrite of earlier versions