X-Refs vs. Bookmarks

[ccardimon]

What is the best factor to employ in deciding to use Cross References or Bookmarks to refer to text in a different topic? My main output is PDF.

[svt-user]

If my primary output was multiple PDFs, I might opt for Named Destinations. http://webhelp.madcapsoftware.com/flare ... ations.htm

However, bookmarking "future proofs" content for greater output flexibility down the road (such as doing WebHelp CSH in future) and the beauty of Flare is that you can always easily convert code with a good grep tool.

Rather than let Flare create names out of labels, I usually create a structured, feature-oriented namespace for content that maps content topics to the product, I then use that structure for consistent bookmark naming. Something like:

<product><mainfeature><subfeature>

<a name="SVT.DatastoreView.VMViewPanel">

These bookmarks provide the targets for X-refs and hyperlinks and also the mapping links for CSH. That way, I can easily see where a reference is going and it keeps everything independent of file name changes or content label changes.

[rob hollinger]

Cross-References refer to specific content in a paragraph or heading and display that content as part of the link. Think of them as Content References.
Cross-References specifically use Bookmarks and Headings to be able to retrieve the content from the "Linked to" file and insert it in the cross-reference.

If you insert a bookmark in a paragraph, you can create a Cross-Reference to that bookmark. In the Cross-Reference it will show the text of the bookmarked paragraph.

Cross-Reference:
See "This is my paragraph in TopicB" on page 1.
CODE:

Code: Select all

<MadCap:xref href="TopicB.htm#TopicB_bookmark">See "This is my paragraph in TopicB" on page 1</MadCap:xref>

In TopicB I have a paragraph that looks like this:

Code: Select all

<p><a name="TopicB_bookmark"></a>This is my paragraph in TopicB</p>