Preventing dead links

Excluding topics from your output can create dead hyperlinks. If there are links to the excluded topics in other topics those links will not have any targets and will produce errors or do nothing when the user clicks on them. You need to plan your project to prevent this from happening.

Help & Manual has several functions that can help you to prevent and eliminate dead hyperlinks caused by excluding topics. If you use them correctly you can easily locate all potential dead links and automatically replace them with alternative text or links.

Whenever you set an include option to exclude a topic you should always use the Find Referrers function to check for any links to the excluded topic in other topics.

1.	Select the topic you plan to exclude in the Project Explorer. You can select either a TOC item or a topic file.

2.	Right-click on the topic name in the Project Explorer and select Find Referrers in the context menu. Alternatively you can also select Find > Find Referrers in Project > Manage Topics.

3.	This displays the topic referrer report. Double-click on its title bar to display it in an external window, this makes it easier to use (double-clicking on the title bar again re-docks it to the Help & Manual window):

Links to the topic in other topics are listed in the Is referred by column. The Links to column only shows topics that the current topic links to, which you don't need to worry about here.

4.	Click on the links in the Is referred by column to display the topics so that you can use conditional text to eliminate dead links (see below). When you are finished you can return to the current topic by clicking on its link in the Topic column.

When you exclude topics from your published output you do this with include options. You can prevent dead links to the topic by using the exactly the same include options to also exclude the hyperlinks that would be dead. This is then automatic – the hyperlinks will always be excluded whenever the topic they link to is excluded, because they are both controlled by the same include options.

You can also use additional include options to include alternative text or even alternative links whenever the topic is excluded.

1.	Use Find Referrers (see above) to locate all topics containing links to the topic you want to exclude.

2.	Open the topic containing the link that you want to exclude in the editor and locate the link.

You now need to decide what needs to be excluded and replaced. We will assume that you want to exclude the entire sentence containing the link and replace it with an alternative sentence.

Excluding the link:

3.	Select the entire sentence containing the link and select the Conditional Text Tool in Write > Insert Object.

4.	Now select exactly the same include options that you are using to exclude the topic the link points to and click on OK.

In the example above we have selected Webhelp and Adobe PDF. This means that the link will only be included when you publish to Webhelp or PDF, it will be excluded from all other formats. Since the options match those set for the topic the link points to it will be excluded whenever the topic is excluded and included when it is included.

Including alternative text and/or links:

5.	If you want, you can now write an alternative sentence with or without a link to a different topic and use conditional text to include the alternative text whenever the original text is excluded.

The easiest way to do this is with IFNOT. In the above example we would also select Webhelp and Adobe PDF, but in combination with IFNOT instead of IF. This will ensure that the alternative is always included when the original is excluded, and vice versa.

These options can be configured in View > Program Options > Compilers. They not a real solution. They should only be used as a safety net to handle any dead links you may have accidentally missed when planning your project.

Option 1: Export excluded topics if referenced by another topic

This option prevents dead links by exporting your excluded topics when you publish if there are any other topics that contain links to them. When this is done no TOC entry is exported for the topic, so it can only be displayed by clicking on the links to it. Don't use this option if the topics you are excluding contain information you don't want a specific user group to see!

All nominally excluded topics that get included by this option will be listed as "implicitly exported" in the compiler report when you publish your project.

Option 2: Remove dead links to topics that have been excluded

This option simply deactivates dead links to topics excluded from your output. The link caption text is still there but it is normal text, no longer a hyperlink. This is definitely safer than Option 1, because it always ensures that excluded content remains excluded. However, depending on the context the plain text in place of the links may be confusing for your users.

All links turned into plain text in this way are listed in the compiler report.

Help url: http://www.ec-software.com/help/index.html?hm_advanced_conditions_deadlinks.htm