Adobe RoboHelp: Merging Multiscreen HTML5

Merging Multiscreen HTML5 help is as easy as creating a master project, child projects, linking the child projects and publishing. Of course there are a few things to be aware of, but it all quite simple.

Merging Multiscreen HTML5 help is also very similar to merging WebHelp but there are some key differences: folder structure and links between projects.

What is merged help?

With merged Multiscreen HTML5 you present the output from multiple RoboHelp projects as a single output. The table of contents, index, glossary and search are all unified.

Merging can be very useful in some circumstances. Peter Grainge’s article The Reasons for Merging Help lists the most important reasons.

Some terminology

The terminology of the Multiscreen HTML5 output can be confusing. In this article I use the default RoboHelp terminology. That includes the following terms:

Term	Definition
Child project	A RoboHelp project that is merged in the master project.
Master project	A RoboHelp project that holds links to one or more child projects.
Screen Layout	An output look and feel for a specific Screen Profile. Much like a skin for WebHelp but much more powerful.
Screen Profile	A selection criterion to select a specific device or a specific configuration, for example by screen resolution. Every Screen Profile contains an output and used a single Screen Layout to provide the reader with a layout optimized for the device he is using.

Folder structure of the output

The folder structure of the output places all the merged child projects within a folder mergedProjects.

In the image you see the main output folder Merging HTML5. The folders android_galaxy_tab, android_phone and desktop contain the output for the different Screen Profiles.

The folder mergedProjects contains a folder for every child project of the master project.

Every child project contains it own output for every Screen Profile.

Merging Child Projects into the Parent Project

You merge the child projects through the master projects’ TOC. Go to the TOC and click the button New Merged Project. Now select the XPJ of the child project you want to merge.

You will find the name of the child project in the master projects’ TOC. And that is all you need to do. All further merging is automatic. Table of contents, context sensitivity, no further manual action required.

Creating Links between Master Project and Child Projects

Creating links between projects is a pain. Because you don’t know which Screen Profile a reader sees, you cannot make hard links. The easiest way to link between projects is to use RoboHelp’s Context Sensitivity.

To call the topic of another project with the map number 8, call the start file of the output as follows:

http://www.example.com/index.htm?rhcsh=1&rhmapno=8

This call will let RoboHelp handle choosing the correct Screen Layout. For more information on making Context Sensitive URLs for Multiscreen HTML5, see my article Context Sensitivity in Multiscreen and Responsive HTML5.

Note: When you open a context sensitive URL in the RoboHelp WYSIWYG editor after you have created the link, RoboHelp may remove everything after the question mark when you save the link. Create the link and use Cancel so RoboHelp won’t break your links.

Screen Profiles and Screen Layouts

The master project and every child project contain their own set of output for every Screen Layout. Whenever you switch between a topic in one child project to another child project, RoboHelp automatically determines the best Screen Layout for the device you are using.

This means that if you set the Screen Profile settings incorrect, a user may end up with different layouts for every child project. Rather annoying if you use the search function to find a relevant topic and suddenly get the iPad layout instead of the Desktop layout.

For example, see the two images below: each topic comes from the same merged project, but the different projects use different Screen Layouts for the same Screen Profile.

 

To avoid this, you must use the exact same Screen Profiles and Screen Layouts for every project.

This master project uses only three Screen Profiles, each with their own Screen Layout. Every child project must use the exact same configuration of Screen Profiles and associated Screen Layouts. If you use extra Screen Profiles or different Screen Layouts your output will show unexpected results.

Note: Make sure the optimization settings for each Screen Profile are the same in ever project too.

Using context sensitivity

If you want to call the help context sensitive, simply call the start file in the root of the output. The start file will determine which topic must be shown. For more information see my article Context Sensitivity in Multiscreen HTML5.

Notes about using Merged HTML5 Help

• The HTML5 widget Project title will show the title of the child project it is used in. It will not show the title of the master project (only in the master project itself.)
• In WebHelp, the only way to show the contents of the entire project was to always open the master project. This has changed in HTML5. You can now open any topic in a child project and the help will show all content.
• Scripters beware: When switching between a topic in different projects, you are actually opening resources in another folder. RoboHelp may add extra slashes to the URL of the current topic. If you have a script that utilizes this URL, be sure to evaluate the value before using it in your script.