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.

 

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, responsive and webhelp 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.

 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. This replicates how it worked in Classic but there you could generate to a folder within a project, in 2019 Classic you cannot. That means they become out of sync with what you are generating. 
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.

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.

Skins

If the parent project is set to use frameless skins, then the child projects must have one frameless skin 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 skin, then the child projects must have one responsive skin 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 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

Skins

The skin for the parent gets applied to the whole merge. Whilst the child projects need to have a skin 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 skins, 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

The first time you generate, 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.

Updating Projects

The Merged Output

What you will see is apparently one help system with:

Additional Information

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 Skins

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

Responsive and WebHelp Skins

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 skin will need to be configured as required.

Partial Merge

After you have created the merge, you might only want to deliver some of the child project. You must always deliver the parent but you can remove child projects from mergedProjects.

Generate all the projects in this demo and then remove one of the children from mergedProjects. The merge will still work and the TOC, Index and so on will automatically adjust.

Glossaries

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

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:-

  1. Select the last topic in the TOC (Child Three - Topic Two) and then apply just filter Three.
    You will see most of the content is hidden except for the paragraph with tag Three applied.
  2. Clear that filters and go to some other topic and then apply filter Three again.
    You will not be able to access Child Three - Topic Two. The problem only occurs with topics already open.

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 different skins and different preset types configured ready to use.

In the demo the topics are linked to standard.css. In Frameless Dark, a master page linked to dark.css is selected in the preset to override the topic css.

Click here to download the demo.

Known Issues

Predictive Search

I understand the results will vary based on previous searches. In a test where each topic had a word starting "blue" with a number following, I expected to see any combination of blueone, bluetwo etc. I did get bluefive and blue six but I also got "blue four child two". That is a combination of the term and the topic name. I cannot see any logic for that.

I also searched on child and got child one and child one topic. Only two results compared with the test using blue, notwithstanding there were many more results that could have been found. Also child one topic does not exist as a string, child one - topic would be valid.

Not major problems but it doesn't seem robust.

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

08 Apr 2020

Search items added to Additional Information and Predictive Search added.

28 Jan 2020

New topic.