Merged Help Using RoboHelp New UI

What's covered?

This topic is about how to create merged help using RoboHelp New UI. It covers frameless, responsive and CHM outputs.

See Merged_Help for further merged help information.

Introduction

Merging the outputs from a number of projects can allow multiple authors to work on different projects as well as allowing different combinations of outputs to be configured. What the end user will see will appear to be a single output. The TOCs, indexes and glossaries will be merged and search works across all the topics.

It is a straightforward process but correct setup and an understanding of the basics are vital.

First Step

The very first thing is to create all the projects you want to merge, you can add more and remove some later if required. You need to do that before attempting to set up the merge. The projects don't need anything more than to be created at this stage.

In the demo setup that you can download, you will find a parent project in one folder and three child projects nested in another. Having all the child projects at the same level is key and makes it easy to set up cross project links that will work in the merged output. If the child projects are not at the same level, cross project links will break in the output unless you manually edit them. Who wants to do that?

Linking the Projects

Next the parent needs to know what children comprise the merge. Open the parent TOC to create a reference to each child.

To add the child projects:

For frameless and responsive outputs, click this icon on the TOC toolbar and browse to the RHPJ file of each of the child projects.

For CHMs, click this icon on the TOC toolbar and browse to the CHM to be merged. Note that if you move the merge, you will need to reapply the projects to be merged.

You wll only see the icon in 2020 if you first go to Project Settings and select the Enable Advanced HTML Help Options check box.
 

RoboHelp copies the child project CHMs generated into the project so when the child is updated, the copy in the parent is not up to date.
Make sure you give the developers the CHMs from the location to which you generated them.

You can add both types to the same TOC. RoboHelp will ignore CHMs when generating frameless and responsive outputs and it will ignore those types when generating CHMs.

The Parent

It's OK to have topics in the parent but creating parent/child and child/parent links will require manually editing them in the source code of your projects. Otherwise they will break in the merged output.

I strongly recommend not having any parent project content. Whilst you must have a parent, think of it as just a shell to bring together the child projects.

A bug crept into RoboHelp 2020 necessitating the parent project to have at least one topic. It is fixed in 2022, the workaround in 2020 is below

  1. In the parent leave First Topic or any topic in.
  2. Remove all content from the topic, including the heading. You just want a blank page.
  3. Add that topic to the parent TOC.
  4. Select the Hide in Output check box in the TOC.
  5. In the parent preset choose a child project for the default topic, not the topic that has been created in parent.
  6. Generate your help.

The parent topic will not show in the TOC and there is no content for the search

In the presets you have to define a default topic. The default topic for the parent will be the default topic for the whole merge. Other than for CHMs, this can be the default topic in any of the child projects. You do not need to set up redirects as you did in Classic versions.

The Children

Set these up as you would any project.

The TOC

How this is set up is exactly what you will see in the merged output. If you want users to just see a book for each child as shown above, then create one book in the child and have all its contents in sub books.

Whatever books appear at top level in the child project will appear as books in the merged output.

Templates

If the parent project is set to use frameless templates, then the child projects must have one frameless template set up but it does not need to be configured in the same way. The configuration of the parent is applied to all the child projects.

Similarly if the parent project is set up to use a responsive template, then the child projects must have one responsive template set up.

Links Between Child Projects

These are created in the same way as a link to another topic in the same project. Click the Insert Link icon and select Local Files, then click the Browse icon.

 Note that in the new UI versions of RoboHelp, cross project links between CHMs are not supported. There is, however, a workaround in Gems. See Item 12 in CHM Gems.

Note the file names are mixed case in this example. If your help is to be published to a Unix server, it is important you do not choose the Use Lowercase File Names in your presets. Your files will then be lowercase but your links will point to mixed case topics. On a Unix server the links will then be broken.
Mixed case is OK but it must be consistent, the link and the target must be the same. If lowercase is a requirement, make sure your file names are lower case to start with.

Generating the Merge

Templates

The template for the parent gets applied to the whole merge. Whilst the child projects need to have a template of the required type, frameless or responsive, you don't need to configure it unless you will also be generating the child project to be used in standalone format.

Default Topics

As with templates, the default topic for the merge is defined in the parent project. There you can select a child project and its default topic will become the merge default topic. All child projects need a default topic defined to be able to generate the output.

Topic Appearance

Topics from each project will display within the merge in one of two ways.

  1. If you do not select a master page, the CSS file(s) linked to each topics will apply in the output.
  2. If you want them to display in the merge with different styles, create a master page and link the required CSS file(s) to that. Select that master page in the preset.
    If you look at Frameless Dark in the demo, you will see that all the projects have a master page with dark.css applied.

First Time

Responsive or frameless merge

You must generate the parent project output first.

When you have done that, you will see that within the parent output, RoboHelp has created a mergedProjects folder and within that there is a folder for each child.

In the presets for each child, you browse to the folder for that child.

Repeat that process for each child until all the projects have been generated for the first time.

Then browse to the output for the parent and run the index.htm file to open the merge.

CHMs

Generate all the CHMs from each project into the same folder.

Updating Projects

  • When you update a project, you only need to generate that project again.
  • If you add a new child project, that is a change to the parent so you need to generate that again as well as generating the new child project.
  • If you remove a child project, that is a change to the parent so you need to generate that again as well as manually deleting the removed child project from the output folders.

The Merged Output

What you will see is apparently one help system with:

  • One TOC.
  • One index that contains all the index terms from all the projects.
  • One glossary with all the terms from all the projects.
  • If you have also defined Dynamic Content Filtering, it will work across the whole merge.

Additional Information

Header Logo

In a single project, when the logo top left is clicked, the user is taken back to the default topic unless you have defined some other location in the Header Logo URL field in the preset. In a merge where a child project contains the default topic, as in the method described in this page, the Header Logo URL must be set to call the default topic. Enter the full URL of the default topic as it will be on the server where the output is located. You only need to enter that in the parent project preset.

Click here to see a demo merge

Note the URL when the output opens. That has been entered in the Header Logo URL field in the preset of the parent project. Select some other topic in the TOC. then click the logo. The topic displayed will revert to the default topic originally displayed.

Calling CSH Help Using Map IDs

If you call topics using map ids, the parent and all the child projects should have unique map ids in their map files. 

If a child topic uses a map id which is same as a parent topic, then using Parent/index.htm?rhmapno=123 will result in loading the parent’s topic (if it exists). 

If for some reason you cannot avoid duplication, then use the child project’s own index.htm file path.
For example - Parent/mergedProjects/child_one/index.htm?rhmapno=123

Calling CSH Help Using URLs

 Frameless Templates

Each topic has a unique URL and the help will open with all the navigation components.

Responsive Templates

If you use the URL of the topic in the format path/topic_name.htm, the topic will open without the navigation controls, the user will have to click a link to open the TOC and other controls.

To open the help with the navigation controls, you need a path that includes the start page of the help, by default that is index.htm. 

You then append #t= followed by the rest of the path to the required topic.
For example - path/index.htm#t=path/topic_name.htm

Running Child Projects Standalone

You cannot run the child projects standalone by copying from the merged output. If you need to run a child project standalone, you must create another preset that creates the output in another folder. The template will need to be configured as required.

Partial Merge

After you have created the merge, you might only want to deliver only some of the child projects.

In the new UI versions of RoboHelp, the theory is that you have to create a different parent with different child projects and generate that to the new parent's mergedProjects child folders.

In testing, I have found that sometimes just removing a single child works and sometimes it breaks the merge. 

My advice is that it is safer to create different parent projects with their own mergedProjects folders. The testing was done in the simple merge that you can download. More complex merges may well break more easily. Creating mulitple parents for different combinations of child projects is the Adobe recommended method.

Glossaries

Glossaries do not merge as even with the same term, the definitions could be different.

  • If you will always deliver the full merge, consider having one glossary only. It doesn't matter which project you put it in but logically it would be the parent in case you later don't deliver all the child projects.
  • If you prefer to keep separate glossaries and there will be common terms, if different definitions are needed, add something to the glossary term to differentiate it.

Dynamic Content Filtering

In the child projects you can set up whatever filters and groups you require for that child.

In the parent you must replicate all the filters and groups that are in use across the child projects for the purposes of filtering. Any groups and tags not applicable to filtering can be ignored. Note in the demo all the projects contain Group One with tags One and Two but only the parent and child three have Group Two and tag Three defined.

In the parent you need a topic that uses all the tags. See the Filter Order topic in the demo.

Generally avoid using tags at both Topic and Content level in the same topic. If a user is viewing a topic with both types applied and they select only the content level tag, the topic will be hidden except for that content.

In the demo. select one or more filters to see just the content for the child projects chosen

Search Results Order

Initially I thought I was getting results only from the body of the topic. However, on checking further I realised I had misinterpreted how the search results were presented.

  1. Topic Title - as in the Topic Properties.
  2. The first instance of the search term including text before and/or after.
  3. The file name.

Search Results Highlighting

  1. Searching on child one the list of results only showed the first instance of the word child in bold text. In the topic itself all instances of each word were highlighted.
  2. By searching with "child one" entered within quotes, only instances of child one were found. The terms child and one where separate were correctly not highlighted.

In the Demo

There are frameless, responsive and CHM presets configured ready to run.

Click here to download the demo. RoboHelp 2022.3 Version

Matt Sullivan's Webinar

If you want a visual demonstration of merging projects, see Matt Sullivan's Webinar.

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.