Merged WebHelp - TOC Links

What's covered?

The normal way of producing the TOC in merged webhelp is to create a TOC in each project covering the topics in that project. In the parent project, you add a reference to the sub project wherever you want it to appear in the combined TOC. Sometimes in a merged webhelp setup, a book in the parent project, or one of the others, needs a reference to a topic in another project and this topic describes how that can be done.

The first method that was posted on this site is described under Old Method and is left posted for the benefit of anyone who has used it, wants to continue using it, but needs a reference to the details. The method is quite straightforward once you have got your mind around it and it's not as fiddly as it looks but the New Method is easier.

Hallie Bourne suggested a method that is much simpler and doesn't need tweaking each time you generate. See New Method.

New Method

Use a redirect!

Say you want a page in the TOC of Child Two that links to a topic in Child 3.

  1. In Child 2 you create a topic that is like the blank topic in the Parent project.
  2. Open it in HTML View and add a redirect with the relative path from that topic to the target topic in Child 3. Redirects are described in the articles on merging webhelp.
  3. In Child 2 add the redirect page to the TOC. That will be simple as you are adding a page that is within the project.

When the user clicks that page in the TOC, it will open momentarily and redirect to the required topic in Child 3. The user should not see the redirect page. You may want to store all your redirect pages in one folder so that you know where to locate them. That is not essential.

Old Method

First, create the new TOC page under whatever book you want. In this example, I will be using the same projects as in Merging WebHelp (the original method) and creating a link from the TOC in the main project to a topic in Project B. In the main project, create or go to the required book and then click on the Create New Page icon to display the TOC Page Properties.

To target the topic in the other project, you need to enter something in the Link To field.

Work out the relative path to the target topic as it will be in the published output (and I emphasise "in the published output", not the source). So creating a link from the main project to Topic 1 in project B in the projects shown in the example...

 

...the link would be

FROM

\Test Publish

TO

\Test Publish\mergedprojects\module_B\Module_B_Topic_1.htm

which would give a relative path of

.\mergedprojects\module b\module_b_topic_1.htm

Now for the fun bit, if you enter that correctly in the Link To field of the properties for the TOC page, RH will remove the .\ at the beginning. Save the TOC and go back to the properties and you will see RH has changed the path. If you were to publish now and this link was the only one in the book, you would not even see the book in the TOC.

Now re-enter the path as

..\mergedprojects\module b\module_b_topic_1.htm

Note the extra stop and I know it's wrong, just bear with me.

Publish the projects again and now you will see the Book in your TOC. You will also see the link but it will not work at this stage. You will get "Page cannot be displayed"

Now you need to locate the whxdata folder in your published output and open the file whtdata0.xml in Notepad or any text editor. You will see lines something like

<book name="Another Project" >

  <item name="test" url="..\mergedprojects\module b\module_b_topic_1.htm" />

Remove the extra full stop (period) at the beginning of the url so that it reads

url=".\mergedprojects\module b\module_b_topic_1.htm"

and open the published help.

Hey presto, it works.

I haven't tested in a full scale project to see if there are any issues but I cannot see any except as below. Any links in the target topic itself will not have been changed so they should be OK. Also any other links to the target topic will not be affected so they too should be OK.

Care when republishing

Each time you publish your webhelp, if you make a change to either the TOC or you select the Republish All checkbox, then RH will rewrite whtdata0.xml. Your previous amendments will be lost and have to be redone. If you haven't changed your TOC, then either clear the Republish All checkbox or save a copy of whtdata0.xml somewhere safe and replace the new version after publishing.

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
01 Mar 2009 Simpler method added.

10 Jan 2004

New topic