
## Section17Cross-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. Try it and see: use --stringparam autoname 'yes' as an argument to xsltproc.

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 a title as the clickable, then that text can be replaced 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 17 and 18. (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.)

One final twist. If you say text="title", then the title you assigned to the theorem will prefix the number. Here is a the final example, which should always refer 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 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.

• Footnotes: Fermat allusion at 2.1.

• Citations: Judson's AATA with annotation at [1]

• Citations: Judson's AATA with autoname that should have zero effect [1]

• Note: just the annotation of previous citation at 1.1

• Examples: Mystery derivative at 4.2, or a question at 4.6.

• Definition-like: A mathematical statement with no proof 4.11.

• A numbered Note: 4.9

• A link to a proposition element, while this document has globally renamed propositions as “Conundrum”s, so this link should use the new name: Conundrum 26.1

• Theorems: Fundamental Theorem of Calculus, with proof at 2.1

• Proof: of second version of FTC at 4.1.1

• Figures: A plot with a derivative at 5.2.

• A Figure within a side-by-side panel, with its own number: 22.5

• A Table within a side-by-side panel, with a subnumber: 22.14.(a)

• A Figure, containing a side-by-side with two sub-captioned images: 22.1

• Display Mathematics: single, first with no name: (4.1). Then with an autoname: (4.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).

• Display mathematics: an equation with “local” tag, which should not be used so very far away: ($\star\star$).

• 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.

• Exercise (inline): with enclosed hint at 4.4

• A group of two exercises, with introduction, conclusion: Exercise Group 11.2.2–3

• Solution: An autonamed portion of an exercise: Solution 42a.1

• Parts of a complicated exercise: Hint 12.2 Answer 12.1

• A subsidary part of an exercise: 12.1.b.i

• An item buried in nested ordered lists: Item 2.b.ii.C

• List item as knowls in HTML, including nested lists: 2, Item 2.b.ii

• A titled list: 12.2

• List item inside a named list, second color in rainbow list: Item 12.2:2

• Second color in rainbow list, but now as a local reference: Item 2

• An item in ordered list, but contained in an unordered list, hence without a number, so ambiguous: Item

• Same item in ordered list, but contained in an unordered list, now with a cross-reference by title with a content override: 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.3.

• An assemblage, which never has a number. A cross-reference now requires content in the xref element, with text='title': text to xref an assemblage

• A cross-reference to a list item in a description list, which has a title, but never a number: Mathematics. 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: Verbatim, Code!.

• 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 case within the proof of Claim 4.3: Case 3b: The inductive step

• 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: An Aside

• A cross-reference to an objectives block, 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

• An activity with full details following: 4.3

• An interactive program inside a program listing, to test if the Javascript will execute properly within a knowl: 20.8

• A cross-reference to a block quotation (which is never numbered): Quote by Dr Seuss

• A type-global cross-reference to a second-level task within a project: Task 4.4.c.iii, the encompassing project: 4.4, and a local reference c.iii.

• A subcaptioned named list: 22.23.(b)

• A cross-reference to a paragraph (p) in the statement of an exercise: paragraph. Notice that such a paragraph has no number and no title, so you need to (a) use text='title', and (b) provide custom text for the title, as an override that becomes the content of the link. You may wish to provide very explicit location information for hardcopy print. Notice that this is not a cross-reference to the exercise, just a small portion of it.

• 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.5

• A cross-reference to a poem, where we need to use a title for the link text, since a poem is 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. 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. 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. 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.

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/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 exercise are numbered under two different schemes): Checkpoint 4.4–4.2.1

• A range of equations: (4.2)–(4.3)

• A system of equations, given as range from first to last: (7.1)–(7.2)

• A range of sections, hand-named to be plural: Sections 3–17

• A range of bibliographic items: [1–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 Spreadsheet.