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.
Subsection4.5.1Creating a Cross-Reference
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.4 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 such as <sidebyside>, <statement>, or <ol>. 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.
Best Practice4.5.1.Use @xml:id Frequently.
Use the @xml:id attribute liberally, on any object you might want to reference later, and on every division. It is easier to do as you author and will be very valuable later. (Trust us on this one.) Develop a system so you can recall them predictably, but keep them readable. Don’t use numbers, they will change. Then make frequent cross-references. They are relatively easy for you and will be incredibly useful for each and every one of your many readers, over and over and over again.
Subsection4.5.2Text of a Cross-Reference
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-global 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 5.8.2.4 might be overkill, when just a 4 would suffice. A hybrid scheme will use the shorter number whenever it makes sense. 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). Finally, if desired, the text can be customized with any text you like.
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 or a replacement of a type. 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. Recognize that this extra content will not benefit from automatic internationalization.
Here are careful examples of providing content inside the <xref> element, where we have provided the content “Division” in the live examples. The list is not exhaustive.
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 (see Section 5.9 for details).
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–6. 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 the 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.
Subsection4.5.4Citations
Citations are just specialized cross-references to <biblio> elements, and so behave the same way as other cross-references. However they will always visually look like [23], and there is no notion of “type name.”
Subsection4.5.5Equations
Similar to citations, references to equations (<men> and <mrow> elements) will visually look like (4.2), where the type name is implied by the parentheses. Notice that you cannot cross-reference an <me> element (it has no number) or an <md> element (it is just a container, filled with <mrow> that you can target if you give them numbers). Consult Subsection 4.9.3 for details about controlling the numbering of equations within an <md> or <mdn> element.
Subsection4.5.6Lists
Roughly, you can target a list item for a cross-reference, but not the list itself, since it is a container. See Subsection 4.11.4 for precise details about using list content as the target of a cross-reference. Note also, that an entire named list may be the target of a cross-reference, see Section 4.20. Here we concentrate on the text of the cross-reference itself.
First, note that if you cross-reference a list item of an anonymous list, there is a very real possibility that the number will be ambiguous, and there is no option for @text will save you, and never can be. See the middle column of Table 4.5.5 for the demonstration. We assiduously try to make it impossible to ever create ambiguous text for cross-references, especially in consideration of print output. Use the feature carefully.
Best Practice4.5.4.Take Care Referencing Anonymous Lists.
Cross-references to list items of anonymous lists can easily be ambiguous and then useless for readers of print. Keep such a cross-reference close to its target, ideally within the same list, and/or perhaps using additional, unambiguous clues about location (which you expect will survive later editing):
The local option, discussed generally above, behaves differently for a cross-reference to a list item of an ordered list that is contained in a named list. As seen in the table just below, the local portion of the number is the part that comes from the list item, without the part that comes from the location of the <list> block.
Table4.5.5.Cross-references to list items, visual text styles
The hybrid options employ a different definition of when the distance between a cross-reference and its target is close enough that the number can be shortened, without becoming ambiguous. When an <xref> and its target are part of the same <list>, then the common part of the number derived from the <list> is not needed. To illustrate we need to make a small <list> with cross-references contained within.
Best Practice4.5.7.Be Rational About Numbering Variations.
With distinct numbering schemes for divisions, theorems, figures, equations, and citations, along with ten different text styles for a cross-reference, plus variants, per-cross-reference settings, and text overrides, there is a huge supply of combinations. Likely you can create some really ugly cross-references. Use the flexibility sensibly.
