diff options
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.tex | 521 |
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. + + + |