Features

“Automagic” Labels for Heading Cross-References

September 30, 2010

By John Irwin | Senior Member

Introduction

This article solves a perennial problem with cross-references in technical documents that use numbered headings. This article:

  • Provides methods for creating conditional cross-reference labels (e.g., Chapter, Section, Subsection) that “automagically” adapt to heading-level changes.

  • Assists technical writers who use Microsoft Word, because with these instructions they will no longer have to correct or maintain cross-reference labels, which would normally require special interventions (such as updating each instance manually or using a repair macro).

If you use the conditional cross-reference labels described here, they will be unaffected by any future changes you may make to the heading-level hierarchy. That is, you may move, promote, or demote them in the heading-level hierarchy without needing to change the labels.

The Problem

A widespread practice in technical documentation is to use numbered headings. Numbered headings help readers and customer support personnel locate content, and they are especially useful in long documents.

When referring to these headings, technical writers often use electronic cross-references that include the heading number and text. These electronic cross-references are not “hard coded” and so do not require individual maintenance to update. If you change the heading text, the heading cross-reference will automatically be maintained when you update the fields in the document.

A common convention for creating cross-references in a print paradigm (e.g., books or manuals) is to use different labels to refer to the headings based on the heading level.

Headings (Heading 1s) are typically identified as “Chapters,” while subheadings below that (Headings 2–X) are identified as “Sections.” Also, if a heading is not numbered, the label may be “Subsection,” “Topic,” something else, or even no label. The following examples show cross-references for four different heading levels:

  • See Chapter 1, “Introduction,” on page 1.

  • See Section 1.1, “Features,” on page 1.

  • See Section 1.1.1, “Standard Features,” on page 1.

  • See the topic “Hardware,” on page 1.

The problem is that if you change the heading level or promote or demote it in the heading-level hierarchy, the label in the cross-reference does not update appropriately. Using the example above, if you promote heading “1.1, Features” to the chapter level by tagging it with a Heading 1 style, the updated cross-reference will read: See Section 2, “Features” rather than See Chapter 2, “Features.” These incorrect labels would then require some type of special intervention to update them, such as a manual fix or a repair macro.

Many writers try to get around this by adopting a generic label for all heading levels. One frequently used generic label is “Section.” This expediency avoids the need to update the labels, but it conflicts with traditional usage, as well as being somewhat awkward and misleading. After all, a chapter is still a chapter, no matter how many people call it a section.

I discovered an ingenious solution to this problem in Microsoft Word—a way to create conditional cross-reference labels. Conditional cross-reference labels adapt to the heading-level hierarchy. If the heading levels are changed or moved, the cross-reference labels still give the desired results when the fields are updated.

A similar problem exists with heading number cross-references, although to a lesser extent. If you insert a cross-reference to a numbered heading (e.g., Section 1.1) and then the heading later gets demoted to a non-numbered heading, the cross-reference will then refer to heading number zero (e.g., Section 0). The known solution to this issue, which is simple, is to create a conditional cross-reference for the heading number. My solution for creating cross-reference labels follows the same basic approach, but offers new conditional logic to solve the labeling problem.

Note: In Microsoft Word, you can include a label as part of the heading numbering itself, but this often results in busy and cumbersome headings. Many people prefer to use a plain heading number rather than a label and number inherent in each heading. In contrast, my solution includes the appropriate labels in the cross-reference (not in the headings themselves).

The Solution

The structure of the conditional cross-reference can be adapted to your particular needs, including punctuation, delimiters, and formatting. I adopted the following cross-reference format for the purposes of this article: See Section 1.1, “Features.”

The label (“Section”) and heading number (“1.1”) are part of the conditional cross-reference; that is, they are output based on the result of testing for certain conditions. The heading text (“Features”) is always output; that is, it is an unconditional cross-reference.

Figure 1: Conditional Cross-Reference Labels Adapt to Heading-Level Changes

Figure 1: Conditional Cross-Reference Labels Adapt to Heading-Level Changes.

Step 1

Use outline numbering for headings, with multi-level numbers and period separators (e.g., 1.1.1).

Each heading is numbered sequentially (for example, chapters are numbered 1, 2, 3, etc.). Subheadings are also numbered sequentially, but in addition they are prefixed with the numbers from the prior levels above them. For example, heading number 1.1.1 represents chapter 1, section 1, subsection 1, and the heading paragraph is tagged with a Heading 3 style.

The subheading number shows the heading’s position in the hierarchy and gives it a unique number sequence within the document. This combination of numbers is a multi-level heading number and each number in the sequence is separated by a period.

In technical documents, it is common to number the first three heading levels and to leave the lower levels, if they are used, as non-numbered.

Excellent instructions for implementing outline numbering are provided by Word MVP Shauna Kelly at www.shaunakelly.com/word/numbering/OutlineNumbering.html, as well as others, including Microsystems at www.microsystems.com/pdfs/sevenlaws.pdf.

Step 2

Create a document that uses the outline numbering from Step 1 and add a heading to it. For example, type “Features” and apply a Heading 1 style. It doesn’t matter what heading level you use at this point (Heading 1, 2, 3, etc.).

Then, in a new paragraph, insert a cross-reference to the heading. It doesn’t matter whether the cross-reference is to the heading text, heading number, page number, etc.

When you insert the cross-reference to the heading, Microsoft Word creates an internal, hidden bookmark around the heading. The bookmark name takes the form _Ref123456789. To check this, you can reveal Hidden Bookmarks on the Insert Bookmarks dialog (which was introduced in Word 97), and you can select and GoTo the bookmark.

Microsoft Word also inserts a cross-reference field, containing a REF field code plus the internal bookmark name that points to the heading; for example: { REF _Ref123456789 }. To see the field code, reveal it by selecting the field and pressing Shift-F9.

Edit the field code so that it matches the following format, but keep your bookmark name in place of the one shown here:

{ REF _Ref123456789 n }

The “n” is a field switch that specifies a cross-reference to the heading number.

When you are done, select the field and copy it to the clipboard by pressing Ctrl-C.

Step 3

Create a prototype of the conditional cross-reference fields. (Or insert a copy of one that I built. You can download and modify my prototypes to fit your needs. At the end of this article, I give the website where you can download them.) For now, we will use a simpler one that you can enter manually.

A text representation of the field coding follows. The curly braces represent field delimiters, which you must insert by pressing Ctrl-F9. The {REF} represents where you should insert the cross-reference field that you created in Step 2. Otherwise, make sure to enter the text as shown, including all spaces and quotation marks. (Quotation marks are shown as straight quotes for legibility but can be entered as either straight or curly quotes.)

You can start by pressing Ctrl-F9 and then typing the text that appears inside the field braces. When you get to the next starting field brace, press Ctrl-F9 (or if it is a {REF} field, press Ctrl-V to insert the field from the clipboard). After you have entered the field coding, you must edit the last {REF} field as described in the next paragraph.

The field coding contains nested fields, and it uses five instances of the {REF} field. The first four use a heading number switch (“n”) and are identical to the one that you created in Step 2, so you can paste it from the clipboard when you get to these fields. The last one uses a hyperlink switch (“h”), and after you paste the {REF} field from the clipboard, you must change the “n” to “h”. (This is necessary to include the heading text in the cross-reference.)

See { IF {REF} = 0 “the topic ” “{ IF { = INT ( {REF} ) } < {REF} “Section” “Chapter” } {REF}, “ }”{REF}.”

Tip: You can press Ctrl-F9 to insert the field delimiters and then type text inside them, or you can type text, select it, and press Ctrl-F9 to enclose it in the field braces.

Use Shift-F9 to toggle the selected field between the field code and the result or Alt-F9 to toggle all field codes.

Select the cross-reference field and press F9 to update it. If the field shows an error, correct any errors in the field coding. If it shows field coding instead of the result, press Alt-F9 to toggle back to the field results.

When you are done, you have a live cross-reference that will adapt to heading-level changes. Test it by changing the heading level of your “Features” heading and then updating the cross-reference field with F9. Test each heading level to be sure they all work.

Step 4

If you plan on using conditional cross-references in your documents, you will need a way to insert them efficiently. An easy way is to store a prototype cross-reference in template autotext and use a macro to insert and modify it. If you take this approach, you will need to do the following with the macro:

  • Insert a temporary “live” cross-reference to a document heading in any form (heading text, heading number, page number, etc.).

  • Insert the cross-reference prototype from the autotext.

  • Replace all instances of the bookmark name in the prototype with the one from the live cross-reference. (Tip: You can copy the bookmark name of the live cross-reference to the clipboard, and then in the Find and Replace dialog, use ^c as the replacement value to specify the clipboard contents.)

  • Press F9 to update the conditional cross-reference fields.

  • Delete the temporary cross-reference you inserted in the first step.

Explanation

The solution pivots on the use of the conditional text field (IF field). This field is often used with the mail merge feature in Microsoft Word. The IF field evaluates a logical condition (e.g., compares two values or expressions), and, depending upon the result, outputs one of two values. If the condition is true, it outputs one value, and if it is false, it outputs the other value.

The basic syntax for the IF field is {IF Condition “True Text” “FalseText”}. This is an IF/THEN/ELSE construction, with implied THEN and ELSE keywords. Alternatively, the output of the IF condition (“TrueText” or “FalseText”) can be numeric (TrueValue or FalseValue).

The field coding also uses the = (Formula) field and the INT function to differentiate between chapter and section heading numbers. The INT function operates on a decimal number in the form x.y and returns the integer portion, i.e., the numbers to the left of the decimal place (x).

The conditional cross-reference tests the heading number to see if it falls into one of three categories: chapter number (1, 2, 3, etc.), section number (1.1 or 1.1.1, etc.), or non-numbered (0). It then assigns one of three labels (“Chapter,” “Section,” or “the topic ”) depending upon the heading number.

  • If the heading number is a positive whole number (x), it assigns the “Chapter” label.

  • If the heading number is a decimal number (x.x) or a multi-level number (x.x.x or more), it assigns the “Section” label.

  • If there is no heading number (0), it assigns “the topic” as the label.

The field logic is illustrated in the following pseudocode (where “HdgNum” represents the heading number field, which you created in Step 1):

This explains the basic functioning of the field. The details of the logic are a bit tricky when dealing with multi-level numbers. It is beyond the scope of this article to explain what happens when using the mathematical INT function on a multi-level number. If you are interested in these details, see below for more information.

More Information

If you want to include a quotation mark inside the IF field results, precede it with the backslash escape character (”).

To add a cross-reference to the page on which the heading appears, add another {REF} field at the end of your prototype and use the “p” field switch. This results in a page reference “on page #” (or “above” or “below” if on the same page).

Samples and More

You can obtain more information and samples from http://word.mvps.org/FAQs/Formatting/conditional_cross_references.htm. The samples contain a variety of pre-built fields that will save you time and trouble. You will also find customizations and extensions to the solution (including four- and five-label extensions), as well as helpful notes and tips on structured cross-references, formatted-style cross-references, auto-text labels, formatting precedence, controlling the presence of labels, automating, limitations, and detailed explanations of the logic.

JOHN IRWIN (JohnIrwin.Eventide@gmail.com) is a senior technical writer for a New Jersey audio and communications firm and a senior member of the STC New York Metro Chapter.

Tags