summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/expex/source/11_Refs.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/expex/source/11_Refs.tex')
-rw-r--r--Master/texmf-dist/doc/generic/expex/source/11_Refs.tex521
1 files changed, 521 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/expex/source/11_Refs.tex b/Master/texmf-dist/doc/generic/expex/source/11_Refs.tex
new file mode 100644
index 00000000000..03d2aeecfac
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/expex/source/11_Refs.tex
@@ -0,0 +1,521 @@
+
+
+\ifnum\secno < 1 \secno=11 \excnt=34 \fi
+
+\section Referring to examples and labeled parts of examples
+
+\nobreak\vskip-2ex
+\subsection*Unnamed reference
+
+\deftagsec{unnamedref}
+\begininventory
+\macros \idx{|\lastx|}, \idx{|\nextx|}, \idx{|\blastx|},
+\idx{|\anextx|}, \idx{|\bblastx|}\endmc
+\endinventory
+
+\noindent If $x$ is the value of |\excnt|, these macros produce
+$x-1$, $x$, $x-2$, $x+1$, $x-3$, respectively, expressed as an
+either an arabic or roman numeral, depending on the setting of
+|exnotype|. The example number counter is incremented early in
+the expansion of |\ex|
+and |\pex|, so if one of these macros is used inside an example,
+``last example'' has the meaning ``current example number''.
+Although |\excnt| is incremented early, it is incremented after
+local parameters are set. Consequently, if
+any of these macros is used in setting parameters in the optional
+argument of |\ex| or |\pex|, it acts as if it were being
+evaluated just before |\ex| or |\pex|.
+
+It is potentially dangerous to use macros like |\bblastx| or
+|\anextx| for reference to an example because later additions or
+deletions in the document can throw off the reference. This kind
+of misreference is particularly easy to overlook in proofing a
+document. It is better to assign names to the things you want to
+refer to and to refer to them by name, particularly in a document
+that will undergo a lot of rewriting. If reference by name is
+used and an intervening example is deleted or added, no problem
+arises. If the example which is referred to is deleted, then
+\Tex\ will report a missing reference.
+
+\subsection Named reference
+
+\deftagsec{named-reference}
+\begininventory
+\macros \idx{|\deftag|}, \idx{|\deftagex|}, \idx{|\deftaglabel|},
+ \idx{|\deftagpage|}, \idx{|\getref|},
+ \idx{|\getfullref|}\endmc
+\parameters*
+\idx{|tag|}& character string& \hfil (none)\cr
+\endinventory
+
+\noindent The core macros are \idx{|\deftag|} and
+\idx{|\getref|}. |\deftag| takes two (obligatory) arguments.
+After |\deftag{«reference»}{«tag»}| is executed, |\getref{«tag»}|
+expands to {\sl reference}, where the value of the reference is
+determined at the point the |\deftag| command was evaluated.
+\idx{|\deftagex|}|{«tag»}| expands to
+|\deftag{\the\exno}{«tag»}|. \idx{|\deftagpage|}|{«tag»}| expands
+to |\deftag{\the\pageno}{«tag»}|, but the expansion is delayed
+until after \Tex's page breaking mechanism has decided what page
+the |\deftag| command appears on. The tag/page pair which is
+generated in this case is written to a file only, so |\getref|
+cannot recover a page number until a tag-ref file is read.
+
+The evaluation of \idx{|\deftaglabel|}|{«tag»}| is more complex.
+|\pexcnt|, the setting of |labeltype|, and the setting of
+|everylabel| are used to construct the reference (either a letter
+or a number). The tag which is submitted to |\deftag| is $\sl
+tag'\!|.|tag$, where $\sl tag'$ is the example number tag.
+
+The code below produces (\nextx).
+
+\codedisplay
+\pex[interpartskip=0pt]
+\a First\deftag{the first part of example \lastx}{FP}
+\a Second\deftagex{snoopy}\deftaglabel{dog}
+\a Third\deftaglabel{a}
+\xe|endcodedisplay
+
+\framedisplay~
+\pex[interpartskip=0pt]
+\a First\deftag{the first part of example \lastx}{FP}
+\a Second\deftagex{snoopy}\deftaglabel{dog}
+\a Third\deftaglabel{a}
+\xe
+\endframedisplay
+
+\noindent Afterwards, assuming that the tag |snoopy| has not been
+redefined in the interim\par\nobreak\medskip
+
+\hskip3em
+\vtop{\openup1pt
+\halign{#\hfil& \quad$\to$\quad #\hfil\cr
+|\getref{snoopy}|& \getref{snoopy}\cr
+|\getref{snoopy.dog}|& \getref{snoopy.dog}\cr
+|\getfullref{snoopy.dog}|& \getfullref{snoopy.dog}\cr
+|\getref{snoopy.a}|& \getref{snoopy.a}\cr
+|\getfullref{snoopy.a}|& \getfullref{snoopy.a}\cr
+|\getref{dog}|& \it undefined tag warning, or spurious reference\cr
+|\getref{FP}|& \getref{FP}\cr
+}}
+
+\medskip
+\noindent |\getref{dog}| will produce a spurious reference if the
+tag |dog| is defined somewhere else in your document.
+|\deftaglabel| must know, at the point that it is expanded, what
+tag has been attached to the example number. If the example
+number has not been tagged at that point, a warning message is
+issued.
+
+There are two alternatives to the explicit use of |\deftagex| and
+|\deftaglabel|. One is the use of the parameter |tag|. After
+
+\codedisplay
+\pex[interpartskip=0pt,labeltype=alpha,tag=snoopy]
+\a First
+\a[tag=dog] Second
+\a Third\deftaglabel{A}
+\xe |endcodedisplay
+
+\noindent |\getref{snoopy}|, |\getref{snoopy.dog}|,
+and |\getref{snoopy.A}| are interpreted as expected, as are
+|\getfullref{snoopy.dog}| and
+|\getfullref{snoopy.A}|.
+
+The other alternative is a special ``tagging notation'' which,
+unlike most shortcuts, makes the code easier to read as well.
+After
+
+\codedisplay
+\pex[interpartskip=0pt,labeltype=alpha]<snoopy>
+\a First
+\a<dog> Second
+\a[tag=A] Third
+\xe |endcodedisplay
+
+\noindent |\getref{snoopy}|, |\getref{snoopy.dog}|, and
+|\getref{snoopy.A}| are interpreted as expected, as are
+|\getfullref{snoopy.dog}| and |\getfullref{snoopy.A}|.
+
+If |\getref{sometag}| is evaluated and the tag is undefined, a
+warning message to this effect is generated
+and~\hbox{$\bullet$|sometag|} is typeset instead of the intended
+reference.
+
+\subsection Proofing references
+
+\begininventory
+\macros* |\refproofing|\endmc
+\endinventory
+It is tedious to check that references to example numbers and the
+like are correct (i.e. refer to what you think they refer to).
+\ExPex\ provides a little help. If you execute
+\idx{|\refproofing|}, then all the references that are generated
+by |\bblastx|, |\blastx|, |\lastx|, |\nextx|, |\anextx|,
+|\getref|, and |\getfullref| are highlighted. If \PSTricks\ is
+loaded at the point that |\refproofing| is evaluated, the
+highlighting consists of a box around the reference. If not, the
+reference is under- and overlined. Highlighting is helpful
+in copy editing. The difference is illustrated below.
+
+\pex
+\a Consider (\getfullref{snoopy.dog}), for
+example.\qquad default behavior
+\refproofing
+\a Consider (\getfullref{snoopy.dog}), for example.\qquad
+|\refproofing|, \PSTricks\ available
+\a {\let\PSTricksLoaded\relax \refproofing
+\makeatletter
+\let\@highlightprint\mathhigh@lightref
+\resetatcatcode
+Consider (\getfullref{snoopy.dog}), for example.}\qquad
+|\refproofing|, \PSTricks\ not available
+\xe
+
+
+
+\subsection The tag/reference file
+
+\begininventory
+\macros \idx{|\gathertags|}, \idx{|\tagfilesuffix|}\endmc
+\endinventory
+
+\noindent Forward references require writing tag/reference
+associations to a file in one run, then reading this file in a
+second run. Forward reference is only one reason for such a
+system. If you work on a document in pieces, say one section at
+a time, and need to refer to things in prior sections, then the
+tag/reference pairs from previous sections must be stored in a
+file so that they can be used in the section that you are working
+on. If you say \idx{|\gathertags|}, the tag/reference pairs will
+be written to a file as they are established. If your main file
+is named {\sl foop.tex}, for example, the default is to write the
+tag/ref pairs to {\sl foop-tags.tex}. But you can modify this by
+using the command \idx{|\tagfilesuffix|}. \slname{expex.tex}
+contains |\tagfilesuffix{-tags}|, but you can overrule this with
+|\tagfilesuffix{«your suffix»}|.
+
+When the first |\getref|, |\getfullref|, or |\gathertags| command
+is encountered, \ExPex\ checks to see if there is a tag file. If
+the file does exist, it is read and all the tag/reference pairs
+it encodes are established. No testing is done for conflicting
+tag/reference pairs with the same tag, so it is the
+responsibility of the user to see that this does not occur to a
+bad effect. If the user wants to be absolutely sure that bad
+references have not accidentally occurred because of using the
+same tag twice, he/she can look directly at the tag file in a
+text editor. If the lines are alphabetized, it is relatively
+easy to find tags for which multiple references have been
+established. If you are a careful copy editor, this may be worth
+doing in a complex project (a book length manuscript) during
+final copy editing. Of course, the printed final manuscript
+should be checked in any event to make sure that the references
+refer to what you want them to refer to.
+
+For what it is worth, my own style of work is to break up
+projects into multiple pieces and have a main file which calls
+the various pieces. Then I simply comment out the calls to
+pieces that I am not working on. From time to time I will run
+the main file calling on all the various pieces, invoking
+|\gathertags|. Then I comment out |\gathertags|. The tag-ref
+file which is created then remains intact until |\gathertags| is
+invoked at some future time. All of the tag/reference pairs it
+encodes are available in subsequent work until a new tags file is
+created.
+
+\subsection References to references, references as values
+
+\begininventory
+\macros* \idx{|\lastlabel|}\endmc
+\endinventory
+%
+If, for some reason, you want to refer to a specific
+part of a multipart example without tagging the example number,
+it can be done as follows, assuming that the part labels are
+alphabetical.
+
+\codedisplay
+\pex[everylabel=\it]
+\a First Example.
+\a Second Example.\deftag{\lastx\lastlabel}{snoopy}
+\a Third Example.
+\xe
+|endcodedisplay
+\framedisplay
+\pex[everylabel=\it]
+\a First Example.
+\a Second Example.\deftag{\lastx\lastlabel}{snoopy}
+\a Third Example.
+\xe
+\endframedisplay
+
+\noindent You can then use |\getref{snoopy}| to retrieve
+\getref{snoopy}. |\lastlabel| expands to the most recent label,
+in the form in which it is printed (i.e. containing the expansion
+of |\everylabel|). If the part labels are numerical, then
+|\deftag{\lastx.\lastlabel}| is required.
+
+You can also say:
+
+\sidx{|exno|, setting by reference}%
+\codedisplay
+\ex[exno=\getref{snoopy}] Second example.\xe|endcodedisplay
+
+\framedisplay~
+\ex[exno=\getref{snoopy}] Second example.\xe
+\endframedisplay
+\medskip
+
+Or you can say:
+
+\codedisplay
+\ex[exno={\getref{snoopy}, repeated},exnoformat={[X]}]
+Second example.\xe
+|endcodedisplay
+
+\framedisplay~
+\ex[exno={\getref{snoopy}, repeated},exnoformat={[X]}]
+Second example.\xe
+\endframedisplay
+%
+Braces must hide the comma in the value which sets the key.
+
+If you say
+
+\codedisplay
+\pex[labeltype=numeric]<dog>
+\a First Example.
+\a<G> Second Example.
+\a Third Example.
+\xe|endcodedisplay
+
+\framedisplay~
+\pex[labeltype=numeric]<dog>
+\a First Example.
+\a<G> Second Example.
+\a Third Example.
+\xe
+\endframedisplay
+
+\noindent then, if you want to repeat (\getfullref{dog.G}) at
+some point, you can use:
+
+\codedisplay
+\ex[exno=\getfullref{dog.G}] Second example\xe
+|endcodedisplay
+
+\framedisplay~
+\ex[exno={\getfullref{dog.G}}] Second example\xe
+\endframedisplay
+
+\subsection Extensions of the tag/reference mechanism
+
+The tag/reference mechanism can easily be extended to reference
+to chapters, sections, and subsections. Suppose, for example,
+that there are counters for the chapter number, section number,
+subsection number, and subsubsection number. One might define:
+
+\codedisplay
+\def\currsec{\the\chapterno
+ \ifnum\secno>0 .\the\secno
+ \ifnum\subsecno>0 .\the\subsecno
+ \ifnum\subsubsecno>0 .\the\subsubsecno \fi\fi\fi}
+\def\deftagsec#1{\deftag\currsec{#1}}|endcodedisplay
+
+\noindent This assumes that there are counters |\chapterno|,
+|\secno|, |\subsecno|, and |\subsecsecno| and that when a chapter
+is initiated, |\secno| is set to 0, when a section is initiated,
+|\secsecno| is set to 0, and that when a subsection is initiated,
+|\subsubsecno| is set to 0. (Lines 1--5, commented out,
+are included at the end of {\sl expex.tex\/} for the user to
+use, modify, or ignore.)
+
+
+\subsection The parameter {\tt fullreformat}
+
+\begininventory
+\parameters*
+\idx{|fullrefformat|}& $\ldots\,|X|\,\ldots\,|A|\,\ldots$ & |XA|\cr
+\endinventory
+
+\begingroup
+\parindent=0pt \leftskip=1.2em
+
+1. |labelformat| (see page \getref{labelformatpage}) determines how the labels are formatted.
+Generally they are followed by a period, but this parameter
+allows other possibilities.
+\smallskip
+
+2. |fullrefformat| determines how references retrieved by
+|\getfullref| are formatted. Generally, example numbers and
+labels are concatenated if the labels are characters and
+separated by a period if the labels are numbers. This parameter
+allows other possibilities. The format specification is
+primitive. The value of |fullrefformat| is analyzed as
+|#1X#2A#3|, with |X| preceding |A|. Then the full reference is
+found by substituting the example number for |X| and the part
+label for |A|.
+\smallskip
+\endgroup
+
+Consider the artificial example below, with unusual formatting
+for illustrative purposes.
+
+\begingroup
+\setss .65 .35
+\beginss
+\pex[labeltype=numeric,labelformat={[A]},
+ fullrefformat=X-A,samplelabel={[1]}]<K>
+\a first
+\a<A> second
+\xe|midss
+\pex[labeltype=numeric,labelformat={[A]},
+ fullrefformat=X-A,samplelabel={[1]}]<K>
+\a first
+\a<A> second
+\xe
+\endss
+\endgroup
+|\getref{K.A}| produces \getref{K.A} and |\getfullref{K.A}|
+produces \getfullref{K.A}.
+
+\subsection Reference to a part of a multipart example
+
+Suppose there is a multipart example which you want to partially
+repeat at a later point, giving only some of the parts. There are
+many opportunities to make a mistake. The reference to the
+example number may be wrong, the references to the part labels my
+be wrong, or a particular part may not be repeated the way it
+originally appeared. Here is one way to (partially) automate the
+references to avoid most of the possible reference
+errors.
+
+\begingroup
+\setss .53 .43
+\beginss
+\deftag{Someone loves everyone.}{1st}
+\deftag{Everyone loves someone.}{2nd}
+
+\pex<A>
+\a \dots
+\a<X> \getref{1st}
+\a \dots
+\a<Z> \getref{2nd}
+\xe
+
+\ex An intervening example.\xe
+
+The two crucial examples in
+(\getref{A}) are repeated below:
+
+\pex[exno=\getref{A}]
+\a[label=\getref{A.X}] \getref{1st}
+\a[label=\getref{A.Z}] \getref{2nd}
+\xe
+
+\ex Numbering resumes.\xe|midss
+\deftag{Someone loves everyone.}{1st}
+\deftag{Everyone loves someone.}{2nd}
+
+\pex<A>
+\a \dots
+\a<X> \getref{1st}
+\a \dots
+\a<Z> \getref{2nd}
+\xe
+
+\bigskip
+\ex An intervening example.\xe
+
+\bigskip
+The two crucial examples in
+(\getref{A}) are repeated below:
+
+\bigskip
+\deftag{\the\secno.\the\subsecno}{explicit-sec}%
+\pex[exno=\getref{A}]
+\a[label=\getref{A.X}] \getref{1st}
+\a[label=\getref{A.Z}] \getref{2nd}
+\xe
+
+\bigskip
+\ex Numbering resumes.\xe
+\endss
+%
+{\bf Important limitation}:\enspace Inside an example that sets
+|exno| to a nonempty value, the use of |\deftaglabel| or
+|\deftagex|, or their implicit versions using the |<|\dots|>|
+notation, or |\label|, will result in an error or (more
+dangerously) an unexpected outcome. This is a minor limitation
+because there should be no need to tag items which themselves are
+referenced by tags. It is important only because violating it
+can generate Tex errors.\endgroup
+
+\subsection Support for the LaTex \ttcs{label} and
+\ttcs{ref} commands%
+
+\deftag{\the\secno.\the\subsecno}{labelsec}
+
+\sidx{|\label|, use of the LaTex macro}
+\sidx{|\ref|, use of the LaTex macro}
+\noindent LaTex users, if so inclined, may wish to use the LaTex
+|\label|-|\ref| mechanism to tag example numbers and example part
+labels.
+
+Assuming that LaTex is in use,
+
+\beginss
+\pex \label{A}
+\a Tom\label{B}
+\a Dick\label{C}
+\a Harry\label{D}, etc.
+\xe
+
+\ex~ Intervening example.\xe
+
+\noindent Consider example (\ref{A}).
+Tom is in example (\ref{B}), Dick is
+in example (\ref{C}), and Harry is in
+example (\ref{D}).|midss
+%%%%
+\pex[aboveexskip=1ex,nopreamble]\deftagex{A}
+\a Tom\deftaglabel{B}
+\a Dick\deftaglabel{C}
+\a Harry\deftaglabel{D}, etc.
+\xe
+
+\bigskip
+\ex~ Intervening example\xe
+
+\bigskip
+\noindent Consider example (\getref{A}). Tom is in example
+(\getfullref{A.B}), Dick is in example (\getfullref{A.C}), and
+Harry is in example (\getfullref{A.D}).
+\medskip
+%%%%
+\endss
+
+There are important differences between the LaTex mechanism and
+the |\deftag|-|\getref| mechanism.
+
+\smallskip
+\noindent 1.\enspace
+|\ref{|{\it tag}|}| cannot be used as a special example number,
+nor can it be given as an optional argument to |\a|.
+
+\smallskip
+\noindent 2.\enspace
+The |\label| name space is flat. No distinction is made between
+names of examples and names of parts of examples. This makes it
+much harder to remember and manage the names, at least for me.
+
+\smallskip
+\noindent 3.\enspace
+LaTex provides no control over the generation of the file
+containing the tag-reference pairs. One cannot work on Chapter 5
+(for example) and have all the tag-reference information for the
+earlier chapters available without actually submitting all of the
+Chapters 1 to 4 to LaTex while you are working on Chapter 5.
+
+
+