Skip to main content
Logo image

Derivatives and Integrals An Annotated Discourse

Section 21 Cross-Referencing

Cross-references are easy, since that is a key reason for having a highly structured document. Here is a useful feature if you elect to use it. Any <xref> will โ€œknowโ€ what it points to, so you can let it provide the โ€œnamingโ€ part of the cross-reference text. You can turn this on globally with the command-line parameter autoname set to 'yes'. If you do that, you will see most of the names in this document doubled, since the names are written into the source already in most places outside of this section.
Moreover, the names themselves will change with the use of the one language dependent file. And another bonus is that with an autoname, you automatically get a non-breaking space between the name and the reference. The autoname switch makes no sense for โ€œprovisionalโ€ cross-references, since there is no information about what they point to.
Here is a reference that has no indication of its type in the source: 2.1. So by default you will just see a number that you can click on. If you use the text="type-global" switch then you should see โ€œTheoremโ€ prepended. Note that if you changed the theorem to a lemma, then that change would be reflected here automatically when autonaming is in effect.
If you set the autonaming behavior globally, or accept the default behavior, there will still be instances where you want to override that choice. Simple: just say text="type-global" or text="global" as part of the xref. Each example below should look the same each time this article is processed, no matter how the global autoname is set.
You might also wish to provide a prefix to a cross-reference and have it incorporated into the text of what you would click on in an electronic version. So if you make an xref with some content, then that content will prefix the cross-reference within the clickable/pokeable text and be attached with a non-breaking space. This xref content totally overrides any prefix that might happen otherwise. So the name of an item (e.g. โ€œcorollaryโ€) could be replaced, and if you make a cross-reference with custom text, that will be the clickable also. An example:
Suppose you want to reference two theorems, so you might want to say something like โ€œTheorems 4.6 and 5.2.โ€ With global autonaming on, you can override the first Theorem by providing the content Theorems on the first xref and text="global" on the second xref. (With global autonaming off, you will also get what you want/expect.) Here is the test, which should look correct no matter what the global switch is: Sectionsย 21 and 22. (But notice that it is up to you to be certain the types of these targets do not change without you changing the content of the first xref. The โ€œauthor-toolsโ€ mode and careful choices of xml:id strings can help avoid this trap.)
If you set the value of @text to title, then the title you assigned to the theorem will be used as the link for a cross-reference. Here is a the final example, which refers to a fundamental theorem by name The Fundamental Theorem of Calculus.
Cross-references to exercises with hard-coded numbers should respect the supplied number. Exerciseย 39.42a should reference problem 42a.
Here we form a list to test pointing at various structures. Each of the following should open a knowl in the HTML version, otherwise it will be a traditional hyperlink (if possible). Note that if a knowl opens, there will always be an โ€œin-contextโ€ link which will take you to the actual location, should you have wished instead to just go there.
Cross-references to structural elements of the document will always take you there directly, since even in the HTML version these parts never get realized as knowls. You will find such links sprinkled through this document, but here is an autonamed link to a subsubsection: Subsubsectionย 4.2.1.
Cross-references can be built into display mathematics, but they can only point to one item (i.e. a comma-delimited list of targets is not supported). Examples below should test the distinction in HTML output between a link that opens a knowl and a link that jumps to a larger chunk of content. Notice that display mathematics is entirely syntax, no matter which output format you create. So if you do not use the autoname facility, you need to wrap non-math text in \text{} and perhaps use a tilde (~) as a non-breaking space (examine the source of this article).
\begin{align*} x^2 + y^2 &= z^2&&\knowl{./knowl/xref/theorem-FTC.html}{\text{Theorem 2.1}}\\ a^2 + b^2 &= c^2&&\text{Section}~\href{section-fundamental-theorem.html}{\text{2}} \end{align*}
Variations on the above include multiple xml:id as the value of a single ref attribute on an xref, in the form of a comma-separated list. In this case, only the numbers are links/knowls and the autonaming attribute is based on the type of the first ref. Wrapping with brackets (citations) or parentheses (equations) is also controlled by the type of the first ref. And the detail attribute for a bibliographic reference is silently ignored. So you can do silly things like have a reference to a theorem within a list of equation numbers and there will be no error message. Handle with care. Spaces after commas in the list will migrate to the output as spaces, so if you donโ€™t have any, you wonโ€™t get any.
If you have a long list of items (such as homework exercises, not in an exercisegroup, or perhaps several chapters), you can get a cross-reference that prints as a range by using xref with two attributes first and last, which may contain a single xml:id each. As with multiple references, first will control autonaming and other features.
The url element may be used to link to a data file, either externally, or internally, if you want to make such an object available to a reader. A good example use case is a spreadsheet that might be part of an exercise, or contain data relevant to some discussion. First let us suppose the data resides somewhere on the Internet, then just use the complete address. Here is one from Microsoft: Sample Excel Spreadsheet
โ€‰1โ€‰
go.microsoft.com/fwlink/?LinkID=521962
.
For a link like the previous one, you might want to provide advice appropriate for your audience about using a context menu to download a file, or how to configure helper/viewer applications.
You can also provide a file yourself, but now it is your obligation to distribute the file with your document (HTML, PDF, etc.) and provide a relative link. This creates some complications, such as making sure an electronic PDF has the associated file in the same place relative to the PDF file. Of course, if you make a print PDF, this becomes impossible. Here is a test example anyway, which is highly likely to be broken in a PDF (including at the PreTeXt project site) unless you build this example on your own computer, locally. Here is a template from the Apache OpenOffice project, provided via the Public Documentation License (PDL): Running Statistics Template
โ€‰2โ€‰
external/data/runningstatisticstemplate.ots
.
The next four paragraphs are each a single <dataurl> element. Explore the source and the output from different conversions. Strictly for testing as of 2022-11-04.
Foo Sample Excel Spreadsheet
โ€‰3โ€‰
go.microsoft.com/fwlink/?LinkID=521962
Bar
Foo Runners Template
โ€‰4โ€‰
http://example.com
Bar
Foo Sample Excel Spreadsheet
โ€‰5โ€‰
go.microsoft.com/fwlink/?LinkID=521962
Bar
Foo Runners Template
โ€‰6โ€‰
https://pretextbook.org/examples/sample-article/oscar/external/data/runningstatisticstemplate.ots
Bar
Testing of output positioning for xrefโ€™s that are inside containers:
Table 21.1. Self-referential Xref In a table
A B C D
Tableย 21.1 B C D
\begin{gather*} {\mathbb Z}_2 \times {\mathbb Z}_2\\ \knowl{./knowl/xref/theorem-FTC.html}{\text{Theorem 2.1}}\\ {\mathbb Z}_2 \times {\mathbb Z}_2 \end{gather*}
Figure 21.2. Xref Inside MathJAX
Now we have two xrefโ€™s to that same target that has a runestone component. Only the first one clicked should try to render the runestone.18.118.1