The PreTeXt Guide

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.

Since the value of an @xml:id is also used in a variety of ways, such as to construct some file names, some care should be taken in how you author them. We limit the possible characters to letters and numbers (a-z, A-Z, 0-9), with hyphens and underscores (-_) available as word-separators. Our advice is to stick to lowercase letters, though we are not yet aware of any problems with case-insensitivity. So in short, use kebab-case or snake-case for your @xml:id values.

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.9 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].