Understanding hyperlinks vs. cross references

[amatsumoto]

I've been reading about the cross reference feature, but I'm not sure I'm clear on when you want to use it vs. a hyperlink. Here is what I'm thinking, but I'd like to know how others are using the two:

• Cross references sound like a better choice when you have a reference to a topic and your content is going to be used in both a help system and print output that requires a page number reference. You set up xref styles in the stylesheet so that the help version looks and works like a link and the print version provides a page number (or whatever you need). They also sound handy because if your referenced topic text changes, so does the link or cross reference text.

• Hyperlinks are a fine choice is you don't need page number cross references in a book, or if you have links to web pages or other things like that.

Is that how others are using this?

I have a two more questions:

• If I do need to use cross references in order to get page numbers to show in printed output, is there a way I can convert my current hyperlinks in the small help system I have now, or do I have to manually change them to cross references?

• If I'm getting how cross references work, it doesn't appear that you can target a specific section in a topic, is this true? For example, say I have a topic that starts with an h1 (which I can x-ref), but it is the third h2 that I really want to x-ref. Do I have to do this with a bookmark? And can a bookmark link in help output be coaxed to show a page number in print output?

Thanks,
Abby

[KevinDAmery]

I've been reading about the cross reference feature, but I'm not sure I'm clear on when you want to use it vs. a hyperlink. Here is what I'm thinking, but I'd like to know how others are using the two:

• Cross references sound like a better choice when you have a reference to a topic and your content is going to be used in both a help system and print output that requires a page number reference. You set up xref styles in the stylesheet so that the help version looks and works like a link and the print version provides a page number (or whatever you need). They also sound handy because if your referenced topic text changes, so does the link or cross reference text.

• Hyperlinks are a fine choice is you don't need page number cross references in a book, or if you have links to web pages or other things like that.

Is that how others are using this?

I have a two more questions:

• If I do need to use cross references in order to get page numbers to show in printed output, is there a way I can convert my current hyperlinks in the small help system I have now, or do I have to manually change them to cross references?

• If I'm getting how cross references work, it doesn't appear that you can target a specific section in a topic, is this true? For example, say I have a topic that starts with an h1 (which I can x-ref), but it is the third h2 that I really want to x-ref. Do I have to do this with a bookmark? And can a bookmark link in help output be coaxed to show a page number in print output?

Thanks,
Abby

Hi, Abby.

What you're saying here is correct, although Cross References are also good for online output. There's one big gotcha, though: if you use variables, Flare currently doesn't resolve them correctly inside a cross reference. How much affect this has on you depends on how often you use variables--I use them all over, so I really can't use cross references effectively.

AFAIK, there isn't currently a way to automatically convert hyperlinks to cross references (Analyzer may be able to do it, but I can't say for sure).

And yes, you'd have to add a bookmark to link to specific topic section. It will show the page number automatically regardless of whether you use the topic heading or a bookmark, provided your cross reference is set up to show page numbers in your print output.

HTH

[doc_guy]

You've pretty much got the right idea on cross references and links.

I use both in my projects. I do online and printed output, and for the most part, I use cross references because I want the page number reference in my printed outputs. In my print section of my style sheet, I make sure my links look like standard paragraph text, so you can't tell it is a link. Then, if I'm including links in my help that I don't want to appear with page numbers in my printed output (or text that is excluded from printed output), then I usually use links instead of cross references for those links.

Cross references do update when you build your project, which is nice. There have been some issues in the past with cross references not pulling in variables if they are in the title of the style you're linking to. (So, if the document title includes a variable that represents your product name, the product name doesn't properly show up in the cross reference.) I'm not sure if that is still a problem, as I've re-structured my content to avoid the issue.

You can link to bookmarks in the text; Here is an example of how you set the settings in the X-Ref editor:



One caveat: Cross references don't work properly if you are linking to a drop-down heading. For some reason Flare grabs all the text in the entire drop-down as the text of the cross reference. Tom Johnson figured out a complex way around this, but I'm hoping this is a bug that is addressed in a later version of Flare.

[amatsumoto]

Thanks! This forum is so helpful!
Abby

[peterc59]

[Flare v11]

In my project, Analyzer recommends changing hyperlinks to cross-references. I wonder why this recommendation is made? is there a performance reason? [Yes, I understand the differences/advantages of the two techniques... but why should Analyzer care?]

Does anyone know of a way to automatically convert hlinks to cross-refs? I'm accomplishing the conversion, one topic file at a time, with a search/replace strings:

For example, imagine the tag in this text is a hyperlink that needs conversion: this is a <field> element

The hyperlink looks like this: <a href="filename.htm"><field></a>

The cross-reference looks like this: <MadCap:xref href="filename.htm"><field></MadCap:xref>

The first substitution is this:

• <a href=
• <MadCap:xref href=

The next substitution is risky... don't replace </a> anywhere except for the previously changed elements:

• </a>
• </MadCap:xref>