MADCAP FLARE: Hyperlinks vs. Cross-References

If you look on Flare’s Insert ribbon, you’ll see one icon for Hyperlinks and another icon for a less familiar feature, the Cross-Reference. Both are flagged on the Insert ribbon and the Topic Editor toolbar in the image below.

Also in the image below, notice that the topic has both a hyperlink and a cross-reference that seem to do the same thing: link users from one topic to another. However, they’re created differently and work differently.

Hyperlinks have been the link mainstay for years but they have two problems:

• A hyperlink is linked to a target but doesn’t “know” what its target actually is. For example, the hyperlink in the image above points to the “Frappe” target topic. If I change that topic’s title to “Milkshake,” the hyperlink still works but the wording is wrong. To fix this, I need to change the word “frappe” in the link to “Milkshake.” This is easy to do with search and replace, but it’s just one more thing to worry about.
• A hyperlink works fine in online outputs and even for print outputs like a PDF. But what happens if users print a PDF? The link obviously doesn’t work; users have to find the target via the table of contents or the index, if you created one. Otherwise, users have to flip through the pages to find the right content. The only solution is for you to change each hyperlink to a page reference by hand, which doesn’t even bear thinking about.

Cross-references, also known as “xrefs,” solve both these problems nicely and add several other benefits.

An xref “knows” what it’s linked to because it links to the target topic’s title. This means that you don’t have to type the text of the link, as you do with a hyperlink. Instead, the xref grabs the title of the target topic and automatically uses it as the link text. And if the target topic’s title changes, the link text changes automatically. For example, if I change the name of the target topic in the example above from “Frappe” to “Milkshake,” Flare changes the wording of the xref to match, as shown in the image below (where the wording of the hyperlink is now wrong). This makes link maintenance more efficient.

• Flare automatically updates the wording when you generate a target that contains the topic. If you want to update the xref during development, without having to generate the target, choose Tools > Update Cross-References to update the xrefs for the topic.

• When you create a print target like a PDF, Flare automatically converts the xref’s format from a link style to a page reference. For example, “cross-reference to Milkshake” in the example above changes to “See Milkshake on page XX” or similar wording (which you can control) by modifying the settings of the mc-format property for the MadCap|xref style for the Default and Print mediums. If you have to create online and print targets, this automatic style adjustment may be enough to make you a big fan of xrefs.
• Xrefs can adjust their wording based on the proximity of the starting topic to the target topic. If the two topics wind up being two or more pages apart in your print output, Flare automatically changes the xref wording to “See XX on page YY.” However, if the starting and target topics wind up one page apart, Flare automatically changes the xref wording to “See XX on the next/previous page.” And if the starting and target topics wind up on the same page, Flare automatically changes the xref wording to “See XX above/below.” This puts the wording of the link into a realistic context.

Xrefs aren’t perfect. They can only link between topics in a given output target. They can’t link to topics in different output targets, or to external files such as external URLs or PDFs. For those, you still have to use traditional hyperlinks. 

Even with that limitation, I consider xrefs to be one of the most useful features in Flare and one with no equivalent in competing tools (that I’m aware of). I’d been using hyperlinks since 1986 by the time I got involved with Flare in 2004 and didn’t quite understand what an xref was at first. But when I saw what they could do, particularly the automatic style adjustment feature, that made me a stalwart fan of xrefs. Give them a try. I think you’ll be pleased.

Neil Perlin is MadCap-Certified for Flare and is a long-time consultant, troubleshooter, and trainer for the tool, going back to MadCap’s founding in 2004. He also has years of experience with older tools like RoboHelp and Doc-To-Help and now defunct tools like ForeHelp. He is also a certified app developer, trainer, and consultant for the ViziApps app development platform. You can reach him at nperlin@nperlin.cnc.net and at NeilEric on Twitter.