Section 3.4 Cross-References

Cross-references in a PreTeXt document are easy, powerful and flexible. So it is worth familiarizing yourselves with them early, here and then ahead in Section 4.5.

Any element that you place a @xml:id on can become the target of a cross-reference. This could be a division, a remark, a bibliographic entry, or a figure. So for example, suppose your source had <subsection xml:id="subsection-flowers"> and someplace else you wrote <xref ref="subsection-flowers" />. Then at the latter location you would get a reference to the Subsection that discusses flowers. In print this might just be the number for the subsection, but in various electronic output formats, these cross-references can be very powerful interactive ways to explore the content. And the mechanism is always the same, pair up an @xml:id on a target with a @ref on an <xref> cross-reference.

A close relative of the @xml:id attribute is the @label attribute, and the two have distinct duties. An @xml:id is a purely internal name: its job is to be the target of a reference, matched by the @ref of an <xref> (and by similar referencing attributes elsewhere). A @label is the durable identifier string that surfaces in your output: it names the web page (the file) a division becomes, the location of an item within a page, the files of generated images, and database entries for projects hosted at Runestone Academy. When an element has an @xml:id but no @label, the value of the @xml:id is used as the @label automatically—a backwards-compatible arrangement from when the @label attribute was introduced, back when an @xml:id did both jobs. Providing both attributes with the same value is common and perfectly fine; distinct values let you control what readers see and share (a page’s file name, say) independently of the name your cross-references rely on. Two cautions: an element with only a @label cannot be the target of an <xref>, and an element with neither attribute gets a manufactured identifier, built from the nearest labeled ancestor and a position, which can change as you edit—fine for an item nobody links to, wrong for anything a reader would bookmark or share.

Since these values can appear in file names, some care should be taken in how you author them. We limit the possible characters to the 26 Latin letters (7-bit ASCII, no accents; a-z, A-Z) and numbers (0-9), with hyphens and underscores (-_) available as word-separators. In particular, an accented letter, such as a German umlaut, cannot be used, no matter the language of your document—this restricted set is the one that travels reliably across every filesystem and web server. The restriction applies equally to @xml:id and @label, and the @xml:id has one extra rule from XML itself: it may not begin with a digit. Our advice is to stick to lowercase letters, though we are not yet aware of any problems with case-insensitivity. So you can use kebab-case or snake-case for your identifier values if you wish.

For more, see Section 4.5 because cross-references have many features. But first, here are two features you do not want to miss. In the early stages of writing, you can author <xref provisional="subsection-flowers" /> to point to a subsection you are contemplating (but have not written yet) and you will get various polite reminders to get that straightened out eventually (see Section 5.10 for details). Also the default behavior is to automatically provide the generic name of the target, so you will get something like “Subsection 4.3.2” without ever typing the “Subsection” part. If you move the target, the generic name will adjust if necessary, and if you switch to one of the supported languages, the generic name will switch language (see [provisional cross-reference: topic-on-languages].