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, 0 insertions, 521 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
deleted file mode 100644
index 03d2aeecfac..00000000000
--- a/Master/texmf-dist/doc/generic/expex/source/11_Refs.tex
+++ /dev/null
@@ -1,521 +0,0 @@
-
-
-\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.
-
-
-