What's covered?This topic describes how to create merged webhelp and how to set up your RoboHelp HTML projects so that you can easily create links between them. As you will find out, there's a little hurdle that has been set up for you by the way RoboHelp works! This method provides a simple workaround. 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 RoboHelp X3 but the method works in all subsequent versions up to and including Adobe RoboHelp 7. Any reference to an MPJ file refers to the XPJ file in later 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. |
If you want to print this topic with all the dropdowns included, click the Show All button and then print.
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:
In RoboHelp Version X3 through to RoboHelp 6, If you create that structure for your RoboHelp projects, valid links between the parent project and any child project, or vice versa, will falsely report as broken when you are creating your help! If you change the structure of your projects as below the links will not show as broken.
There is a small snag though, the links between parent and child projects will be broken in your generated output!
Links between the various child projects will be fine. The problem only affects parent / child links so
Whatever your scenario though, I strongly recommend you do follow this structure as you will find it provides a clean logical way of working.
Before you read too much further there is one point you need to consider as it affects whether you use this new simpler method or the old method. You need to think about what you want the user to see in the TOC when they open the help.
Show Me
Using the old method, it is possible to create this TOC where the child projects (Plugin 1 and Plugin 2) appear within a book called Configuration which is defined in the parent project. Configuration and the child projects are only seen when Main Book 2 is expanded. This cannot be done using the new method.
As you will discover, this method works by putting all the projects with any content at child level. The parent project is effectively nothing more than a container. For reasons that will be clear later, the outcome of this is that each project will appear as below. The books can be in any order but they cannot be nested as with the old method. This should not be an issue for most projects but you have to decide.
If you can already see that you need the old method, click here to see how that 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 child project
|
From then on, the user is working with child projects and, as I said earlier, there is no problem with links between child projects. How it is done is described in the following sections. For those who used the previous method and need to refer back, or anyone curious about it, click this link.
A zip file containing a working example can be downloaded. I have set all the file dates and times to 01/08/04 and 00:00. This will enable you to identify any files you change. The zip file contains two zip files.
As always, before you start using a new method on your live projects, do back them up first.
Click here to see a demo of the mergedwebhelp.
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.
|
This is the structure RoboHelp will create when you generate and publish merged webhelp. |
|
If you set up your source projects in the same way, when you create links between parent and a child they will falsely report as broken. |
 |
To avoid that you need to set up a structure like this. At this point you will be saying to yourself, earlier he said a different structure for the source projects would lead to broken links between the parent and a child in the output. Correct, it would, but this method avoids any such links! What we do is put all the topics that we used to put in the parent, in the child_1 project. The parent project contains only one topic the user will never see. When help is opened by calling the start page of a parent project, what happens is the toolbar and navigation pane displays and the default topic for the parent project starts to open but the redirect in it calls the default topic for child_1 and 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. |
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.
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 projects.
Next create any other child projects you require. These are also created in their own folders under projects.
To create the links:
Highlight the text that will be the link.
Click on Insert | Hyperlink or the hyperlink icon.
Click the "Link To" drop down 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!
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.
The next step is to create the references to the child projects and add the redirect to the only topic in this project. Reopen the parent project.
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 WebHelp tab in the window that displays.
Browse to a child project and highlight the project
file. This example shows what you will see in X3.
Open the topic in the parent project and add the line below to the Meta lines in the head section. Obviously you will need to amend the path and file name to whatever names you have used. Remember, you are pointing to the default topic in the target project, not the start page.
<meta HTTP-EQUIV=refresh CONTENT="0;URL=./mergedprojects/child_1/child_1.htm">
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.
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 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.
You do not have to publish each time you generate and you can skip steps 2 - 4 in this section for now if you wish.
Start the Generate Wizard
and generate to the rh_generate folder. I recommend the name of the file
you specify here is different to the default topic to avoid confusion.
I use index.htm which is typically the home page for a web site.
Publish to the rh_publish directory. The image
shows the window after the server name and url have been created.
To create the server name, click on New and enter
the path in the window displayed.
You will have to recreate the server details in the demo as these are
lost when the files are transferred from one PC to another.
The difference between generating and publishing is something that can confuse. In most cases you generate to your hard disk and you publish to a server. Anything already in the generate target when you generate gets deleted and new content is created. Anything in the publish folder is not automatically deleted, that only occurs if you select the Republish All option. That difference means you can tweak things in the publish folder that will not necessarily get overwritten next time you publish. Sometimes they will but you will know what you have tweaked and can test. You will soon know what to check. Step 8 is an example of the type of tweak you have to consider.
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:\rh_generate\mergedProjects\child_1. Don't forget you also need to tick the browse sequence check boxes for the relevant child projects.
In the above example you will see the "P" in mergedProjects is upper case.
The merge module was introduced with RH X3 when I reported this as a bug because it can cause problems on Unix servers, or if your developers insist on all lowercase path and filenames for some reason. Click here for additional information.
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 cae, 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 lower case, 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 as it will be "wrong" everywhere. Consistency is what matters. |
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. |
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 will probably find the first topic displayed does not synchronise. Thanks to Jose Badeau there is now a fix for this.
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.
RH does not check external links which includes links between the child projects so you may want to consider a web site link checking utility.
If you have Dreamweaver or FrontPage, they both have link checkers. Initially I used Dreamweaver for this check. It also reports various broken links in various js files but I did not find that these affected any functionality.
Now I use Xenu. This is a freeware program which does an excellent job in a fraction of the time.
Go to either your rh_publish folder (or rh_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.
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 FTP the files, you cannot 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.
The content of files in the generated output is the same as the content of the files in the published output. Thus if you do not have the task of getting the files onto the server, you can give the generated output to your developers, burn it to CD or whatever.
If the mergedProjects bug described in Step 7 is an issue for you, then you may wish to publish to your hard disk for the reasons stated there.
Take a copy of the full merged webhelp 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 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.
From time to time I am asked about splitting a large existing project into smaller chunks for merging. I haven't prepared detailed notes but here's the text of an email I prepared to help someone.
Click here.
First it is vital that you understand how merged webhelp works before you
attempt to split an existing project. You really do need to download the demo
and understand the mechanics of it. If you don't do this first, it is like
driving into an unlit tunnel without your car headlights off. You will crash.
Before you start and every step of the way, create backups of your work. If
you do that, recovery from any mistakes is easy.
When I broke my project up I was starting with about 10,000 topics. I worked
out a logical split of the topics which for this purpose we will say was General,
Product A and Product B. Then I created three folders in the single project
called General, Product A and Product B and reorganised all my folders and
files so that the topics were under the right folders. Doing it this way means
that RH amends all the links as it moves things around.
Later in the process there will be a lot of find and replace operations and
it is important that they can find unique folder paths. So at this stage I
prefixed many of my folders with a tilde ~ symbol as that is unlikely to occur
otherwise.
Having done that you now create folders for the required number of child projects,
three in this example. Copy the full project into three folders so that at
this stage you have three folders each with a copy of the full project.
The next step is to delete from each child those topics that are not part of
that child. When you delete the topics you will be prompted whether or not
you want to remove references in other topics. DO NOT remove the references,
you want the broken references as they are the evidence later that you have
repaired those broken links. The index will pretty much sort itself out as
it will delete references to topics that have been deleted. The TOC will need
a sort out but again I would leave that at this stage.
You are now at the trickiest part of the operation, repairing the broken links.
You may not have many but it is more likely that you will have lots. Here you
need a good Find and Replace tool and certainly one that is better than that
supplied with RoboHelp. Some people recommend BK ReplaceEm as it is free but
I much prefer FAR (free for one month and then inexpensive). What you need
to do is examine some of the broken links. You are looking at what the link
is (which will be the relative path before this operation) and what it should
be (what the relative path is now). That defines the Find and Replace. You
have to be careful here. It is very easy to not only amend the links you mean
to but also amend other links. Look to find something like "..\..\#path
rather than ..\..\#path (not absence of quote mark) as the latter would also
amend a link such as "..\..\..\#path because it would find that end of
the string. This is one area where you must back up frequently as you can do
several passes and get them right, then screw it all up in the next pass and
undo a few hours work.
After each Find and Replace operation open RH and check that the broken links
number is going down. You might have to open, close and open again, perhaps
making a small change to one topic.
Gradually you will work through all the topics in a project until the broken
links have been fixed. After that you turn to the TOC in that project and change
that so that it only points to topics that are in that project. (Again a tidy
up before you start will pay dividends here.)
Then work through the remaining child projects until everything has been cleared
up.
Create the parent as described in my topic and you are ready to generate your
merged webhelp.
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.
At the moment the cause is being investigated by the poster's developers and hopefully a solution will be found and published. Until then there are two options:
Typically a merged webhelp setup will have one parent and a number of children. All of these will be generated to one output folder. For some installations, the parent and all the children will be delivered, for others the parent and some of the children will be delivered. It could be a different combination of children for different installations and if there are many children, it would get tricky remembering all the combinations. It may also be further complicated by some of the installations needing different versions of a child project.
This was the scenario that faced Phil Wells. With around 150 child projects, you can imagine his nightmares. Phil's neat solution was to share the job between many parents! Here is how it works.
Let's take an example. Parent 1 uses say three of four children but needs two variants of say child four.
This requires some careful thinking during the setup but once that is done, it becomes plain sailing. The parents shoud rarely change using this method as the children are likely to remain constant. What does change is the content of the child projects. When Phil makes a change, he simply generates all the webhelp outputs and knows for sure that all the output combinations in his Outputs folder are up to date. Alternatively he can make changes to the children over time and then just run through all the outputs. What he does not have to do is enter the error prone area of what output requires what combination of child projects and variants thereof.
Another reason that Phil did this was to enable him to create webhelp and CHM help from the same source. The links are written differently for these two outputs so for every link, you have to write it in the format the webhelp requires and the format that CHM requires and then apply conditional tags to each. Phil then targetted those outputs to suitably named folders within Outputs. With the CHM output, you do not want the redirect described above. In this parent, you create a Welcome page and keep the content minimal.
Date |
Changes to this page |
| 03 May 2008 | Backslashes in the redirect changed to forward slashes. |
| 12 Jan 2008 | Confirmation added that instructions remain good up to and including RH7. |
| 06 Jun 2007 | Multiple Parents and Multiple Outputs section added. |
| 15 Mar 2006 | Guidance for splitting a large project added. |
02 Nov 2005 |
Section added re Citrix issue. |
13 Aug 2005 |
Difference between generating and publishing added to Step 6. |
| 18 Mar 2005 | Link added to new topic describing how to create merged webhelp using RoboHelp for Word. |
| 31 Dec 2004 | Step 7 amended as the capital P in mergedProjects has not been corrected in RH X5. |
| 06 Oct 2004 | Unix instructions reworded to make clearer. |
| 20 Aug 2004 | Step 8 revised to cover the Xenu link checking program. |
| 19 Aug 2004 | Wording of "Why Structure is Important" section revised. Step 2. Additional paragraph about skins. Browse sequence information moved to here. Step 5. The need to point to the default topic added. Step 7. Amended re the mergedProjects bug. Step 10. Expanded to provide more information about generating and publishing. |
| 18 Aug 2004 | The need to create and enable a browse sequence in the parent project added. This is necessary even though the user will never see it. |
| 17 Aug 2004 | Note added covering the differences with how the TOC can be displayed according to whether you use the new method or the old method. Step 10 added covering:
|
| 06 Aug 2004 | Working demonstration built into the topic. Topic amended to distinguish between the recommended structure which not all users will require and those steps that apply to all merged webhelp production. Topic also amended to provide information if users detect any screen flicker when opening the help. Confirmation added that the mergedProjects bug has been fixed in X5. See Step 7. |
| 01 Aug 2004 | Folder names for source projects changed
This is to make clearer the difference between the parent and the other projects and reserve the name "mergedprojects" for the output folders. The download has been updated as well. |
| 23 Jul 2004 | Topic extensively revised to cover a new simpler method. My original solution was to use some unique folder names and then undertake a mass find and replace exercise on the output. An email from another author on a different aspect of merged webhelp identified a different approach. It set me thinking and I then modified that method to develop what I think is a much simpler solution. My main project now has over 11,000 files in some 700 folders and this new method gives me a significant time saving when generating and publishing. |
| 15 Jun 04 | Warning added to not use spaces in project names. |
