Authoring - Detecting and correcting invalid pointerpaths

If pointers are removed from a path or if topics and/or folders in the path are moved to other locations in the tree then hyperlinks with pointerpaths could not work properly. To demonstrate this we continue with the example in using pointerpaths in hyperlinks. In this example the hyperlink target 'About the shark' has the pointerpath 'Shark.About' in the 'Fishes' book. Let's see what happens if we remove the 'About' pointer in the path by clearing it in the table on the right as in the next image.

Destroying a pointerpath

Just double click in the cell in the 'Pointer' column and delete it. Save the containing folder and select the 'Related topics' in the 'Book: Birds' This is the topic that contains the hyperlink with the pointerpath. If the pointerpath is invalid or broken the hyperlink is marked with an error sign: a red square with a white cross.

Hyperlink with an invalid pointerpath

If you don't see the invalidation sign, refresh the topic. The next image gives you a closer look at that sign.

Hyperlink with an invalid pointerpath

In a multi authoring environment other authors can change topics that are already retrieved in your Workbench. In the example above some other author could have restored the pointer in the path. If you perform a refresh of the topic that includes the hyperlink with the invalid pointerpath, the hyperlink will become valid again and that sign will disappear.

To see the behavior of such a hyperlink you should preview the 'Book: Birds' and select 'Related topics'.

Previewing content containing a hyperlink with a broken pointerpath

Next, click on the hyperlink. The system still knows the context of the hyperlink which is the 'Fishes' book. That book will be opened but the pre selection of the hyperlink target will stop at the point where the path was broken which is the 'Chapter: The shark'.

Trying to jump to a hyperlink with a broken pointerpath

So, if you reorganize your books and chapters it is strongly recommended to verify the hyperlinks and to correct broken pointerpaths. You use the search function to obtain this. It will scan a folder and its dependants for hyperlinks. The validity of the included pointerpaths will be indicated in the search result. This is demonstrated in the next images.

Opening the search

Popup the menu of the project folder and select 'Search'.

Searching for hyperlinks

On the 'Search' window you click on the 'Other' tab. Next, you choose the 'hyperlinks' option. The 'Internal' option is to locate the hyperlinks to objects within the scope of the folder and its dependants on which you start the search. With the 'External' option you locate the hyperlinks to objects outside that scope. The default is set to locate all the hyperlinks.

If you click 'Start' the search runs through the folders and the included hyperlinks are shown in the result list on the bottom of the Workbench.

Hyperlinks found

About the buttons of the search result

The buttons on the top right of the Search pane allow you to perform the following operations.

The Search pane

With the ‘Refresh’ button on the search result you can re-execute the last search. The folder or the topic that was the object of that search will be automatically reselected and the Search window will popup. The search options chosen before are preselected. You just have to click 'Start'.


With the ‘Print’ you can print the overview list. The content however is not included in the print.


The ‘History’ button on the search result pane allows you to reshow previous search lists (the 5 last search operations are kept in the history queue).


With the ‘Remove’ button you can clear a list from the history.


With the ‘Search’ button you can launch a new search on the object currently selected in the tree. The difference with the 'Refresh' is that you will have to set all the options and after the search operation, a new item will be added to the 'History' list.


The 'Pointerpath' column indicates the hyperlinks with a pointerpath. Invalid pointerpaths are marked in red. You can click on the column heading to sort the result. If you double click on a found item or popup its menu and select 'Go to' the topic that contains the hyperlink will be located in the Workbench tree and the hyperlink in the topic will be selected.

If you then open the hyperlink properiies by popping up the menu on the hyperlink and selecting 'Hyperlink properties' you will see that the pointerpath field on tthe window has a red background.

Hyperlink properties with an invalid pointerpath


To correct this you can do two things: copy the target and paste it over the invalid hyperlink or restore the pointer path  Either way you need to locate the target. You achieve this easily by popping up the menu of the hyperlink and selecting 'Where used'.

Requesting a hyperlink's where-used list

The 'Where used' pane on the bottom of the Workbench allows you to locate the hyperlink target. If there are multiple items in the list the 'Location' column can help you to find the correct item. Double click on the item to locate it in the tree or popup the menu and select 'Goto'.

The hyperlink target is selected in the tree.

Locating a hyperlink target object

Next, you copy the object in the tree and reselect the topic that holds the hyperlink. In this example it is 'Related topics' in the 'Fishes' book. Next, paste over the invalid hyperlink.

Pasting over an invalid hyperlink

A message box will ask you to confirm the paste.

Confirming the paste over a hyperlink

If you click 'Yes', the hyperlink is corrected.

Another way to correct the hyperlink would be to examine and restore the pointerpath in the folder(s) of the hyperlink target. In this example it is the 'Shark' chapter in the 'Fishes' book.

Restoring the pointerpath in the folder


 About HelpServer
 Starting up and logging on
 The basic working principles
 Using the content in help and documentation systems
 Formatting the content
 Searching and replacing text
 Reusing content with shares
 Navigating with hyperlinks
 Navigating with pointerpaths
 Creating a pointerpath
 Searching for a pointerpath
 Using pointerpaths in hyperlinks
 Detecting and correcting invalid pointerpaths
 Using bookmarks and jumps
 Duplicating content with clones
 Using tables
 Including media files
 Navigating to web pages
 Using embedded chunks
 Including html code
 Navigating with menus
 Using snippets
 Spelling checking
 Using the view mode
 Creating an index
 Creating a FAQ
 Creating a glossary
 Team authoring
 Working with projects
 Setting up structured authoring
 Generating file based output
 Creating printed output
 Importing files and folders
 Loading files in the project gallery
 Converting legacy content
 Including legacy content in real time
 Transferring objects between installations
 Customizing the look and feel
 User accounts
 Working with templates
 Working with metadata
 Workflow management
 Using event exits
 Appendix A: The URL parameters
 Appendix B: The object indicators
 Appendix C: Play Javascript