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 if you elect to use it.
     Any <tag>xref</tag> will
     <q>know</q>
     what it points to, so you can let it provide the
     <q>naming</q>
     part of the cross-reference text.
     You can turn this on globally with the command-line parameter <c>autoname</c>
         <idx><h>autoname</h></idx>
     set to <c>'yes'</c>.
     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.
   </p>
   <p>
     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 <em>non-breaking</em>
     space between the name and the reference.
     The autoname switch 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 has no indication of its type in the source:
     <xref ref="theorem-FTC" />.
     So by default you will just see a number that you can click on.
     If you use the <c>text="type-global"</c> switch then you should see
     <q>Theorem</q>
     prepended.
     Note that if you changed the theorem to a lemma,
     then that change would be reflected here automatically when autonaming is in effect.
   </p>
   <p>
     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 <c>text="type-global"</c> or <c>text="global"</c> as part of the <c>xref</c>.
     Each example below should look the same each time this article is processed,
     no matter how the global <c>autoname</c> is set.
     <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">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 global autonaming on,
     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 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:
     <xref ref="section-cross-referencing">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.
     Exercise<nbsp /><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" />.
         </p>
       </li>
       <li>
         <p>
           Citations: Judson's AATA with annotation at <xref ref="biblio-judson-AATA" />
         </p>
       </li>
       <li>
         <p>
           Citations: Judson's AATA with autoname that should have 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" />
         </p>
       </li>
       <li>
         <p>
           Note: just the annotation of previous citation at <xref ref="note-judson-AATA" />
         </p>
       </li>
       <li>
         <p>
           Examples: Mystery derivative at <xref ref="example-mysterious" />, or a question at <xref ref="sample-question" />.
         </p>
       </li>
       <li>
         <p>
           Definition-like: A mathematical statement with no proof <xref ref="principle-principle" />.
         </p>
       </li>
       <li>
         <p>
           A numbered Note: <xref ref="note-remark" />
         </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" />
         </p>
       </li>
       <li>
         <p>
           Proof: of second version of FTC at <xref ref="proof-FTC-corollary" />
         </p>
       </li>
       <li>
         <p>
           Figures: A plot with a derivative at <xref ref="figure-function-derivative" />.
         </p>
       </li>
       <li>
         <p>
           A Figure within a side-by-side panel, with its own number:
           <xref ref="another-regular-figure" />
         </p>
       </li>
       <li>
         <p>
           A Table within a side-by-side panel, with a subnumber:
           <xref ref="table-sidebyside-subtable" />
         </p>
       </li>
       <li>
         <p>
           A Figure, containing a side-by-side with two sub-captioned images:
           <xref ref="fig-sidebyside-global" />
         </p>
       </li>
       <li>
         <p>
           Display Mathematics: single, first with no name:
           <xref ref="equation-alternate-FTC" />.
           Then with an autoname:
           <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" />.
           Then with an autoname:
           <xref ref="equation-use-FTC" text="type-global" />.
           And two, with a plural form:
           <xref ref="equation-alternate-FTC">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" />.
         </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 autonaming:
           <xref first="exercises-null-problem" last="exercises-cosine-derivative">Exercises</xref>.
         </p>
       </li>
       <li>
         <p>
           Exercise (inline):
           with enclosed hint at <xref ref="exercise-essay" />
         </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: An autonamed portion of an exercise:
           <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" />
         </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" />, <xref ref="list-two-two-two" text="type-global" />
         </p>
       </li>
       <li>
         <p>
           A titled list: <xref ref="list-colors-rainbow" />
         </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 an autoname.
           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 an autoname:
           <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" />
         </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" />,
           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" />
         </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>

       <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>
 
     </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 an autonamed 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 <c>autoname</c> facility,
     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" /></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 autonaming attribute 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>
 
       <li>
         <p>
           Four theorems, with spaces, autonamed:
           <xref ref="theorem-FTC, theorem-number-01,             theorem-number-02, theorem-number-03" text="type-global" />
         </p>
       </li>
       <li>
         <p>
           Two equations, no spaces, autonamed:
           <xref ref="equation-alternate-FTC,equation-use-FTC" text="type-global" />
         </p>
       </li>
       <li>
         <p>
           Two bibliographic items, no autoname:
           <xref ref="biblio-judson-AATA, biblio-lay-article" />
         </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 autonaming and other features.
     <ul>
       <li>
         <p>
           A range of exercises, autonamed (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" />
         </p>
       </li>
       <li>
         <p>
           A system of equations, given as range from first to last:
           <xref first="equation-system-begin" last="equation-system-end" />
         </p>
       </li>
       <li>
         <p>
           A range of sections,
           hand-named to be plural: Sections<nbsp /><xref first="section-sage-cells" last="section-cross-referencing" />
         </p>
       </li>
       <li>
         <p>
           A range of bibliographic items:
           <xref first="biblio-judson-AATA" last="biblio-lay-article" />
         </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>


   <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="external/data/runningstatisticstemplate.ots" visual="external/data/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/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/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" /><xref ref="program-activecode-python" />
   </p>
 </section>