Skip to main content

The PreTeXt Guide

Subsection 4.5.1 Creating a Cross-Reference

It is a two-step process to make a cross-reference.
  1. 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.
  2. 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 Practice 4.5.1.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.