Four years ago, I wrote an article about OpenOffice.org writer called "Fielding Questions, Part 2 - Cross References and User-Defined Fields." I regularly receive mail about it, but these days I have to preface each reply by explaining that the article is obsolete. Repeating the explanation gets old quickly, so I decided that an update is necessary. At first, I thought some footnotes or a short second article would be enough, but I quickly found that a major rewrite of the original was needed. The information below reflects how cross-references are done as of version 3.1.

Over the last few releases, cross-references have improved immensely in OpenOffice.org. In particular, you can now create cross-references from headings, numbered items, and bookmarks, all of which users were requesting four years ago. They are still not where they should be, but they are now a better match for cross-references in other word processors than they were. The main weakness is still a lack of building blocks to create the standard sentences and sentence fragments that surround cross-references, and this weakness can be solved either by using a few user-defined fields, or else with AutoText.

Using Cross-References

Cross-references are used in academic and technical documents to refer to related material. In Writer, cross-references have three main purposes:

• They reduce repetition in a document. Instead of repeating information already given, you can give it once and reference it in other places.
• They help readers quickly find related information in which they might be interested.
• When you write a document, they provide a hyperlink that you can select to change the position of the mouse cursor in the document.

Once cross-references are made, they are listed in the Navigator under References, so that you easily can find them.

Cross-references are placed in fields because they are likely to change frequently. While you are writing, the wording of a cross-reference is likely to change as well as the page on which it appears. You could change them all manually, but because they are in fields, you only have to select Tools > Updates > Fields to have all cross-references immediately updated.

Creating a cross-reference within a document is done in two steps:

• Create the cross-reference source. The cross-reference source is the text to which the cross-reference directs users.
• Create the cross-reference. The cross-reference is the field that points to a source.

Adding a Cross-Reference Source

By convention, a cross-reference usually refers to a heading or title. You can use any text as a cross-reference source. The advantage of using a heading or title is that when a reader follows the cross-reference, the source can be seen quickly because it is formatted differently from the body text.

If your document does not have headings or sub-titles, then you can often save time by referring to existing bookmarks, rather than just setting the cross-references on the fly.

However, if you need a cross-reference that does not refer to a heading, numbered paragraph or bookmark, you can create a source by following these instructions:

• In the document, select the text for the cross-reference source. To help readers find it as quickly as possible, in most cases the text should be a non-text body style that is formatted to stand out. Headings are used most often reference sources, but captions are almost as common.
• Select from the menu either Insert > Cross reference or Insert > Field > Other > References. In both cases, the Fields window opens. The References tab is active.
• In the left pane of the cross-reference window, select Set Reference. The selected text appears in the Value field on the tab. Because you cannot edit the selected text from the tab, it is grayed out.
• Enter a name for the cross-reference source. This is the name listed in the Selection pane of the References tab. Even though the Value field is available when you select the name, the most useful name for a reference source usually is its actual text or perhaps an abbreviation of it. With this choice, you immediately can identify the reference source later. The main reason for not making the Name and Value field identical is if the text of the reference source is not unique in the document.
• Select the Insert button. The content of the Name field now is listed alphabetically in the Selection pane. It now is ready to be used in a cross-reference. In the document, the selected text is no longer highlighted. Instead, it has the gray background of a field.

Adding a Cross-Reference

A cross-reference points readers to another part of the document whose contents is related to the present one. The cross-reference usually consists of fields for the cross-reference source and some lead-in text, such as "For more information, see".

To add a cross-reference:

• If necessary, add the cross-reference source, as already described.
• Type the lead-in text in the position where you want to add the cross-reference. Common lead-ins are "For more information, see ", or simply "See". You can also automate this part of the task (see below).
• Select either Insert > Cross Reference or Insert > Field > Other > References. In both cases, the Fields screen opens. The References tab is active.
• Select a source. Headings, numbered paragraphs, or bookmarks are listed separately. If you created your own source, select Insert Reference. In all four cases, the available sources of that type are listed in the Selection pane.
• From the Format pane, select the information about the source to include in the cross-reference. You can only choose one at a time. Choices are:
• Page: The page number for the cross-reference source is added at the mouse cursor.
• Chapter: The chapter number for the cross-reference source is added at the mouse cursor. For this choice to work, you must have selected a numbering style for the first level heading in Tools > Outline Numbering or in the paragraph style. By default, it is the Heading 1 paragraph style.
• Reference: The text of the cross-reference source is added at the mouse cursor.
• Above / Below: The word above or below is added, depending on where the cross-reference is in relation to its source. Usually, this choice is suitable only for informal cross-references and to material on the same page.
• As Page Style: The page number for the cross-reference source is added at the mouse cursor, using the numbering style defined in Page > Layout Settings > Format on the Page Styles screen.
• Select the Insert button to add the cross reference at the mouse cursor's current position in the document.

For most standard cross references, you will want to add the Reference with quotation marks around it, and the page number or possibly the chapter.

Cross-Referencing Another Document

Adding a cross-reference to another document is a process entirely different from adding a cross-reference within a document. Instead of setting the cross-reference first and then adding a field, add a hyperlink using the following procedure:

• Open the target document for the cross-reference. (The target document is the one that will contain the cross-reference)
• Open the Navigator by selecting Edit > Navigator or by pressing the F5 key.
• Select the source document--the document you are referencing--from the drop-down list at the bottom of the Navigator.
• Set the Drag Mode tool to Insert As Hyperlink.
• Drag the heading you are referencing into the target document. A hyperlink to the heading is placed in the target document. The hyperlink is active and can be used to jump to the source document. If you want the hyperlink to resemble regular text, edit the Internet Link and Visited Internet Link character styles.
• If necessary, add:
  • The lead-in text.
  • The page number. This must be added and updated manually.
  • The document name. This can be added manually or by dragging and dropping the title or chapter title of the source document.

Text added as a hyperlink is not updated automatically when the original changes. However, the link is preserved.

Adding Cross-References in Master Documents

Adding cross-references to sub-documents in a master document is similar to adding cross-references in a standalone document. However, the cross-reference exists only in the master document. When you have a sub-document open, you can't read the cross-reference directly. Instead, you have to view the master document. You also cannot read a reference in one sub-document from another sub-document.

The solution is to note the name of the reference source as you create it and then enter it for the cross-reference in the target sub-document. The cross-reference field in the second document is blank when you are viewing only the second document, but it displays the reference within the master document. Or, to follow the procedure step-by-step:

• Open the sub-document in which you want to set the reference. You can open it by itself or from the master document.
• Select the text for the reference.
• Select Insert > Cross-Reference > Set Reference. The Fields screen opens with the References tab open. The selected text is entered in the Value field.
• Enter a name for the reference. The name should be unique not only in the sub-document, but in all sub-documents in the master document. The easiest way to ensure uniqueness is to make the name and the value identical. Make a note of the reference's name.
• Select the Insert button. The selected text now has the gray shading that marks a field.
• Save the sub-document with the reference.
• Open the sub-document in which you want the cross-reference. Again, you can open the sub-document by itself or from the master document.
• Select Insert > Cross References > Insert Reference. The Fields screen opens with the References tab open. Because the reference is in another document, it is not listed in the Selection pane.
• Enter the reference's name. You can leave the value blank.
• In the spot where you want the cross-reference, enter the lead text and then select the format followed by the Insert button to add the cross-reference. Because the sub-document cannot find the reference in the other sub-document, only the gray shading for the field is visible.
• Save the sub-document with the cross-reference.
• Open or return to the master document. Because the master document can locate the reference in the first sub-document, the cross-reference's field(s) now have information from the reference in them.

Remember that the filling of the field in the master document naturally causes changes in paragraph length. To avoid any unexpected changes in the master document, place all cross-references in their own paragraph. Because few cross-references are likely to be more than one line, the chances of changing the formatting are reduced. If you open the sub-document with the cross-reference by itself, the cross-reference field(s) are empty again.

Automating Lead-Ins and Adding Your Own Fields

Writing lead-in text for cross-references gets repetitive. Instead of retyping the same messages every time, you can automate the process either by creating user-defined fields or AutoText

A typical cross-reference, at least in my experience, is something like "For more information, see ___ ", page____".

This can be setup with user-defined fields using two fields. The first field provides the lead-in for a Reference format and the second is for the page number. Taken together with the cross-reference fields, these user-defined fields produce sentences such as "For more information, see 'Setting Up Cross References', page 45."

Writer offers two ways to create a custom field. First, you can use the four vacant fields in File > Properties > User Defined to create text fields. By default, these fields unimaginatively are named Info 1 through 4, but you can click the Info fields button on the User Defined tab to give each a more descriptive name. However, if the field names are changed in a template, documents based on the template don't retain the new name for some reason. At any rate, I personally prefer to use these user-defined fields to add information about the document that I want noted in headers and footers or on title pages.

The second way to define your own user fields is by adding a new type of field in Insert > Fields > Other > Variables > Type > User Field. Each user field has a name that appears in the Selection pane of the Variable tab and a value, or actual entry. More importantly, unlike the Info fields available from File > Properties > User Defined, these fields can be set to have their own number format or even to be invisible. This trait can be used as hidden proof of ownership of the file or as a secret condition that makes the field unreadable unless changed. However, when augmenting cross-references, you can settle for text format.

Another method of automating cross-reference leads is to create an AutoText entry. To do this task, type the standard structure of a lead in, leaving blank spaces where you can insert the cross-reference material. Highlight what you have typed, then select Edit -> AutoText. Give the entry a name -- "cross-reference" would do -- and add a keyboard shortcut. Then select AutoText -> New to add it to the available entries.

When you go to use the AutoText entry, insert it into the text, then go to each of the blank spaces and fill in the cross-reference material.

Both User-Defined Fields and AutoText have other purposes. For example, User-Defined Fields can be places to store meta-data that you want to use in the text, such as a document's verson number, while AutoText can be used simply as a way to avoid long phrases that you are constantly using. But tools like these also provide means for you to overcome some of the limitations of Writers -- and, in both cases, cross-references are a prime example of such usage.

Conclusion

If all this sounds clumsy and roundabout, you're understanding the situation pretty well. Unfortunately, the workarounds are going to be with us for a while. Approximately half of what Writer needs to handle cross-references well has been added since I originally wrote about the subject five years ago, and work still needs to be done to provide a really efficient way to add the lead-ins. It would not take much work to add a few stock phrases to choose from, but, so far, the work has not been done.

The result is, we'll be living with the workarounds for at least a couple of years. The most that can be said for them (as I originally said) is that they're better than nothing. Meanwhile, if you're doing academic or technical work, be prepared -- still -- for some frustrations as you work with cross-references.