Derivatives and Integrals An Annotated Discourse

<section xml:id="section-cross-referencing" label="section-cross-referencing">

  <title>Cross-Referencing</title>

  <p>
    Cross-references
    <idx>cross-reference</idx>
    are easy, since that is a key reason for having a highly structured document.
    Here is a useful feature.
    Any <tag>xref</tag> will <q>know</q> what it points to, so you can let it provide the <q>type name</q> part of the cross-reference text, such as <q>Theorem</q> or <q>Section</q>.
    You control this document-wide with the <attr>text</attr> attribute of the <tag>cross-references</tag> element in your <tag>docinfo</tag><idx><h>cross-reference</h><h>type name</h></idx>.
    The value <c>type-global</c><mdash/>the default, and what this article uses<mdash/>supplies the type name automatically, so there is no need to write it into your source.
  </p>

  <p>
    Moreover, the names themselves will change with the use of the one language-dependent file.
    And another bonus is that with an automatic type name, you get a <em>non-breaking</em> space between the name and the reference.
    A type name makes no sense for <q>provisional</q> cross-references, since there is no information about what they point to.
  </p>

  <p>
    Here is a reference that suppresses its type with <c>text="global"</c>:  <xref ref="theorem-FTC" text="global"/>.
    So you will just see a number that you can click on.
    Using <c>text="type-global"</c><mdash/>or simply accepting the document default<mdash/>you would instead see <q>Theorem</q> prepended.
    Note that if you changed the theorem to a lemma, then that change would be reflected here automatically.
  </p>

  <p>
    Whatever document-wide default you set with <tag>cross-references</tag>, there will still be instances where you want to override that choice.
    Simple: just say <c>text="type-global"</c> or <c>text="global"</c> as part of the <tag>xref</tag>.
    Each example below should look the same each time this article is processed, no matter the document-wide <tag>cross-references</tag> setting.
    <ul>

      <li>

        <p>
          No name ever: <xref ref="corollary-FTC-derivative" text="global"/>
        </p>

      </li>

      <li>

        <p>
          Always named: <xref ref="corollary-FTC-derivative" text="type-global"/>
        </p>

      </li>

    </ul>

  </p>

  <p>
    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 <c>xref</c> 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 <c>xref</c> content totally overrides any prefix that might happen otherwise.
    So the name of an item (<eg/> <q>corollary</q>) could be replaced, and if you make a cross-reference with custom text, that will be the clickable also.
    An example:
    <ul>

      <li>

        <p>
          A grand result: <xref ref="corollary-FTC-derivative" text="global">Major Corollary</xref>
        </p>

      </li>

      <li>

        <p>
          A grand result: <xref ref="corollary-FTC-derivative" text="custom">a nice corollary</xref>
        </p>

      </li>

    </ul>

  </p>

  <p>
    Suppose you want to reference two theorems, so you might want to say something like <q>Theorems 4.6 and 5.2.</q>  With type names shown (the default), you can override the first <c>Theorem</c> by providing the content <c>Theorems</c> on the first <c>xref</c> and <c>text="global"</c> on the second <c>xref</c>.
    (With type names suppressed, you will also get what you want/expect.)   Here is the test, which should look correct no matter the document-wide setting:  <xref ref="section-cross-referencing" text="global">Sections</xref> and <xref ref="section-internationalization" text="global"/>.
    (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 <c>xref</c>.
    The <q>author-tools</q> mode and careful choices of <c>xml:id</c> strings can help avoid this trap.)
  </p>

  <p>
    If you set the value of <attr>text</attr> to <c>title</c>, 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 <xref ref="theorem-FTC" text="title"/>.
  </p>

  <p>
    Cross-references to exercises with hard-coded numbers should respect the supplied number.
    <xref ref="exercise-with-hardcoded-number"/> should reference problem 42a.
  </p>

  <p>
    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 <q>in-context</q> link which will take you to the actual location, should you have  wished instead to just go there.
    <ul>

      <li>

        <p>
          Footnotes: Fermat allusion at <xref ref="footnote-fermat" text="global"/>.
        </p>

      </li>

      <li>

        <p>
          Citations: Judson's AATA with annotation at <xref ref="biblio-judson-AATA" text="global"/>
        </p>

      </li>

      <li>

        <p>
          Citations: Judson's AATA with a type name, which has zero effect <xref ref="biblio-judson-AATA" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          Citations: In a <tag>references</tag> division inside an appendix <xref ref="biblio-strang-article-uno" text="global"/>
        </p>

      </li>

      <li>

        <p>
          Note: just the annotation of previous citation at <xref ref="note-judson-AATA" text="global"/>
        </p>

      </li>

      <li>

        <p>
          Examples: Mystery derivative at <xref ref="example-mysterious" text="global"/>, or a question at <xref ref="sample-question" text="global"/>.
        </p>

      </li>

      <li>

        <p>
          Definition-like: A mathematical statement with no proof <xref ref="principle-principle" text="global"/>.
        </p>

      </li>

      <li>

        <p>
          A numbered Note: <xref ref="note-remark" text="global"/>
        </p>

      </li>

      <li>

        <p>
          A link to a <c>proposition</c> element, while this document has globally renamed <c>proposition</c>s as <q>Conundrum</q>s, so this link should use the new name: <xref ref="proposition-as-conundrum" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          Theorems: Fundamental Theorem of Calculus, with proof at <xref ref="theorem-FTC" text="global"/>
        </p>

      </li>

      <li>

        <p>
          Proof: of second version of FTC at <xref ref="proof-FTC-corollary" text="global"/>
        </p>

      </li>

      <li>

        <p>
          Figures: A plot with a derivative at <xref ref="figure-function-derivative" text="global"/>.
        </p>

      </li>

      <li>

        <p>
          A Figure within a side-by-side panel, with its own number: <xref ref="another-regular-figure" text="global"/>
        </p>

      </li>

      <li>

        <p>
          A Table within a side-by-side panel, with a subnumber: <xref ref="table-sidebyside-subtable" text="global"/>
        </p>

      </li>

      <li>

        <p>
          A Figure, containing a side-by-side with two sub-captioned images: <xref ref="fig-sidebyside-global" text="global"/>
        </p>

      </li>

      <li>

        <p>
          Display Mathematics: single, first with no name: <xref ref="equation-alternate-FTC" text="global"/>.
          Then with a type name: <xref ref="equation-alternate-FTC" text="type-global"/>.
        </p>

      </li>

      <li>

        <p>
          Display Mathematics: multi-row, first with no name: <xref ref="equation-use-FTC" text="global"/>.
          Then with a type name: <xref ref="equation-use-FTC" text="type-global"/>.
          And two, with a plural form: <xref ref="equation-alternate-FTC" text="global">Equations</xref> and <xref ref="equation-use-FTC" text="global"/>.
        </p>

      </li>

      <li>

        <p>
          You can cross-reference <xref ref="equation-use-FTC" text="custom">The Fundamental Theorem of Calculus</xref> via custom text of your choice.
        </p>

      </li>

      <li>

        <p>
          Display mathematics: an equation with  <q>local</q> tag, which should not be used so very far away: <xref ref="equation-local-star" text="global"/>.
        </p>

      </li>

      <li>

        <p>
          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.
        </p>

      </li>

      <li>

        <p>
          Exercises (divisional), a range, with plural form provided to override the type name: <xref first="exercises-null-problem" last="exercises-cosine-derivative" text="global">Exercises</xref>.
        </p>

      </li>

      <li>

        <p>
          Exercise (inline): with enclosed hint at <xref ref="exercise-essay" text="global"/>
        </p>

      </li>

      <li>

        <p>
          A group of two exercises, with introduction, conclusion: <xref ref="exercisegroup-two-problems" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          Solution: A portion of an exercise, with its type name: <xref ref="solution-antiderivative" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          Parts of a complicated exercise: <xref ref="exercise-complicated-second-hint" text="type-global"/> <xref ref="exercise-complicated-first-answer" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          A subsidary part of an exercise: <xref ref="exercise-one-two-one" text="global"/>
        </p>

      </li>

      <li>

        <p>

          <idx><h>knowl</h><h>nested</h></idx>
          Three cross-references to individual exercises, but due to their location, they should have different <q>type names</q> in the cross-reference: in an <tag>exercises</tag> division, <xref ref="duplicate-divisional" text="type-global"/>; in the narrative, <xref ref="exercise-essay" text="type-global"/>; and in a <tag>worksheet</tag>, <xref ref="exercise-vector-addition" text="type-global"/>.
        </p>

      </li>

      <li>

        <p>
          An item buried in nested ordered lists: <xref ref="list-two-two-two-three" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          List item as knowls in HTML, including nested lists: <xref ref="list-two" text="global"/>, <xref ref="list-two-two-two" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          A titled list: <xref ref="list-colors-rainbow" text="global"/>
        </p>

      </li>

      <li>

        <p>
          List item inside a named list, second color in rainbow list: <xref ref="rainbow-orange" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          Second color in rainbow list, but now as a local reference: <xref ref="rainbow-orange" text="type-local"/>
        </p>

      </li>

      <li>

        <p>
          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: <xref ref="target-no-number" text="custom">No Number List Item</xref>
        </p>

      </li>

      <li>

        <p>
          Several examples of hybrid cross-references to list items within a named list can be found in, and adjacent to, <xref ref="list-to-reference" text="type-global"/>.
        </p>

      </li>

      <li>

        <p>
          An assemblage, which never has a number.
          A cross-reference now requires content in the <c>xref</c> element, with <c>text='custom'</c>: <xref ref="assemblage-basics" text="custom">text to xref an assemblage</xref>
        </p>

      </li>

      <li>

        <p>
          A cross-reference to a list item in a description list, which has a title, but never a number: <xref ref="cpu-definition" text="title"/>.
          Note that you need to include the attribute <c>text="title"</c> even if that is obvious from the situation.
          This requirement may be relaxed in a future refactoring of the cross-reference system.
        </p>

      </li>

      <li>

        <p>
          A very similar cross-reference to the previous one, but testing how final punctuation of titles is handled: <xref ref="bus-definition" text="title"/>.
        </p>

      </li>

      <li>

        <p>
          A cross-reference to a <q>paragraphs</q> subdivision, which never has a number (so comments above about description list items and titles applies here too): <xref ref="hierarchy-structure" text="title"/>
        </p>

      </li>

      <li>

        <p>
          A case within the proof of <xref ref="claim-with-cases" text="type-global"/>: <xref ref="inductive-step" text="title"/>
        </p>

      </li>

      <li>

        <p>
          A cross-reference to a description list item with a title containing math: <xref ref="description-list-math-title" text="title"/>
        </p>

      </li>

      <li>

        <p>
          A cross-reference to an aside, by title necessarily, and with some formatting in the title: <xref ref="an-aside" text="title"/>
        </p>

      </li>

      <li>

        <p>
          A cross-reference to an <c>objectives</c> block, with a type name.
          This demonstrates the number of the Objectives here, which is not shown in the original version since it is implicit: <xref ref="objectives-structures" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          A cross-reference to an individual objective.
          This is authored as a list item, but displayed as an objective (singular) via a type name: <xref ref="objective-structure" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          A cross-reference to the top-level element (<eg/><c>book</c>) 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:  <xref ref="derivatives" text="custom">ToC or Title</xref>
        </p>

      </li>

      <li>

        <p>

          <q>Cross-references inside quotations previously lost track of their target, so this tests correcting that, not so much the cross-reference itself: <xref ref="theorem-FTC" text="type-global"/></q>

        </p>

      </li>

      <li>

        <p>
          An activity with full details following: <xref ref="activity-with-hint-answer-solution" text="global"/>
        </p>

      </li>

      <li>

        <p>
          A <c>type-global</c> cross-reference to a second-level <c>task</c> within a project: <xref ref="project-task-level-two" text="type-global"/>, the encompassing <c>project</c>: <xref ref="project-structured" text="global"/>, and a <c>local</c> reference <xref ref="project-task-level-two" text="local"/>.
        </p>

      </li>

      <li>

        <p>
          A subcaptioned named list: <xref ref="color-list-as-panel" text="global"/>
        </p>

      </li>

      <li>

        <p>
          This opens a knowl for an <c>example</c>.
          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 <init>HTML</init> id.
          So we test its styling and function here: <xref ref="example-structured" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          A cross-reference to a poem, where we need to use a title for the link text, since a <c>poem</c> is not numbered: <xref ref="poem-light-brigade" text="title"/>
        </p>

      </li>

      <li>

        <p>
          A cross-reference to a <tag>references</tag> division in a subsection, which should not be numbered where born, but which has the number of its parent division in a cross-reference: <xref ref="references-section" text="type-global"/>.
          And a cross-reference to a <tag>references</tag> division, which is the <q>main</q> 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): <xref ref="references-backmatter" text="title"/>.
        </p>

      </li>

      <li>

        <p>
          A cross-reference to a <tag>solutions</tag> division in a subsection, which should not be numbered where born, but which has the number of its parent division in a cross-reference: <xref ref="solutions-subsection" text="type-global"/>.
          And a cross-reference to a <tag>solutions</tag> division, which should appear as an appendix both where born and as a cross-reference: <xref ref="solutions-backmatter" text="type-global"/>.
        </p>

      </li>

      <li>

        <p>
          A cross-reference to an <tag>exercises</tag> 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: <xref ref="exercises-subsection-solo" text="type-global"/>.
          In contrast we cross-reference an <tag>exercises</tag> 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: <xref ref="exercises-section-multiple" text="type-global"/>.
          Also an <tag>exercise</tag> within an <tag>exercises</tag> which should have a cross-reference employing the number of the containing (unstructured) <tag>section</tag>: <xref ref="duplicate-divisional" text="type-global"/> which is in <xref ref="exercise-collection" text="type-global"/> which is in the (unstructured) <xref ref="exercises-single" text="type-global"/>.
        </p>

      </li>

      <li>

        <p>
          A custom cross-reference: <xref ref="corollary-FTC-derivative" text="custom">Custom</xref>
        </p>

      </li>

      <!-- Instructions for Interactives are not numbered, so use a simpler @text -->

      <li>

        <p>
          Cross-reference to <tag>instructions</tag> of an <tag>interactive</tag>: <xref ref="kinematics-instructions" text="title"/>
        </p>

      </li>

      <li>

        <p>
          A hyperlink to a <tag>subexercises</tag> via its required title (no number is assigned): <xref ref="hard-subexercises" text="title"/>
        </p>

      </li>

      <li>

        <p>
          You can request the text to be a type, then a number, then a title: <xref ref="theorem-FTC" text="type-global-title"/>
        </p>

      </li>

      <li>

        <p>
          Asking for the text to be a type, then a number, then a title, when there is no title, is not a problem: <xref ref="corollary-FTC-derivative" text="type-local-title"/>
        </p>

      </li>

      <!-- Accumulate examples here --> <!--

      <li>

        <p>
          : <xref ref="" text=""/>
        </p>

      </li>

      -->
    </ul>

  </p>

  <p>
    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 a type-named link to a subsubsection:  <xref ref="subsubsection-different-integrals" text="type-global"/>.
  </p>

  <p>
    Cross-references can be built into display mathematics, but they can only point to one item (<ie/> 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 automatic type name, you need to wrap non-math text in <c>\text{}</c> and perhaps use a tilde (<c>~</c>) as a non-breaking space (examine the source of this article).
  </p>

  <p>

    <md>

      <mrow>x^2 + y^2 &amp;= z^2&amp;&amp;<xref ref="theorem-FTC" text="type-global"/></mrow>

      <mrow>a^2 + b^2 &amp;= c^2&amp;&amp;\text{Section}~<xref ref="section-fundamental-theorem" text="global"/></mrow>

    </md>

    <idx><h>bug</h><h>in-context broken</h></idx>

  </p>

  <p>
    Variations on the above include multiple <c>xml:id</c> as the value of a single <c>ref</c> attribute on an <c>xref</c>, in the form of a comma-separated list.
    In this case, only the numbers are links/knowls and the type name is based on the type of the first <c>ref</c>.
    Wrapping with brackets (citations) or parentheses (equations) is also controlled by the type of the first <c>ref</c>.
    And the <c>detail</c> 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.
    <ul>

      <!-- NB: a knowl for "theorem-number-02" will *only* be created if this list is decomposed --> <!-- properly, so do not remove, and certainly do not cross-reference it elsewhere         -->

      <li>

        <p>
          Four theorems, with spaces, with type names: <xref ref="theorem-FTC, theorem-number-01, theorem-number-02, theorem-number-03" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          Two equations, no spaces, with type names: <xref ref="equation-alternate-FTC,equation-use-FTC" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          Two bibliographic items, no type name: <xref ref="biblio-judson-AATA, biblio-lay-article" text="global"/>
        </p>

      </li>

      <!--

      <li>

        <p>
          : <xref ref=""/>
        </p>

      </li>

      -->
    </ul>

  </p>

  <p>
    If you have a long list of items (such as homework exercises, not in an <c>exercisegroup</c>, or perhaps several chapters), you can get a cross-reference that prints as a range by using <c>xref</c> with two attributes <c>first</c> and <c>last</c>, which may contain a single <c>xml:id</c> each.
    As with multiple references, <c>first</c> will control the type name and other features.
    <ul>

      <li>

        <p>
          A range of exercises, with type names (this range appears <q>out-of-order</q> since the two <c>exercise</c> are numbered under two different schemes): <xref first="exercise-essay" last="exercise-test-number" text="type-global"/>
        </p>

      </li>

      <li>

        <p>
          A range of equations: <xref first="equation-use-FTC" last="equation-conclude" text="global"/>
        </p>

      </li>

      <li>

        <p>
          A system of equations, given as range from first to last: <xref first="equation-system-begin" last="equation-system-end" text="global"/>
        </p>

      </li>

      <li>

        <p>
          A range of sections, hand-named to be plural: Sections<nbsp/><xref first="section-sage-cells" last="section-cross-referencing" text="global"/>
        </p>

      </li>

      <li>

        <p>
          A range of bibliographic items: <xref first="biblio-judson-AATA" last="biblio-lay-article" text="global"/>
        </p>

      </li>

      <!--

      <li>

        <p>
          : <xref ref=""/>
        </p>

      </li>

      -->
    </ul>

  </p>

  <p>
    The <c>url</c><idx>url</idx>
    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.
    <idx><h>reference</h><h>external</h></idx>
    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: <url href="http://go.microsoft.com/fwlink/?LinkID=521962" visual="go.microsoft.com/fwlink/?LinkID=521962">Sample Excel Spreadsheet</url>.
  </p>

  <p>
    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.
  </p>

  <!-- http://templates.openoffice.org/en/template/running-statistics-template --> <!-- http://templates.openoffice.org/template/download/1203 -->

  <p>
    You can also provide a file yourself, but now it is your obligation to distribute the file with your document (<init>HTML</init>, <init>PDF</init>, <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):  <url href="data/spreadsheet/runningstatisticstemplate.ots" visual="data/spreadsheet/runningstatisticstemplate.ots">Running Statistics Template</url>.
  </p>

  <p>
    The next four paragraphs are each a single <tag>dataurl</tag> element.
    Explore the source and the output from different conversions.
    Strictly for testing as of 2022-11-04.
  </p>

  <p>
    Foo <dataurl href="http://go.microsoft.com/fwlink/?LinkID=521962" visual="go.microsoft.com/fwlink/?LinkID=521962">Sample Excel Spreadsheet</dataurl> Bar
  </p>

  <p>
    Foo <dataurl source="data/spreadsheet/runningstatisticstemplate.ots" visual="http://example.com">Runners Template</dataurl> Bar
  </p>

  <p>
    Foo <dataurl href="http://go.microsoft.com/fwlink/?LinkID=521962">Sample Excel Spreadsheet</dataurl> Bar
  </p>

  <p>
    Foo <dataurl source="data/spreadsheet/runningstatisticstemplate.ots">Runners Template</dataurl> Bar
  </p>

  <p>
    Testing of output positioning for xref's that are inside containers:
  </p>

  <table xml:id="self-referential-tabular-xref">

    <title>Self-referential Xref In a table</title>

    <tabular>

      <row bottom="medium">

        <cell>A</cell>

        <cell>B</cell>

        <cell>C</cell>

        <cell>D</cell>

      </row>

      <row>

        <cell><xref ref="self-referential-tabular-xref" text="type-global"/></cell>

        <cell>B</cell>

        <cell>C</cell>

        <cell>D</cell>

      </row>

    </tabular>

  </table>

  <figure>

    <caption>Xref Inside MathJAX</caption>

    <p>

      <md>

        <mrow>{\mathbb Z}_2 \times {\mathbb Z}_2</mrow>

        <mrow><xref ref="theorem-FTC" text="type-global"/></mrow>

        <mrow>{\mathbb Z}_2 \times {\mathbb Z}_2</mrow>

      </md>

    </p>

  </figure>

  <p>
    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.<xref ref="program-activecode-python" text="global"/><xref ref="program-activecode-python" text="global"/>
  </p>

</section>