Automating Links Based on Commands

Example Here is the default format associated with the main MadCap|xref style (which you can change in the stylesheet, if you want):

{para}

The format consists of a single command, with no extra text. This particular command is designed to display the first paragraph that it comes across in the destination file, which is usually a heading.

If the destination file starts with the heading Installing Batteries, the inserted cross-reference link will simply display Installing Batteries in online output.

However, for print-based outputs, here is the default format associated with that same style (because it is using the print medium in the CSS file):

"{para}" {pageref}

This format uses two commands, with text (in this case, quotation marks) around one of the commands.

So in print-based outputs, the cross-reference link pointing to the Installing Batteries topic might display something like "Installing Batteries" on page 13.

Later, if you decide to change the heading text of the destination topic from "Installing Batteries" to "Installing Large Batteries," 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 (e.g., See Installing Large Batteries). 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.

Example You have created autonumbers in order to number all of your figures. Perhaps your autonumber 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 autonumbering 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 autonumber 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 autonumber portion of that paragraph. The following two autonumber commands can be used:

{paranum} This command displays all of the content in the autonumber format, including any text before an autonumber, the autonumber itself, and any text after the autonumber. 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 autonumber and the autonumber itself. However, it does not show any text after the autonumber (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 autonumber 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 autonumber appears.