FrameMaker Tutorial:
Cross-References

Developed for Advanced Documentation Students
by
David A. McMurrey and Thomas A. Moore

See the FrameMaker resource page for additional study materials. Got a question about this tutorial? Post it in the FrameMaker FAQ

The following informal FrameMaker tutorial shows you how to insert cross-references, customize existing cross-reference formats, and create your own cross-reference format from scratch. If you see any errors or think we should have included other tasks, let us know! Subsequent lessons will focus on templates, tables, tags, graphics, cross-references, book building, variable text, and the like. These tutorials only get you started; if you have more in-depth needs, see the Adobe FrameMaker User Guide or Adobe FrameMaker Classroom in a Book. (This tutorial is provided for advanced documentation students on a free, as-is basis, without guarantee of accuracy.)

This tutorial is based on FrameMaker version 5.5 for Windows. You may see some minor differences if you are using a different version.

Note: For the sake of brevity, we will use an abbreviated style for menu commands throughout this lesson. For example, "Choose File > New" means "Choose New from the File menu".

Opening and Renaming a Sample File

First, open one of the sample files included with FrameMaker:
  1. Choose File > New.

  2. In the New dialog box, click Explore Standard Templates. On the left will be a list of the different types of documents you can choose from.

  3. Click More to view additional choices.

  4. Click Chapter (under the Book heading) and then Show Sample. This creates a FrameMaker document with sample text already filled in. This will give you something to work with.

    Note: If you get an error message about the document using unavailable fonts, click OK.

  5. Choose File > Save As…, name the file Chap1, and click Save.
Tip: There are more sample documents under Help > Samples & Clip Art. Make a point to go back and explore them when you are finished with this lesson.

Inserting a Cross-Reference

Imagine that you want to insert a cross-reference that looks like this:

For more information, see Table 1 on page 3.

  1. Move to the end of the first paragraph and type For more information, see . Be sure to type a space after the word see.

  2. Choose Special > Cross-Reference. The Cross-Reference dialog box appears:

    Cross-Reference dialog box

  3. In the Paragraph Tags scroll list, choose TableTitle.

  4. In the Paragraphs list, choose Table 1: Ridebis et licet rideas.

  5. In the Format list box, choose Table Number & Page and click Insert.

  6. Type a period.

FrameMaker inserts a cross-reference to the table on page 3 using a predefined cross-reference format. Did you see all that intimidating code in the cross-reference format? Don't worry, we will explore what it means in the next couple of sections.

Understanding the Cross-Reference Format

Each cross-reference format is a combination of text and "Building Blocks". The Building Blocks are code that tells FrameMaker exactly what to insert for the cross-reference. For example, the format Table <$paranumonly> on page <$pagenum> tells FrameMaker to insert the word "Table", then the autonumber for that paragraph format, then the words "on page" and then the page number. Explore the other Building Blocks to see what kind of results you get.

Customizing a Cross-Reference Format

Imagine that you want to insert a cross-reference including the page number of the table, but not the title of the table itself. You can modify the cross reference format to do just that:

  1. In your document, double-click the cross-reference you just created. Notice that the entire cross-reference is highlighted, no matter how many words it includes. The Cross-Reference dialog box also opens.

  2. At the lower right of the Cross-Reference dialog box, click Edit Format. The Edit Cross-Reference Format dialog box appears:

    Edit Cross-Reference Format dialog box

  3. In the Definition text box, delete everything except page <$pagenum>.

  4. In the Name text box, type Page Number and click Add.

  5. Click Done, then Replace.

With this procedure, you added a new cross-reference format called Page Number. You also replaced the existing cross-reference in your document with the new format.

Creating a Cross-Reference Format

Suppose none of the existing cross-reference formats in your document is exactly what you need. If this is the case, you can create your own:
  1. Choose Special > Cross-Reference.

  2. Click Edit Format. Once again, the Edit Cross-Reference Format dialog box appears:

    Edit Cross-Reference Format dialog box

  3. Delete everything in the Definition text box.

  4. From the Building Blocks list, choose <Emphasis>.

  5. From the Building Blocks list, now choose <$paratext>.

  6. In the Name text box, type Text.

  7. Click Add, then Done, then Done again.

You have now created a new cross-reference format called Text. The <Emphasis> bulding block is a character format that will make the cross-reference appear italicized. Go on to the next section to try it out.

Insert a Cross-Reference to Another File

You can also insert a cross-reference to any other file that is currently open:
  1. Open the sample file called Front Matter from the Standard Templates. Refer to Opening and Renaming a Sample File if you need help.

  2. Save the file with the name Preface.

  3. Return to Chap1.fm.

  4. Place the insertion point after the second paragraph on page 1, press Enter, and type This book, . Be sure to leave a space after the comma.

  5. Choose Special > Cross-Reference.

  6. From the document list box, select Preface.fm.

  7. For Paragraph Tag, choose TitleBook, and for Paragraph, choose Great Events of the Twentieth Century.

  8. For Format, choose Text, and click Insert.

The words "Great Events of the Twentieth Century" should appear in italics. You will get more practice working with multiple files in the Book-Building Tutorial.

Updating Cross-References

The beauty of automated cross-references is that they change when the text changes, ensuring that they are always accurate. Updating your cross-references after changes is easy:
  1. Go to the first page of Preface.fm.

  2. Change the title to "Great Events of the 1980s".

  3. Go back to Chap1.fm.

  4. Choose Edit > Update References.

  5. Select All Cross-References and click Update.

    Your cross reference in Chap1.fm should change to reflect the new title.

  6. Save your files, if desired.

In this tutorial, you learned how to insert a cross-reference, customize an existing cross-reference format, and create a cross-reference format from scratch. Experiment with the other cross-reference building blocks. The concept of building blocks carries over to many other aspects of FrameMaker, including variables, autonumbering, tables of contents, and indexes.

If you've completed this tutorial and are taking an online course in print documentation, go to the FrameMaker workshop area of the Print Documentation Chatroom and let the rest of the class know how you did on this tutorial.


Information and programs provided by hcexres@prismnet.com.