Merged WebHelp - Nested TOCs

 

 

What's covered?

This page describes an earlier method I used to create merged webhelp. It will still be required if in the merged TOC you want to nest the book for a child project within a book in the parent project. In all other circumstances, I would strongly recommend the other methods described for your version of RoboHelp.

The screenshots are from an old version of RoboHelp but the functionality is virtually the same in later versions.

Demo Project

Click here to download the demo projects.

Step 1 - Create Required Structure

The MergingWebHelpDemo_Version_2.0 directory is required only for the purposes of this demo.

TestCreateHelp holds all the projects to be merged. The main project goes in ~main and ALL others go under ~sub.

The mpj file for the main project will be in ~main. The mpj file for the sub projects will be in the projects directory e.g. ~sub\Module B in this example.

TestGenerate and TestPublish can be within Test CreateHelp but not within ~main or ~sub. Do not create any sub directories, this is covered later.

If you want the TOC to auto-synchronise with the topic displayed, make sure your project names do not contain any spaces. This can cause problems with synchronisation as described in Snippets.

 

In your project:

You can call TestCreateHelp whatever you want.

You can call ~main and ~sub whatever you want but there are some very important rules:

- The names must be strings that will not appear anywhere in your HTML (other than the paths created!). This is the reason I precede the names with the tilde symbol as that is not used in code.

- The sub directory names and the names you give the sub project when you add it to the TOC in the main project must be exactly the same. RoboHelp uses the sub project name that you enter as a marker in the TOC to create the sub directories to which you generate and publish. Those sub directories must have the same name as where you create the help.

Follow eHelp's instructions for including the TOC from the sub project(s) noting the above rules re naming.

Step 2 - Develop your help and create links between the projects as required

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).

CARE IF YOUR OUTPUT IS 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 webmerge 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. This can result in a mismatch of case causing broken links on a Unix box. You must ensure the case is the same for the files and links in your output.
This mismatch is not an issue on Windows systems.

Step 3 - Generate and Publish the Main Project

Generate to the TestGenerate directory.

 

Publish to the TestPublish directory. The image below 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.

 

Step 4 - Generate and Publish the Sub Project(s)

In Step 3, RoboHelp will have created additional directories under TestGenerate and TestPublish. Generate and publish each sub project to the appropriate directory under merged projects.

 

For Module B, generate to \TestGenerate\mergedProjects\Module B.

 

For Module B, publish to \TestPublish\mergedProjects\Module B. The image below 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.

 

Step 5 - Amend the Relative Paths.

If you now open the webhelp by double clicking Main_Module_A.htm in Test Publish, the TOC and Index should appear as required and will access the correct pages. Links in the topics however will get "Page cannot be displayed" errors.

Use the Multi-File Find and Replace Tool or some other application such as FAR to edit the published files.

This step will change the content of TestPublish so I have created a copy of the directory as it is at this stage and called it TestPublishOriginal. If you want to see the difference between TestPublish before and after making the following changes, compare TestPublish and TestPublishOriginal.

Point to TestPublish including sub directories

Point the Find and Replace tool to TestPublish including sub directories. You can exclude the mergedProjects directory in this step.

Find ../~sub
Replace mergedProjects

 

Point to TestPublish\mergedProjects including sub directories

Point the Find and Replace tool to TestPublish\mergedProjects including sub directories.

Find ~main/
(note the slash at the end of the string)
Replace nothing, there is no replacement string

Step 6 - Trace Broken Links

Now the links between projects should also work and you can test them. As RH does not check external links, 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.

Step 7 - Delivery

Generate / Publish. What's the difference?

The content of the files is the same. The publishing process makes various checks and if you select not to republish all, it will just update what has changed. You can FTP the generated files to the server if you wish but you then have the task of making sure you update the right files, or you can update everything.

What if all the projects are not required on a particular installation?

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.

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

07 Feb 2017

Topic reviewed. No changes made. Any screenshots may differ in your version of RoboHelp but the functionality is the same.

20 Aug 2004

Step 6 revised to cover the Xenu link checking program.

17 Aug 2004

Step 7 added.

23 Jul 2004

This topic covers the original method I described for creating merged webhelp. The sections that were before Step 1 have been removed but the topic is otherwise "as was".

15 Jun 04

Warning added to not use spaces in project names.