The Problem

A widespread practice in technical documentation is to use numbered headings, and when referring to these headings, to identify them with an electronic cross-reference that includes the heading number and heading text. Electronic cross-references are not hard-coded and so do not require individual maintenance to update them. 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 in these documents is to use different labels to refer to the heading based on its heading level. Heading 1s are typically known as Chapters, while subheadings below that (Headings 2-x) are known as Sections. If a heading is non-numbered, its label may be Topic, or something else, or it may even have no label. Examples of cross-references to four different heading levels:

The label (e.g., Chapter, Section, Topic) is part of the supporting text for the cross-reference, which also includes the introductory clause ("See" or "For details, see..." and so on), delimiters between the elements, and punctuation. These are the elements of a structured cross-reference.

Although it is sometimes done, the label is not usually a part of the heading numbering because it would result in very busy and cumbersome looking headings. In this type of documentation, most people prefer a simple heading number rather than a label and number inherent in each heading.

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

Many writers try to get around this by adopting a generic label for all heading levels. One generic label that is frequently adopted by writers is Section. This avoids the need to update the labels, but there are still those purists among us who find it an awkward though expedient solution. A chapter is still a chapter after all, no matter how many people call it a section, and there's no use trying to convince these traditionalists otherwise.

The methods described here provide a solution to this problem.