Merging Webhelp - Adobe RoboHelp 7
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 has been 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! The screenshots are from Adobe RoboHelp HTML 7 and some of the options are only available in that version. If you are working with versions, X3, X4, X5 or Adobe RoboHelp 6, you might prefer to view the earlier version of this article. Click here. 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. |
If you want to print this topic with the content of all the dropdowns included, click the Show All button and then print.
Why Structure is Important
The webmerge module enables multiple webhelp projects to be merged at run time and function as if they were a single project. The folder structure of the generated and published files is:
- Parent Project
- Merged Projects
- Child One
- Child Two
- Child Three etc.
Before RoboHelp 7 corrected a bug, if you created that structure for your source projects, valid links between the parent project and any child project, or vice versa, would falsely report as broken when you were creating your help. If you changed the structure of your projects as below, the links did not show as broken but perversely they were!
- Parent
- Child Projects
- Child One
- Child Two
- Child Three etc.
So things did not work out of the box and that drove the design of this method. Whilst the false reporting of links has now been fixed, there are still many good reasons for using this structure, as you will see.
The key message here is that you must have your projects organised in a certain way so that cross project links are easy to create and work in the output.
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 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 in 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 but 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. The details are contained in this section of the earlier version of this article.
How This Method Works
As with other forms of merged help, there has to be one project 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 below.
| Toolbar | |
| TOC, Index and Search | Default topic for parent project
|
What this 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 this:
| Toolbar | |
| TOC, Index and Search | Default topic for the child 1 project
|
From then on, all the content is in child projects. How it 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.
As always, before you start using a new method on your live projects, do back them up first.
Demonstration
Click here to see a demo of the merged webhelp.
You should not detect any flicker in the topic frame before the default topic appears but if you do, solutions are given in Step 5.
Close the demo window to return here.
The Structure and the Basics
 |
So that you can set things up easily when working on the source files, you need this folder structure for your projects. What we do is 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 the toolbar and navigation pane display and the default topic for the parent project starts to open but it calls the default topic for child_1. That is what the user sees. Hopefully you have grasped the principles involved but don't worry if not. Just continue on and it will become clearer. |
Step 1 - Create the Structure
Create a structure for the source projects similar to the one shown. You can call the folders whatever you want. I simply use parent and projects so that the order is the parent first and then the children.
Step 2 - Create the Parent Project
- Create a webhelp project. I use "parent" as the project name and the file name for the only topic in this project. If you want the TOC to auto-synchronise with the topics displayed, make sure your project names do not contain any spaces. Spaces can cause problems with synchronisation as described in Snippets.
- Open the default topic that RH creates and remove all text including the topic name.
- 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.
- 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.
- 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 etc. 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 under "projects".
Step 4 - Develop Your Help and Create Links
To create the links:
- Highlight the text that will be the link.
- Click on Insert | Hyperlink or the hyperlink icon.
- Click the "Link To" dropdown shown below and select File.
- 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 or editing the registry.
Click here if your help will be installed on a Unix Box.
When you publish a single webhelp project with the "Use Lowercase Filenames" option selected, RH changes both the filename and any links to lowercase.
When you publish each project with the "Use Lowercase Filenames" option selected, RH will change all the filenames to lowercase but links to files will only be changed to lowercase for those files in the project you are publishing. So all the filenames will be lower case 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.
Step 5 - Update the Parent Project
The next step is to create the references to the child projects and set up the only topic in this project to call a topic in Child 1 so that effectively becomes the default topic for the merge. So 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 RH instructions for including the TOC from the sub project(s).
- Click the Insert Merged Project icon (highlighted blue)
- The Merged Project dialog will appear. Make sure the FlashHelp/WebHelp tab is displayed. The project name will be blank at this point.
- Navigate to the XPJ file for the child and click Open.
- Repeat steps 1 - 3 until all the child projects are shown in the TOC as below. The order
of the references is the order in which their TOCs will appear in the
merged help.
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 onload="timer=setTimeout('move()',100)">
Background Colour
It is important that the topic to which the user will be redirected and the parent topic have the same coloured background. If the two topics have different colours, the redirect may be detected. If you did detect a flicker in the demo, first try it again, if you still see it and find it unacceptable, click here for additional information.
When I first tried this method, the two topics had different coloured backgrounds and the parent had some text. It was very obvious what was happening. First I removed the text from the parent and then I applied the same colour to the background as in the topic to which users will be redirected. On the systems I have seen, the build up is then undetectable as you first get the colour from the parent, and then the text from the redirect appears to build cleanly on top.
If after doing this you can still detect the process, you need to decide whether or not it is acceptable. If it is not you could try this idea from Leon Descoteaux.
- Amend the redirect to introduced a timed delay. The number after CONTENT= is the number of seconds before the redirect starts. Enter a value long enough to allow the user to see some text on the parent page. Perhaps 2 or 3 seconds.
- On the parent page, add your chosen text, something like "Help opening ... "
This will delay the redirect process and you will see your message before the redirect starts. The time needs to be long enough that it is not a flicker and long enough to read the message, but not long enough to annoy the user.
You could use this method to display a splash screen by making that the parent topic and using a suitable delay.
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.
- Start the Single Source Layout for WebHelp so that you see the first page of the wizard. By default it will appear as below.
- Change the Output folder and filename. The folder I have selected is outside the project folders. It's just cleaner that way with source in one folder and output quite separate. The file name by default will be projectname.htm. 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 to Use Lowercase File names. That does not work across a merge so if you want lowercase filenames, set them up that way rather than using this method.
- Leave everything in the Content section unchanged.
- Use whichever options you require in Additional Options. I suggest you tick Add Mark of the Web while you are setting things up.
- 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.
- The last page of the wizard is where you set up publishing. Not everyone needs to publish. If you are not sure see Delivery below. If you do need to publish, click New and enter the required location in the New Destination dialog. The name can be whatever you want.
- Click Finish and the Parent project will be generated, and published if you set up a server path. (It can be a local drive for this purpose.)
Step 7 - Generate and Publish the Child Project(s)
When you generated the parent project it will have created a structure like this, except 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:\rh7\generate\mergedProjects\child_1. Don't forget you also need to tick the browse sequence check boxes for the relevant child projects. First time around run with the defaults in the Content frame. Once you have got to grips with the method, you will want to make other selections in the same way you would with a single project. The options are described later in this article.
Care re mergedProjects
In the above example you will see the "P" in mergedProjects is upper case.
If your developers insist on all lowercase path and filenames for some reason. Click here for additional information. I recommend that you leave the folder as mergedProjects if you can.
Does it matter?
See the table.
Question |
Answer |
Is your output going to be used only on a Windows platform? |
If your output will only be used on a Windows platform, then it does not matter. Windows is not case sensitive. Indeed if you look at what's involved in changing the case, there are good reasons for not changing it. |
Do your developers insist on lowercase file names? |
You will need to check with them whether this will be an issue. If they do require lowercase, see below. |
Is your output going to be used on a Unix platform? |
Unix is case sensitive. If you do not make any changes anywhere, then the help will work fine with mergedProjects. Consistency is what matters. |
I must use lowercase.
If you generate and publish, you probably only need to amend the published output.
If you only generate and then transfer those files to your server outside RH or you put them on CD, you only need to amend the generated files.
The bug works differently when generating and publishing. There's nothing like consistency, at least not here!
Generated Output |
Published Output |
When you define the path for the generated output, you can specify a lower case p. Don't bother. What will happen is that RH will generate all your output to mergedprojects. Then it will create another folder called mergedProjects for its own files and folders! So set it up as mergedProjects and then change the folder name when you are finished. Care: Next time you generate, RH will see your renamed mergedprojects and create mergedProjects again! If you have any toys left in the pram, use them to change it back to mergedProjects first. |
After you have published the parent, you can rename the folder mergedprojects and the rest of the publishing will go fine as long as you use "mergedprojects" when setting up the publishing target. In the published output, RH does not create an additional mergedProjects directory, it is happy to use mergedprojects. |
Find and Replace |
Having changed the folder name, it is important that all references to it are in the same case. You need to point a case sensitive Find and Replace tool at ALL the files in your output.
I emphasise ALL files to make the point it is not just your htm files. Indeed your own files are unlikely to contain this folder name. It is RH's own files that need changing. You will soon learn the exclusions such as image files. |
Step 8 - Forcing the TOC to synchronise
Provided you select Automatically in the Synchronise TOC check box, 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(), probably on line 1306.
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 each time you publish.
Step 9 - Check for Broken Links
RH 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 rh7_publish folder (or rh7_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 switches 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'll see it! That is also why I suggested giving this blank topic the same colour background as the other topics 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 to search on.
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 on a particular installation?
Take a copy of the full merged webhelp outputand delete from the copy the folders for the projects that are not to be installed. It really is that simple.
Try it. Take a copy of rh_generate from the download, delete the folder for Child 3 and then open the help. You will see the TOC no longer shows the book for that project and the index no longer shows its topics. Any links from topics to the deleted child will of course 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 using conditional tags and a build expression.
RoboHelp 7
Earlier in this article, I deliberately skipped over many of the fields in the wizard. I wanted you to focus on getting a starter project up and running. Hopefully you have now reached that stage and 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 7.
 |
|
 |
|
 |
|
 |
|
Citrix Issue
In a RoboHelp forum post dated 28 October, 2005, an issue with the Citrix environment was reported.
Many of our clients access our software via a Citrix Server and when the Help is accessed from our software in that environment, a blank "About" window appears prior to the Help opening. The Help does open ok, but that blank window does not close until after you close the Help, and then manually close the blank window.
There are two options:
- Live with it (well it is an option, even if you don't like it!)
- Remove the redirect and add some information to the parent project's only topic. Avoid creating any links to or from other projects in the merge though as they will fail in the generated / published output.
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 |
| 20 Jun 2009 | Multiple outputs section removed and transferred to a new article. |
| 14 Jun 2009 | Amended to provide alternative redirect as meta tag method has issues from Firefox 3.0.9 onwards. Section on Splitting a Large Project removed. Now a separate page. |
| 31 Aug 2008 | Topic rewritten for Adobe RoboHelp 7. |