Creating Context-Sensitive Cross-References

For print-based and EPUB output you can create context-sensitive cross-references, which automatically change the text in the link based on the relationship of the cross-reference and the target location.

Using context-sensitive cross-references is simply a matter of using the correct command. In other words, instead of using the simple {page} command, you can use the {pageref} command.

Example You use the plain {page} command. Perhaps the complete format that you create for a cross-reference style is this:

See "{paratext}" on page {page}.

When you generate the output, this cross-reference will be converted to something like the following, regardless of where the link falls in relation to its destination:

See "My Information" on page 42.

However, let's say that you use a slightly different format, something like this:

See "{paratext}" {pageref}.

When you generate the output, what you see in place of {pageref} depends on the relative closeness of the link and the destination. It might be translated as any of these:

See "My Information" below.

See "My Information" above.

See "My Information" on previous page.

See "My Information" on page 42.

How to Create Context-Sensitive Cross-References

  1. Go through the process of inserting or editing a cross-reference. See Inserting Cross-References and Editing Cross-References.
  2. In the Insert Cross-Reference dialog, select either New or Edit, depending on whether you want to create a new cross-reference style or edit an existing one.

  3. Provide a format in the Enter format field. This format can be a combination of text and automated commands.

    When creating this format, make sure you include the {pageref} command in it. You can find the command by selecting either Show All or Show Page Commands. When you find the {pageref} command in the list, double-click it to add it to the format. Here is an example of a format that contains a context-sensitive cross-reference command: See "{paratext}" {pageref}.

  4. Click OK.

Note The default format for the primary cross-reference style (MadCap|xref) is already set up to create context-sensitive cross-references. If you have been using the old default cross-reference formats and want to continue using them, you can edit the MadCap|xref style and replace the new formats with the older ones. The old cross-reference format for the default style medium is See "{paratext}". The old format for the print medium is See "{paratext}" on page {page}. See Editing Cross-Reference Style Formats.

If you have already edited the MadCap|xref style in a stylesheet before upgrading to a new version, your custom format will not be affected. You will only see a change if you have never changed the default format from older versions.

Note You also have control over the text used in context-sensitive cross-references (e.g., instead of the text displaying "on next page," it can be customized to display "on following page"). You can customize this text through the use of a language skin. See Editing Text for Context-Sensitive Cross-References.