When you read a novel, you would likely read it cover-to-cover (in one sitting?) and then put it away and never read it again. But for a textbook, you may read cover-to-cover, but you may also frequently skip around, especially at exam time. And once read, it might become a reference work for you, since you know it so well. So years later you might come back looking for something. Cross-references help with all this, so use them liberally. Recognize that an index is really just a specialized way to provide an abundance of cross-references.
It is a two-step process to make a cross-reference.
Put an @xml:id attribute on any element you think you might want to reference later. Be organized about the values of these attributes, and in particular do not number them, as this has no place in your source, and you do not want to maintain the changing numbers over the life of your project. See the advice in Section 3.3 about banned characters. Some elements do not accept this attribute because the element has nothing to identify it (no number, no title). Typically these are containers like <sidebyside> or <statement>. In these cases, put the attribute on the closest enclosing element.
To make a cross reference, you create an <xref /> element with a @ref attribute with the same value as @xml:id attribute on the element you want to reference.
Simple. It is meant to be, so you can use it liberally. But we also know authors want some flexibility.
By default, a cross-reference will visually be text like Theorem 5.2. Depending on your output format, it may have various devices to help you locate that theorem. Maybe a page number, or it is a hyperlink, or the whole theorem is the content of a knowl. You can change the default look of cross-references by setting the @text attribute in docinfo/cross-references. But you can also change the visual appearance of a cross-reference on a case-by-case basis. Add a @text attribute to your <xref /> element to override the document-wide setting. The first column of this table lists the possible attribute values, either document-wide, or on a per-cross-reference basis. The second column has live cross-references to a section of an earlier chapter (that is far away). The third column has live cross-references to another section of this chapter (which is close by). For the fourth column, we have placed content (“Extra”) into the <xref> element as an override of, or addition to, some of the text for the cross-references of the preceding column. Study the table and then read some more explanation following. Note that type-hybrid is the default.
Note that local/global describes the uniqueness of the number (and is affected by your choice of numbering schemes), while type refers to an automatic prefix of the number. The text of the type will vary according to the document's language. If a cross-reference and its target are close to each other, a number like 18.104.22.168 might be overkill, when just a 4 would suffice. A hybrid scheme will use the shorter number whenever it makes sense. Finally, there are two phrase schemes, and it should be clear what text title will produce (though realize there must be a title for the object, possibly a default provided by PreTeXt).
You can also override the text used in a cross-reference link. You do this by providing content to the <xref> element. In other words, do not use an empty tag, but put some (simple) text in the element. Generally, this additional text becomes a prefix of a number, a replacement of a type, or a replacement of a title. It is better to use these overrides, since in electronic formats, the text of the override will be incorporated into the “clickable” portion of the resulting link, making a larger item to hit.
Here are careful examples, where we have provided the content “Division” in the live examples. The list is not exhaustive. Note that overriding a title provides a way to provide any text you would like.
Citations, which are cross-references to <biblio> elements behave the same way, but will always visually look like . References to equations (<men> and <mrow> elements) will visually look like (4.2), where the type is implied by the parentheses. Notice that you cannot cross-reference an <me> (no number) or <md> (just a container).
Further, there are some variant formats.
Replace @ref by @provisional and give it a value with some simple text like subsection on eagle habitat and you will get reminders that once you write this future subsection you need to link it in right here. This is just a convenience for authors during the early stages of a writing project.
Replace @ref by the pair @first and @last. Provide attribute values just as you would for @ref. The code will check that the targets have the exact same tag, and that the order is correct. You will get a link that looks like a range, separated by an en-dash. As a link, only @first will be used for the linking mechanism (i.e., one link is generated, not two). Experiment with @text and content overrides.
The @ref attribute may be a list of @xml:id, separated by commas or by spaces. Then you will get back a list of cross-references. This is meant for a list of citations, producing a look like [5, 9, 22], but it makes no restriction to this case. Use it generally, but it is unlikely to get any more capable. If you want a different list, just use multiple <xref> and format as you desire.
You can create many different combinations with the text options and the variants. Here is one example. You want to say Chapters 1–5. As a range you use the variant with two references. You would get “Chapter” out front automatically with the type-global scheme, but a plural form makes more sense. So you use that text as an override. We could use either type-global or global to get the same text, and possibly type-hybrid depending on teh place where you built the cross-reference. So possibly, one of these schemes might be your document-wide setting and you do not need to specify it now. Here is what we just used:
You can place a cross-reference into a <title> element, but a particular conversion is free to simply render it as text, and not as an active link.
Finally, there is fairly robust error-checking to protect against typographical errors in the attribute values that need to match up for all this to work. Also, there is a check that the @xml:id are unique. But all this checking happens at processing-time, not at the validation step. Any suggestions for improvements that make these checks even more robust are welcome.
With numbering schemes for divisions, theorems, figures, equations, and citations, along with nine different text styles, plus variants, per-cross-reference settings, and text overrides, there are a lot of combinations. Likely you can create some fairly ugly cross-references. Use the flexibility sensibly.