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
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
Correcting
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