Flakey cross references

[Combs, Richard]

Steve Johnson wrote:
 
> I've had it both ways but as a best practice you need to save the
> document you're referring to after you place the cross-reference.
> 
> Every tag that is the target of a cross-reference gets a marker. For
> reasons unknown to me, sometimes these markers become stale and have
> to be deleted and reinserted. This might also cause your references to
> break.
> 
> Do a search for All Markers or for Markers of Type cross-reference and
> check them out. Make sure the marker matches the tag with which it's
> associated.

Sorry, but this is just bad advice. Cross-reference markers don't become "stale." 

When you point a cross-reference to a paragraph, FM generates a unique string for the marker text. (If you point xrefs to markers you manually inserted -- which is necessary when creating xrefs to destinations in text insets -- it's up to you to ensure that the marker text is unique and identifiable by you.) 

This unique marker text string identifies the destination of the cross-reference so the cross-reference "knows" where to take you. The string looks something like this: 

	38790: Head1: Conference Templates

The second element of the string is the name of the paragraph tag in which the marker is created. But it's just a unique string; using the pgf tag name is just a convention some FM programmers chose to use. If you change that paragraph to a Head2, the marker string isn't updated to "38790: Head2: Conference Templates" -- it remains unchanged. It _has_ to, otherwise the cross-references to that marker won't be able to find it anymore and will be broken.

If you delete and reinsert xref markers (unless you exactly re-create their marker text), or if you "(m)ake sure the marker matches the tag," you'll _definitely_ break the cross-references to it. 

Some of the reasons cross-references break are: 

(1) The destination file isn't open, and FM can't open it in the background to resolve the xref (because, e.g., there are missing fonts).
 
(2) The destination is in hidden conditional text (this is operator error; the xref should have the same condition applied and also be hidden). 

(3) Someone accidentally deleted the marker (most often happens when editing without View > Text Symbols turned on). 

(4) Someone who doesn't understand markers thinks editing the marker text or re-creating them to overcome "staleness" is a good idea. 


Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
------
rgcombs AT gmailDOTcom
303-903-6372
------