The PreTeXt Guide

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.