Preserving cross-references to/from XML

Joseph,

   A cross-reference is a link from one spot in a document to a spot in the same or a different document. FrameMaker calls the target of this link its "source" because the target is the source of information (such as a title, autonumber, or page number) displayed by the cross-reference. FrameMaker supports two types of cross-references, which I describe as element based and marker based. The source of an element-based cross-reference is an element that has a unique ID attribute. Internally, FM uses the value of the ID attribute to find the source elements.   I The source of a paragraph-based cross-reference is a cross-reference marker.

   When you create a cross-reference in structured FM, you select the Source Type from a pop-up menu that gives four choices:

     Paragraphs

     Cross-Reference Markers

     Elements Listed in Order

     Elements Sorted by ID

   When you choose either Paragraphs or Cross-Reference Markers, make appropriate selections, and click Insert, FM creates a marker-based cross-reference. If you chose Paragraphs and select a paragraph that already contains a cross-reference marker, FM uses the existing marker as the source. If the paragraph does not contain such a marker, FM creates one.

   The difference between the two Elements options is the order in which elements that have unique ID attributes are listed, and whether the value of their unique ID attributes appear in the dialog box. Internally, FM stores the unique ID of the source element in its data structure for the cross-reference element and uses this ID to find the source element when it updates cross-references. If the cross-reference element's definition include an ID Reference attribute, FM also stores this value in the cross-reffereence's first ID Reference attribute. You can insert a cross-reference whose source is an element whose ID attribute is not yet set, and FrameMaker will assign a value to that attribute.

  You can create both element-based and marker-based cross-references in both structured and unstructured documents. However, you have to be using the Structured FrameMaker product interface to see the element-based Source Types. Of course, to create an element-based cross-reference, the source must be within a structured document or flow.

  You can ensure that only element-based markers are used in valid structured document by making their ID Reference attributes required. FM will still let you create a marker-based cross-reference but it won't be valid because the ID Reference attribute won't be set.

   When it reads or writes XML, FM exports element-based cross-references using the XML's IDREF attribute to the ID value of the FM source element's unique ID. As Jang's old message relates, a r/w rule is needed to name this IDREF attribute if the element tag differs from FM's default. For many releases, FM simply converted marker-based cross-references to text because there is no way to identify the source with an ID reference attribute. Later releases export marker-based cross-references as elements but use a srcfile attribute (whose value contains the filename containing the cited marker as well as the marker text) instead of an IDREF attribute for such cross-references.

  If you are seeing srcfile attributes in your XML where you want IDREFs, the FM cross-references will need to be changed to define the link with attributes. If your cross-references are element-based but generated XML does not include the value of IDREF attributes, add a r/w rule of the form Jang gave above.

   --Lynne