TechNote (Archived)

Understanding and Resolving Issues with Cross-References in FrameMaker

What's Covered

Two Types of Cross-References

Resolving Cross-Reference Problems

Chapter 6 of the Adobe FrameMaker 5.5 User Guide discusses cross-references in FrameMaker and how to resolve problems with them. This document builds on that discussion. You may find this document most helpful if you first read Chapter 6.

Two Types of Cross-References

FrameMaker provides two types of cross-references: paragraph and spot. A mistaken assumption is that the name "spot" indicates an ability to link to a specific spot in a paragraph. In actuality, spot cross-references and paragraph cross-references use the same building blocks for formatting and therefore may appear identical in your document. The primary difference between the two cross-references is how you use them, not how you format them.

Many cross-reference formats use the <$paratext> building block, which displays the entire paragraph that contains the marker. (No building block displays only the word that contains the marker.) Therefore, if you use the <$paratext> building block when setting up either type of cross-reference, the entire paragraph appears in your document. The following two examples show how spot cross-references are intended to be used:

- To reference the second page of a two-page paragraph. When you insert a cross-reference, FrameMaker, by default, places a Cross-Ref marker at the beginning of the source paragraph so the first page is referenced in the cross-reference. You can, however, insert a Cross-Ref marker on the second page of the paragraph. Then, use a Source cross-reference marker that you will select later when you insert the cross-reference.

- To mark text with reminders to yourself to cross reference it later. You can access these markers by choosing Special > Cross-Reference or by generating a List of Markers of type Cross-Ref with the Automatic Hypertext Links option selected.

Resolving Cross-Reference Problems

You can usually determine if you have cross-reference problems upon opening a file or choosing File > Generate/Update for a book file: FrameMaker returns the message, "This document contains unresolved cross-references." Cross-reference problems can occur for a variety of reasons, including the following:

- Editing the source of a cross-reference

- Changing the pagination of the source document.

- Deleting a marker from its source document

- Deleting a source document

- Moving the source to a different file

- Another user's opening and locking of a source document

Cross-references can be set up on the master pages as well as the body pages. When searching for unresolved cross-references, always check the master pages in addition to the body pages.

Messages Althougha Document Has no Unresolved Cross-References

When you open a FrameMaker document that contains external cross-references, FrameMaker opens each referenced document without displaying it, updates the cross-references, and closes the document. However, if a referenced document contains text formatted with fonts that are unavailable, FrameMaker cannot open it and, therefore, cannot verify or update the cross-references. As a result, it displays two messages: "This document contains unresolved cross-references" and " . . . unavailable fonts" -- although your document may have no unresolved cross-references. To prevent these messages, you can do either of the following:

-- Edit FrameMaker's preferences so that FrameMaker permanently replaces missing fonts with available fonts:

Note: If you complete the following steps, unavailable fonts will be permanently replaced with available fonts whenever you save a document. If you want to retain a specific font in your document and that font is not available on the system, you should not complete these steps.

1. Open each FrameMaker document that is cross-referenced, and click OK to the messages.

2. In each document, choose File > Preferences and deselect Remember Missing Font Names.

3. Save each document.

-- Determine which fonts are missing and install them:

1. Close the document.

2. Open all files referenced by the original document.

3. Click OK to the unavailable fonts message.

4. Check the FrameMaker console (Windows), the shell from which you started FrameMaker (UNIX), or the Missing Fonts window (Mac) for a list of the missing fonts.

5. Do one or both of the following:

- To restore printer resident fonts, switch the default printer to the one used when the document was created.

- Install the missing fonts.

6. Open the document.

7.Search for unresolved cross-references on both the body and master pages and update them.

Cross-Reference Sporadically Drops Tags

A cross-reference can display a paragraph tag if the tag is in the same connected text flow as is the cross-reference's source. If the tag and source are in separate text flows or unconnected text frames, FrameMaker will not identify the tag. FrameMaker looks for the tag only within the flow that contains the cross-reference's source.

For example, if you have formatted your cross-references as<$paranumonly[Chapter]>-<$pagenum>, Chapter will not appear when it is in another text flow or unconnected text frame.

To make sure that the source is in the same flow as the tag:

1. Put the insertion point in the source paragraph.

2. Choose Edit > Select All in Flow.

3. Zoom down to view multiple pages, and then verify from the highlighted text whether the text is in the same flow. If it is not, reformat the document, placing text in the same flow.