Skip to main content

The PreTeXt Guide

Robert A. Beezer, David Farmer, Alex Jordan, Mitchel T. Keller

Subsection 4.5.3 Variations

There are some variant uses for the <xref> tag.
  • 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:
<xref first="start-here" last="schema" text="global">Chapters</xref>
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.
PrevTopNext