About cross-references

Cross-references in unstructured documents

FrameMaker provides two types of cross-references—to paragraphs and to specific spots within paragraphs. In both cases, FrameMaker uses markers to keep track of the source of cross-references.

It is easier to create and maintain paragraph cross-references because FrameMaker automatically creates a marker on the paragraph tag in the source files. In the case of spot cross-references, you have to first mark the spot with a marker and then create a cross-reference to the marker.

Note: The Cross-reference feature supports the Unicode text encoding standard.

Cross reference markers

FrameMaker uses a marker (of type Cross-Ref) to keep track of the source of each cross-reference. If you move a marker and then update cross-references, the marker’s new location is used to update the cross-reference.

For paragraph cross-references, the marker text contains a number assigned to the marker, the paragraph tag, and text of the paragraph being cross-referenced. When you insert a paragraph cross-reference, a cross-reference marker is inserted automatically at the beginning of the source paragraph if necessary. (The marker text is not updated, so the tag and text sometimes don’t match the cross-reference.)

For spot cross-references, the marker text is the text you type when creating the marker on the source text. It is important to mark the text in the source first so that it appears in the Cross-Reference panel at the time you create the spot cross-reference.

Cross-references in structured documents

When working with structured documents, FrameMaker keeps cross-references, variables, and footnotes up to date for you. To add a cross-reference in FrameMaker, you normally use an element designed for that purpose. The cross-reference element points to a location, or source, that can be in the same document or a different document. The source is also normally an element, such as a Chapter, Section, Figure, or Table element.

An element-based cross-reference shows text from the source element.

If a cross-reference points to a source in an unstructured flow, the source can be either a whole paragraph or a marked spot in text. It is also possible to point to a paragraph or a spot in a structured flow, but it’s best to point to another element. (Cross-reference elements are often defined to be invalid if they point to anything other than an element.)

ID and ID Reference attributes in structured documents

FrameMaker uses attributes in cross-reference and source elements to maintain the connection between the two elements. The source element has an ID attribute that stores a unique identifier in the document or book. The cross-reference element has an ID Reference attribute that also stores the source’s identifier as a way of keeping track of what the reference points to.

If you insert a cross-reference to a source that has an ID attribute but does not yet have a value for the attribute, FrameMaker automatically provides the value.

An ID that FrameMaker generates is an eight-character string that conforms to the XML or SGML reference concrete syntax.

FrameMaker tries to ensure that your IDs are unique in the following ways:

  • When FrameMaker generates an ID, it is unique within the document. The ID is unique even within the book, because documents in a book have different filenames and part of the generated IDs comes from the filename.

  • If you enter an ID that is not unique, the ID is not accepted. FrameMaker does not test for whether an entered ID is used in a different document in a book but you can validate the book to find duplicate IDs.

  • If you paste a copy of an element with a duplicate ID, the pasted element loses its ID.

It is still possible for a document to have IDs that are not unique. For example, duplicate IDs occur if you show hidden conditional text that contains an element with the same ID as another element. The duplicate IDs are identified as invalid in the Structure View.

Invalid value

An ID Reference attribute is sometimes defined to require a value. If an attribute requires a value but does not have one, the cross-reference probably points to a paragraph or spot within text rather than an element. FrameMaker identifies the attribute as invalid in the Structure View.

Missing a required value

Cross-reference pod overview

The cross-reference pod lists all the cross-references in the current document, selected document, or all open documents. It allows you to add, edit, delete or search for cross-references from a single panel. You can also filter cross-references to view only external or unresolved cross-references. This helps to troubleshoot unresolved cross-references across multiple open documents.

View full size graphic
Cross-reference pod
Select the file.

List all, external, or unresolved cross-references.

Insert a cross-reference in a document.

Edit a selected cross-reference.

Delete a selected cross-reference.

Go to the location of the selected cross-reference in the document.

Refresh pod data.

Search for a cross-reference.