Merging Help - Adobe RoboHelp 9

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 that at one time involved 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 9 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. The article contains a section on merged Microsoft HTML Help (CHMs). It also introduces Dynamic User-Centric Content.

 

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 How this method works The structure Download the demo The table of contents 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 synchronize Step 9: Check for broken links Step 10: Test Step 11: Delivery RoboHelp 9 Configuration

Dynamic User-Centric Content DUCC   Merged AIR Help   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 The Index What you supply   Calling the help

Merged WebHelp

How this method works

According to the online help for RoboHelp, the basics of merged WebHelp are that in TOC of the parent you include placeholders for the child projects. When you generate the WebHelp for the parent, a folder named mergedProjects will be created and that will contain folders to which you generate the child projects. All quite simple and correct, as far as it goes.

What is not explained is that unless your source projects are set up with the correct structure, creating cross project links will require you to work out the relative path in the output and type that into the HTML. Fortunately it is not difficult to set things up so that RoboHelp creates the links for you and removes the scope for error.

The two key elements to the method described here are:

• The source projects are maintained within a simple structure.
• The parent default topic contains a redirect URL that opens a designated topic in a child project.

When merged WebHelp is opened from the start page, what you normally see is shown in Figure 1. The start page opens the tri-pane window and the parent project's default topic is displayed.

Figure 1. The conventional way of viewing merged WebHelp

What this method does is open the help via the parent project, as it must, but the redirect means the topic displayed is in fact from one of the child projects. What the user sees is shown in Figure 2:

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

In reality, the content of the topic from the child project would be the same content that would have been in the parent so the user sees no difference.

As all the content is in child projects, creating cross-project links can be done via the RoboHelp interface. That and what you need to know about merged help is described in the following sections.

The structure

The folder structure of the generated and published files is the same and is shown in Figure 3. The output from the parent is at one level in the "generate" folder, then there is a "mergedProjects" folder that is a "container" for folders that hold the output from the child projects.

Figure 3. Generated and published files folder structure

The same structure is needed for your source projects so that you can create links between them. With this structure links can be created using the RoboHelp interface. The only wrinkle is that links between parent and child will still break in the output. To handle that using this method, the content that is normally placed in the parent is placed in child_1 and the parent is effectively just a shell, albeit a very important one.

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.

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

Figure 4. Use this model structure for your merged help source projects.

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. If you do have content in the parent, avoid links between the parent and any child.

Download the Demo

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 download the demo and work on it first before attempting to work with your live project. The demo is intentionally 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 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 nest a child project within a book in the parent project but 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.

That works with no problems in the merges I have seen. The alternative is hand coding all your cross project links. Not recommended.

There is another 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.

Step 1: Create the structure

Create a structure for the source projects similar to the one shown in Figure 4 which is repeated here.

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 in the parent folder you created in Step 1. I have used "parent" as the folder name and the project name in the demo. 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 in the child_1 folder you created in Step 1.

This project will contain 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.

Then, create any other child projects you require in the folders for child_2, child_3 and so on.

Step 4: Develop your help and create links

To create links between the child projects:

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 ask me the question again" option. In RoboHelp 9 you can restore the warnings in Tools > Options.

Figure 5.  "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 in Figure 6)

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.

Figure 6.

3. Click the folder icon and navigate to the XPJ file for the child project and click Open.
4. Select a child project from the Open dialog box.

Figure 7

5. Repeat steps 1–4 until all the child projects are shown in the TOC as shown in Figure 8. The order of the references is the order in which their TOCs will appear in the merged help.

Figure 8. The child projects shown in the parent project's TOC.

Add the redirect

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 synchronize 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 synchronize. It also works in Internet Explorer.

1. 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.

<script language="JavaScript" type="text/javascript">//<![CDATA[ <!--Script courtesy of http://www.web-source.net - Your Guide to Professional Web Site Design and Development //--> var time = null function move() { window.location = './mergedProjects/child_1/child_1_topic.htm' } //]]></script>

Note that it is a condition of using the script that the acknowledgement remains in it.

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 onload="timer=setTimeout('move()',100)">

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 configuration settings. By default it will appear as in Figure 9.

Figure 9. 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 the output quite separate. The folder must be on your local drive.
   Starting from RoboHelp 9, the default start page file name will be index.htm in new projects, if you see anything else I suggest you rename to 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 8). As already explained, in a merge that may result in broken links. If you want lowercase filenames, create your topics with lowercase file names rather than using this option.
3. If your default browser is Internet Explorer, I suggest you tick the Add Mark of the Web option while you are setting things up. You will find that in the Navigation Settings.
4. Leave everything in the Content section unchanged.
5. Take a look at the other settings but I suggest you leave the defaults unchanged for now. Once you are familiar with merged WebHelp, you can use whatever options you require.
6. Publishing is optional and 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. The name can be whatever you want and it can be a local drive.
7. Click Save and Generate and the Parent project will be generated.
8. When RoboHelp has generated the project, if you have set up a Publish location a Publish button will be enabled.

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 3, which is repeated here. The child project folders will be empty at this stage.

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

C:\rh9_merge\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 synchronize

Provided you set the Synchronize TOC option to Automatically, once the help has been opened, the topics displayed should synchorize with the TOC. You may also need to set Optimise Speed to Local PC or Intranet. See the Navigation settings below for more information.

If you find the first topic displayed does not synchronize when you open the help, Jose Badeau provided this solution for earlier versions of RoboHelp.

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 synchronize 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 such as Xenu.

Step 10: Test

Go to either your rh9_publish folder (or your rh9_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. If you use the publishing function built into RoboHelp, various checks will be made and, if you select not to republish all, RoboHelp 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.

RoboHelp 9 Configuration

Previously the outputs for each project were generated using what was referred to as "The Wizard". Each page was accessed by clicking Next and Previous buttons. That has changed in RoboHelp 9. Now you access one page where you click the different options and work through them. It is important that you do look at each page.

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 9.

Let's take a look at these settings. Mostly the fields have been re-arranged but there are some new ones.

Remember, you have to go through the settings of each project in the merge.

General Settings

Figure 10.

 

Field	Information
Title Bar	What appears in the browser title bar used to be based on what was defined in Project Settings. Now you can set it here.
Favicon	If you want an icon to appear in the browser tab, set the icon here. It must be a 16 X 16 png or ico file. Note the path is absolute and based on a drive letter so the link will likely break if you move the project to a different machine with different mappings.
Output Folder and Start Page	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.
User Lowercase File Names	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.

 

Content Settings

Figure 11.

 

Field	Information
Content Title	Unless you are producing DUCC, you may as well leave this unchanged. DUCC within a merged setup is complex and you should not attempt it until you have first got your mind around how merged help works ordinarily.
Table of Contents / Index / Glossary	RoboHelp 7 introduced the ability to have more than one TOC, Index and Glossary. Select the required one here.
Variable Set	Variables were introduced in RoboHelp 6. Edit the values in the set you will use and then select that set here.
Default Topic	Select as required.
Language	Select as required. This will be the default language and will apply to content except where topics and / or paragraphs with a different setting.
Encoding	Leave the default unless your web administrator advises you that other encoding is required.
Map Files	Select as required.
Browse Sequences	Select as required.
Conditional Build Expression	The Conditional Build Expression option will apply only to the project being generated, not to other projects. That is desirable.
Apply to All Topics	Apply to all Topics was introduced 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.
Exclude Unreferenced Topics from Output	This was introduced in RoboHelp 9 and excludes any topic that is not in the Table of Contents or linked to from a TOC topic. The linking cascades so if the TOC has a link to a topic and that topic has a link to a topic not in the TOC, the second topic will be included, similarly if that topic has a link to another topic, the third topic will be included. If you use this option, check your output carefully to ensure the content is limited to what you want.
Exclude Baggage Files From Search	Certain types of baggage file will be included in search results unless you select this option.

 

Navigation Settings

Figure 12.

 

Field	Information
Skin Selection	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.
In Topic Navigation	This field is only enabled if in Skin Selection you select "Traditional Style - No Skin". It provides options to include/exclude “Show/Hide” buttons for Navigation pane in a Topic. It also gives option to include/exclude browse sequence in topic.
W3C Compliant Topics	Tick if this compliance is required.
Add Mark of the Web	Use the Add Mark of the Web option in Additional Options while you are working locally, but note that links to PDF filesWord documents and some other files may not work locally.
Section 508 Compliant	Tick if this compliance is required.
Optimise Speed For Internet / Internal	Logically you should set the appropriate option. Often problems posted on the RoboHelp forums have been resolved by changing this setting to Local PC or Intranet.
Preferred Format	Select DHMTL unless you have a specific reason to select HTML. The latter will give you an index with A - Z characters rather than the normal index.
Toolbar Buttons	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.
Synchronize TOC	This will work across the merge as long as you set the option in all the projects. It has been found that TOC synchronization works better if Optimise Speed (above) is set to Intranet.
Add Breadcrumb Links	In addition to any breadcrumbs you have included in a master page, this will add breadcrumbs to all topics.
Enable Browse Sequence	For some reason the browse sequences you selected in Content settings unless you also select this field.
Show Navigation Pane Link...	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.
Show Merged TOC in Child Project	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.
Search Input Field in Toolbar	Tick if this compliance is required.
Add About Box	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.

 

Search Settings

Figure 13.

The Search settings are the same as for any project and are not described here.

Publish Settings

Figure 14.

• 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.
• It is recommended that you leave Republish all unselected. Then only updated topics and internal files will be published to the server thereby reducing the time taken to publish.

Dynamic User-Centric Content

Dynamic User-Centric Content was introduced in RoboHelp 9 and is demonstrated in the sample projects that ship with RoboHelp 9. To see the samples, click Open on the RoboHelp Starter page and then click Samples in the ribbon on the left.

DUCC can be implemented within a merged setup but it takes some effort to get your mind around it.

Do not attempt to create merged help with DUCC unless you have already got a clear understanding of both merged help and how DUCC works in a single project.

Parent

To make merged WebHelp work with DUCC, you have to create the three categories in the parent and generate the single layout in that project. That creates the structure to which you then start generating. There will be a folder for each category and there will be a mergedProjects folder under each of them with folders for each child.

Children

In the child projects you only have one category but you need three layouts in each, one for All, one for Category A and one for Category B. Thus for a parent with three categories and three children you need ten layouts.

• The layout for All in each child points to the appropriate child folder under the folder All\mergedProjects that generating the parent creates. Because this category is intended to show all topics, there is no build expression.
• The layout for Category A in each child points to the appropriate child folder under the folder CategoryA\mergedProjects that generating the parent created. No categories are created in the child projects but the build expression Not Category B is applied.
• The layout for Category B in each child points to the appropriate child folder under the folder CategoryB\mergedProjects that generating the parent created. No categories are created in the child projects but the build expression Not Category A is applied.

Demo

Click here to download a demo.

Snippets

Occasionally I come across useful bits of information that don't quite fit the general content on this page but are worth mentioning. I add such items here.

Breadcrumb Home Link

Jonathan Smith, Technical Author at IRIS Software Group in the UK, wanted to be able to open child projects in such a way that when the user clicked the Home breadcrumb it opened the default topic for the full merge, not that child.

This is the solution he posted at http://forums.adobe.com/thread/931964

You need to edit the MasterData.xml to point to the default topic of the parent project and then add target=\"_top\" >" to the strTrail var in the AddMasterBreadcrumbs function in whtopic.js. Copy these edited files to each child project's output and it seems to work fine.

Merged AIR Help

• Merged Browser Based AIR Help is created in the same way as Merged WebHelp.
• Merged Desktop AIR Help requires a slightly different but straightforward variation.

Merged Desktop AIR Help

1. The source projects are set up in the same way as described for merged webhelp. See previous sections.
2. The change in procedure is when you generate. Generate the parent using the AIR Application option. The Output Location can be wherever you want but I suggest you follow the same procedure as with WebHelp and create a separate folder outside of any project.

Figure 15

3. When the AIR file has been created you will see the dialog below. Click Done. Do not install at this stage.
   

Figure 16

4. If you now use Windows Explorer to view the Output Location you will see the AIR file. You will also see a mergedProjects folder has been created with subfolders for each child project defined in the parent. At this stage there will be no content in them except some placeholder files that RoboHelp creates.

Figure 17

5. Go to each child project in turn to create the AIR output but this is where there is a very important difference.
   From the child projects you generate browser based AIR help, even though it is local AIR help that you want. Because you will select Browser Based Help as the Output Type in the dialog shown in Step 1, the Start Page field will be enabled. Browse to the relevant child project subfolder created when you generate the parent and generate the output to that folder.
6. When you have generated all the child projects, go back to the Parent and generate that again. When the dialog shown in Step 3 appears, click Install.
7. The installed AIR help will display all the projects.

The TOC, Search and Index worked as expected in a simple test and removing one of the child project outputs that you will find in Program Files worked in the same way as removing a child folder from merged webhelp. Please note though that I did not test removing child projects extensively.

 

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 the Merged WebHelp content 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.

The Index

In a merged CHM setup, the index of the parent project must contain at least one index term. The indexes in all the projects must be binary indexes.

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!

See Calling WebHelp for more information.

Search does not work when CHMs are on another machine

If you find that the search does not work when you put the CHMs on another machine, see Item 13 in Using RoboHelp 9.

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
09 Dec 2011	Breadcrumb Home Link - Snippet added.
30 Jun 2011	Merged AIR Help section added.
31 May 2011	New topic for RoboHelp 9. Explanation of method rewritten.