About Cross-References

Cross-references let you create automated links that are based on commands you provide. This allows you to keep links consistent and change them in just one place by using the <MadCap|xref> style. Commands are contained in brackets (e.g., {paratext}).

example

Let's say you have a topic with the title "About Things," and there are several other topics in your project that you want to link to that topic. Furthermore, let's say that each one of those links needs to have the same text (e.g., "For more information see 'About Things.'")

Now, you could use a text hyperlink in each of those topics; this would be a good option if the text in each of the links needed to be different. But instead you create a cross-reference using the <MadCap|xref> style. In this style you specify the exact text mentioned above, along with the {paratext} command, which displays the text of the first paragraph it finds (such as a topic heading). You can use that cross-reference style anywhere that you'd like to create a link using that configuration. When you insert the cross-reference it includes the text you provided (e.g., "For more information see"), and it uses the {paratext} command to display the heading text for the destination topic (e.g., "About Things"). When you put it all together, you have "For more information see 'About Things.'"

Later, if you decide to change the heading text of the destination topic to "About Whatchamacallits," the cross-references will be updated automatically when you generate the output. The new heading will automatically be reflected in all of the links using that cross-reference style (i.e., "For more information see 'About Whatchamacallits'"). If you had used text hyperlinks in a situation like this, you would need to find and replace the text in all of the pertinent links manually.

example

Here is an example of a cross-reference format, using a combination of text and commands:

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

A format such as this might be translated in the output as something like this:

See "Dogs and Cats" on page 93.

If you are using auto-numbers in your content (e.g., for figure or table numbers), you can create cross-reference formats that include the auto-numbers. For more, see About Auto-Numbers.

example

Let's say that you have created auto-numbers in order to number all of the figures in your project. Perhaps your auto-number format is set up to show the word "Figure" followed by an incremented number and a colon (e.g., Figure 4:, Figure 5:, Figure 6:). In addition, wherever you apply auto-numbering in a topic, you might manually type a short description of the image (e.g., Properties Dialog). So in the output under the graphic, the user might see something like this:

Figure 4: Properties Dialog

Now let's say that you want to insert a cross-reference in another topic that points the user to the Figure 4 graphic. To do this, first of all you would probably want to insert a bookmark at that auto-number location so that you can point directly to that paragraph when you insert the cross-reference. Then you can create a special cross-reference format that includes the auto-number portion of that paragraph. The following two auto-number commands can be used:

{paranum} This command displays all of the content in the auto-number format, including any text before an auto-number, the auto-number itself, and any text after the auto-number. Using the example provided above, this command would display something like this in the cross-reference:

Figure 4:

{paranumonly} This command displays any text before an auto-number and the auto-number itself. However, it does not show any text after the auto-number (such as a colon). Using the example provided above, this command would display something like this in the cross-reference:

Figure 4

In addition, if you want to include any text that you manually add in the topic after the auto-number format, you can add the {paratext} command to the cross-reference format. Using the example provided above, this command would display something like this in the cross-reference:

Properties Dialog

Therefore, suppose your entire cross-reference format is this:

See "{paranum} {paratext}"

In that case, the output would display something like this:

See "Figure 4: Properties Dialog"

On the other hand, suppose your entire cross-reference format is this:

See "{paranumonly} {paratext}"

In that case, the output would display something like this (without the colon):

See Figure 4 Properties Dialog

Again, when you insert the cross-reference in a topic, make sure you select the format that you created, and also remember to link to the bookmarked paragraph where the auto-number appears.

Tip: If you insert a cross-reference into a topic and it initially does not look the way you expected, try updating the cross-references in the topic. See Updating Cross-References.

Command	Description
b	Start bold text
/b	End bold text
bg	Start new background color
/bg	End background color
color	Start new text color
/color	End text color
default	Reset all font changes
ext	File extension
family	Start new font family
/family	End font family
file	File name, including extension
filename	File name, without extension
h1	Text of first heading 1 paragraph
h2	Text of first heading 2 paragraph
h3	Text of first heading 3 paragraph
h4	Text of first heading 4 paragraph
h5	Text of first heading 5 paragraph
h6	Text of first heading 6 paragraph
i	Start italic text
/i	End italic text
page	Page number
pagecount	Page count
pageref	Context-sensitive page reference
paranum	The auto-number text of bookmarked paragraph.
paranumonly	The auto-number only of bookmarked paragraph
paratext	Text of bookmarked paragraph
paraxml	Text and markup of bookmarked paragraph
path	File path
size	Start new font size
/size	End font size
sub	Start subscript text
/sub	End subscript text
sup	Start superscript text
/sup	End superscript text
title	Title of document
u	Start underlined text
/u	End underlined text
url	File path, URL syntax

Cross-references can be used to convert online links to "page number" references if you are producing print-based output.

For example, a link that is displayed as "See My Topic" in online output can be displayed as "See page 36" in printed output. This is done by using a print medium in your style sheet. You also need to make sure the print medium is associated with the target you want to build. For more information see About Style Sheet Mediums.

You can do the following with cross-references.

• Insert You can create new <MadCap|xref> styles, add commands, and add the cross-references to topics. See Inserting Cross-References into Topics.
• Create context-sensitive cross-references For print-based 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. See Creating Context-Sensitive Cross-References.
• Edit You can change the style and settings for a cross-reference. See Editing Cross-References.
• Update You can refresh your cross-reference links manually so that they display updated information. See Updating Cross-References.
• Single-source You can use style sheet mediums to single-source your cross-reference formats. For example, you can create a cross-reference format that displays as "See 'My Topic'" in some outputs (e.g., online documentation) but as "See 'My Topic' on page 44" in other outputs (e.g., print-based formats). See About Style Sheet Mediums.