OpenOffice.org: Cross-References Revisited

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.

xref

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.

setting-reference

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.

user-defined

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.

autotext

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.

AttachmentSize
autotext.png34.78 KB
setting-reference.png29.63 KB
user-defined.png36.57 KB
xref.png37.72 KB
______________________

-- Bruce Byfield (nanday)

Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Cross-References in Master Documents is broken

celem's picture

While your article is good, it is unfortunate that Cross-References in Master Documents is very broken! See issue 100448 at /www.openoffice.org/issues, and bug 289614 at bugs.launchpad.net. Please go vote for them to help raise the priority, which currently is not high.

I just finished a 240 page book written in fourteen chapters, each in its own OO file. The Cross references are fine in the individual files but when gathered into a Master Document they will randomly scramble. When publish time came and the bug still wasn't fixed, I had to export the master document to a single file and then manually edit the incorrect cross references.

I consider this bug to be extremely high. After all, what good id the elegant Master Document capability if its output cannot be trusted to be correct.

For more detail see the actual Bug Reports:

http://tinyurl.com/dy3ckl

http://tinyurl.com/ccs8ph

OpenOffice.org: Cross-References Revisited

celem's picture

Good article! I found a few new to me, useful tips - thanks. By the way, are you aware that, in a large work with master documents, if the anchors in figures are different that the numbering can randomly be incorrect in the master document. I have found the only safe way around this bug is to always make everything anchor "as character". See the bug report issue no. 100448 at the link below.

http://www.openoffice.org/issues/show_bug.cgi?id=100448

Cross-references example in LaTeX

Jakub Narębski's picture

It is a pity that OpenOffice.org didn't took example from (La)TeX treating of cross-references, and various packages enhancing cross-references in LaTeX like varioref, fancyref, cleverref, refstyle, etc.

White Paper
Linux Management with Red Hat Satellite: Measuring Business Impact and ROI

Linux has become a key foundation for supporting today's rapidly growing IT environments. Linux is being used to deploy business applications and databases, trading on its reputation as a low-cost operating environment. For many IT organizations, Linux is a mainstay for deploying Web servers and has evolved from handling basic file, print, and utility workloads to running mission-critical applications and databases, physically, virtually, and in the cloud. As Linux grows in importance in terms of value to the business, managing Linux environments to high standards of service quality — availability, security, and performance — becomes an essential requirement for business success.

Learn More

Sponsored by Red Hat

White Paper
Private PaaS for the Agile Enterprise

If you already use virtualized infrastructure, you are well on your way to leveraging the power of the cloud. Virtualization offers the promise of limitless resources, but how do you manage that scalability when your DevOps team doesn’t scale? In today’s hypercompetitive markets, fast results can make a difference between leading the pack vs. obsolescence. Organizations need more benefits from cloud computing than just raw resources. They need agility, flexibility, convenience, ROI, and control.

Stackato private Platform-as-a-Service technology from ActiveState extends your private cloud infrastructure by creating a private PaaS to provide on-demand availability, flexibility, control, and ultimately, faster time-to-market for your enterprise.

Learn More

Sponsored by ActiveState