Cross References and Hyperlinks

Hyperlinks from topic to topic or to bookmarks have been part of Adobe RoboHelp from the first versions. Cross References can be thought of as links on steroids.

• Using hyperlinks, the text of the link never changes. If, for example, you change the name of the target topic, the link remains unchanged.
• Not so with cross references, they update automatically. If you create a cross reference to a heading, for example, and then the heading changes, so does the link to it.

 Cross references give more functionality than hyperlinks but link only to targets within the project. Hyperlinks can link to internal or external content.

Looking at how to set them up shows just how much more cross references give.

Setting Up Cross References and Links

The link icon on the toolbar has two options.

Insert a Cross Reference

Insert Cross Reference gives more specific targeting than hyperlinks.

Insert a Link

Insert Link enables you to link to topics, bookmarks and external content with options as to whether or not they appear in a popup.

Cross References

When you click Cross Reference a dialog will appear allowing you to choose the topic containing whatever you want to cross reference. Then you will see the Cross Reference dialog shown below.

Select Topic

This will show the topic chosen and give you the option to change it. 

Type

In this example Heading has been chosen. The headings in the selected topic are then displayed in Targets. The other options are:-

Bookmark

The Targets panel will display every bookmark in the selected topic.

Description

The Targets panel will display what has been entered in the topic's Description field in its Properties.

Figure

The Targets panel will display every figure with a caption applied in the selected topic. You can include a caption when adding a figure or you can add it later in Properties.

Paragraph

The Targets panel will display every paragraph in the selected topic. Select the required paragraph.

Table

The Targets panel will display every table with a caption applied in the selected topic. Tables without captions will not appear. You can include a caption when adding a table or you can add it later in Properties.

 HTML5 rules require the table to have a caption to make this work. What if you don't want a caption showing above or below you table? Format the caption text to be the same color as your background.

Title

The Targets panel will display the Title of the topic. Remember this is not necessarily the same as the topic's heading.

Format

Here you select how you want the cross reference to appear, the heading type has four options.

• Heading Text - Use this if you want the text only in all outputs.
• Page Number - Use this if the text in the topic is to show the page number only. This would only be used where the cross reference would only appear in PDF and Word outputs.
• Chapter Number - Use this only in cross references that are to appear in PDF and Word outputs. You will need to apply a condition tag to the cross reference and use a condition expression in online outputs.
• Heading Text with Page Number - This option will give the heading text only in online outputs but in PDF and Word outputs it will add the page number.

Targets

This field will show the options for the Type you selected, in this example the headings in the topic. If, for example, you later change a heading that is targeted from within the topic or from another topic, the text of the link will automatically be changed. If you selected to use page numbers, next time you generate a PDF or Word document, the page numbers will automatically refresh. You cannot edit the text as you can with hyperlinks as the whole point is to automatically keep the text of the link in sync.

Preview

In the Preview field you will see what will be shown in the topic based on the Format option you have selected and you can add a Screen Tip that will be seen when the user hovers the mouse over the cross reference. 

Screen Tip

Enter any text to be shown when the user hovers the mouse over the cross reference.

Display In

Select how the target is to be displayed

Hyperlinks

Hyperlinks have the advantage of also being able to link to external content such as web pages and create a link that opens a pre-formatted email in the user's default email client.

By default when you drag a topic from the Contents panel to a topic, it will be created as a hyperlink. In Edit > Preferences you can change the default so that a cross reference is created.

Converting Hyperlinks to Cross References

If you have an older project and want to convert the hyperlinks to cross references, there is a script that will do that for you.