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.-
Always named: Corollary 4.1
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:-
A grand result: Major Corollary 4.1
-
A grand result: a nice corollary
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.
-
A link to a
propositionelement, while this document has globally renamedpropositions as “Conundrum”s, so this link should use the new name: Conundrum 32.1 -
Display Mathematics: multi-row, first with no name: (4.2). Then with an autoname: (4.2). And two, with a plural form: Equations (4.1) and (4.2).
-
You can cross-reference The Fundamental Theorem of Calculus via custom text of your choice.
-
Display mathematics: an equation with “local” tag, which should not be used so very far away: (✶✶).
-
You can author a cross-reference to a displayed equation with no number, but it will not be very satisfying. You should get a warning if you try.
-
Exercises (divisional), a range, with plural form provided to override autonaming: Exercises 11.2.1–11.2.3.
-
A group of two exercises, with introduction, conclusion: Exercise Group 11.2.2–3
-
Solution: An autonamed portion of an exercise: Solution 39.42a.1
-
A subsidary part of an exercise: 12.10.1.b.i
-
Three cross-references to individual exercises, but due to their location, they should have different “type names” in the cross-reference: in an
<exercises>division, Exercise 36.2; in the narrative, Checkpoint 4.6; and in a<worksheet>, Worksheet Exercise 35.1.2. -
An item buried in nested ordered lists: Item 2.b.ii.C
-
List item inside a named list, second color in rainbow list: Item 12.3:2
-
An item in ordered list, but contained in an unordered list, hence without a number, so a cross-reference by number would be ambiguous. So we use a cross-reference which relies on custom text: No Number List Item
-
Several examples of hybrid cross-references to list items within a named list can be found in, and adjacent to, List 12.4.
-
An assemblage, which never has a number. A cross-reference now requires content in the
xrefelement, withtext='custom': text to xref an assemblage -
A cross-reference to a list item in a description list, which has a title, but never a number: Central Processing Unit (CPU). Note that you need to include the attribute
text="title"even if that is obvious from the situation. This requirement may be relaxed in a future refactoring of the cross-reference system. -
A very similar cross-reference to the previous one, but testing how final punctuation of titles is handled: Bus!.
-
A cross-reference to a “paragraphs” subdivision, which never has a number (so comments above about description list items and titles applies here too): Structure
-
A cross-reference to a description list item with a title containing math: Math \(x^2\)
-
A cross-reference to an aside, by title necessarily, and with some formatting in the title: An Aside with a Formatted Title
-
A cross-reference to an
objectivesblock, with an autoname. This demonstrates the number of the Objectives here, which is not shown in the original version since it is implicit: Objectives 4 -
A cross-reference to an individual objective. This is authored as a list item, but displayed as an objective (singular) via an autoname: Objective 4.1
-
A cross-reference to the top-level element (e.g.
book) will point to a summary page similar to a Table of Contents in HTML. For LaTeX output it will behave similarly, unless there is no Table of Contents, then it will go to the main title page: ToC or Title -
“Cross-references inside quotations previously lost track of their target, so this tests correcting that, not so much the cross-reference itself: Theorem 2.1”
-
A
type-globalcross-reference to a second-leveltaskwithin a project: Task 4.4.c.iii, the encompassingproject: 4.4, and alocalreference c.iii. -
This opens a knowl for an
example. It has a solution, which is orginally presented as a hidden knowl. But since this version is a duplicate, the knowl for the solution is a file version, not an embedded version, and hence free from duplicating any unique identifaction like an HTML id. So we test its styling and function here: Example 4.7 -
A cross-reference to a poem, where we need to use a title for the link text, since a
poemis not numbered: The Charge of the Light Brigade -
A cross-reference to a
<references>division in a subsection, which should not be numbered where born, but which has the number of its parent division in a cross-reference: References 11.4. And a cross-reference to a<references>division, which is the “main” bibliography in the back matter, and so is not numbered where born, nor in a cross-reference (which we must accomplish via it’s title): References. -
A cross-reference to a
<solutions>division in a subsection, which should not be numbered where born, but which has the number of its parent division in a cross-reference: Solutions 4.2.6. And a cross-reference to a<solutions>division, which should appear as an appendix both where born and as a cross-reference: Appendix B. -
A cross-reference to an
<exercises>division in a subsection, which is the only such division in that subsection and therefore should not be numbered where born, but which has the number of its parent division in a cross-reference: Exercises 4.2.3. In contrast we cross-reference an<exercises>division which is one of two inside a section, and therefore is numbered, when born and when cross-referenced, in continuity with the preceding subsections: Exercises 11.3. Also an<exercise>within an<exercises>which should have a cross-reference employing the number of the containing (unstructured)<section>: Exercise 36.2 which is in Exercises 36 which is in the (unstructured) Section 36. -
You can request the text to be a type, then a number, then a title: Theorem 2.1 The Fundamental Theorem of Calculus
-
Asking for the text to be a type, then a number, then a title, when there is no title, is not a problem: Corollary 1
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 LaTeX 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.-
A range of exercises, autonamed (this range appears “out-of-order” since the two
exerciseare numbered under two different schemes): Checkpoint 4.6–4.2.3.1 -
A range of equations: (4.2)–(4.3)
-
A system of equations, given as range from first to last: (7.1)–(7.2)
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 Spreadsheet1
go.microsoft.com/fwlink/?LinkID=521962For 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
data/spreadsheet/runningstatisticstemplate.otsThe 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 Runners Template Bar
6
https://pretextbook.org/examples/sample-article/oscar/external/data/spreadsheet/runningstatisticstemplate.otsTesting of output positioning for xref’s that are inside containers:
| 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*}
