summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex')
-rw-r--r--Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex250
1 files changed, 137 insertions, 113 deletions
diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex
index 64d5028f629..3079e6384a0 100644
--- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex
+++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex
@@ -105,6 +105,11 @@
zcLanguageSetup,
zcRefTypeSetup,
zcheck,
+ zvref,
+ zvpageref,
+ zvrefrange,
+ zvpagerefrange,
+ zfullref,
}
}
\lstset{
@@ -266,14 +271,14 @@ as the main entrance for reference making, whose behavior can be modulated by
local options.
Considering that \pkg{zref} itself offers the \pkg{zref-titleref} module, and
-that the integration with \pkg{zref-check} allows \pkg{zref-clever} to make
-context sensitive references, a significant part of the most prominent
-automation features available to the standard referencing system is thus
-brought to \pkg{zref}, working under a single consistent underlying
-infrastructure and user interface. There are some limitations, of course (see
-\zcref{sec:limitations}), and it may be your cup of tea or not. Still, all in
-all, hopefully \pkg{zref-clever} can make \pkg{zref} more accessible, and
-interesting, to the average user.
+that \pkg{zref-vario} offers integration of \pkg{zref-clever} with
+\pkg{varioref}, a significant part of the most prominent automation features
+available to the standard referencing system is thus brought to \pkg{zref},
+working under a single consistent underlying infrastructure and user
+interface. Alas, there are some limitations (see \zcref{sec:limitations}),
+and it may be your cup of tea or not. Still, all in all, hopefully
+\pkg{zref-clever} can make \pkg{zref} more accessible to the average user, and
+more interesting to users in general.
\section{Warning}
@@ -501,7 +506,43 @@ and defaults to \texttt{true}. The \opt{nocomp} option is a convenience alias
for \texttt{comp=false}. Of course, for better compression results the
\opt{sort} is recommended, but the two options are technically independent.
+\DescribeOption{endrange} %
+The \opt{endrange} option provides additional control over how the end
+reference of a range is typeset, so as to achieve terse ranges. The option
+can operate in two technically different ways. It may receive one of a number
+of predefined values, which can process the end reference of the range,
+comparing it with the beginning reference, to achieve a given end
+result.\footnote{For the \TeX{}nically inclined: those values that perform
+ some processing -- namely \texttt{stripprefix}, \texttt{pagecomp}, and
+ \texttt{pagecomp2} -- fully expand the references (\texttt{x}-type
+ expansion) before comparing them, since it makes sense to perform this task
+ as close as possible to the printed representation of the references. I
+ don't expect this to be a problem in normal use cases, but it does represent
+ a limitation on what the references can contain. In case some control over
+ this is needed, check the \texttt{zref-clever/endrange-setup} hook in the
+ code documentation.} Or, it can specify a label property to be used
+directly, without any processing. The available predefined values are:
+\texttt{ref}, \texttt{stripprefix}, \texttt{pagecomp}, and \texttt{pagecomp2}.
+\texttt{ref} corresponds to the default behavior, and instructs \cs{zcref} to
+use whatever property was set at the \opt{ref} option for the end of range
+reference. \texttt{stripprefix} strips the common part at the start of each
+reference from the end one. \texttt{pagecomp} is the equivalent of
+\texttt{stripprefix} for page numbers, it does the same thing, but only if the
+references are comprised exclusively of Arabic numerals. \texttt{pagecomp2}
+is a variant of \texttt{pagecomp} that leaves at least two digits at the end
+reference (except for a leading zero). If values other than the predefined
+ones are given to \opt{endrange} they are considered as label properties, as
+long as they are declared. This property is used to typeset the end of range
+reference if the label contains it, and if both references would be
+``compressible'' according to the \opt{comp} option, otherwise the property
+specified by the \opt{ref} option is used. This is useful for things like
+sub-elements for which we can build a proper abbreviated sub-reference and
+populate the label with it (some compatibility modules already provide a
+number of such properties, but other ones can be built with \pkg{zref}, as
+needed).
+
\DescribeOption{range} %
+\DescribeOption{rangetopair} %
By default (that is, when the \opt{range} option is not given), \cs{zcref}
typesets a complete list of references according to the \meta{labels} it
received as argument, and only compresses some of them into ranges if the
@@ -510,12 +551,14 @@ immediate sequence. The \opt{range} option makes \cs{zcref} behave
differently. Sorting is implied by this option (the \opt{sort} option is
disregarded) and, for each reference type group in \meta{labels}, \cs{zcref}
builds a range from the first to the last reference in it, even if references
-in between do not occur in immediate sequence. \cs{zcref} is smart enough,
-though, to recognize when the first and last references of a type do happen to
-be contiguous, in which case it typesets a ``pair'', instead of a ``range''.
-It is a boolean option, and the package's default is \texttt{range=false}.
-The option given without a value is equivalent to \texttt{range=true} (in the
-\pkg{l3keys}' jargon, the \emph{option}'s default is \texttt{true}).
+in between do not occur in immediate sequence. It is a boolean option, and
+the package's default is \texttt{range=false}. The option given without a
+value is equivalent to \texttt{range=true} (in the \pkg{l3keys}' jargon, the
+\emph{option}'s default is \texttt{true}). \cs{zcref} is smart enough to
+recognize when the first and last references of a type do happen to be
+contiguous, in which case it typesets a ``pair'', instead of a ``range''. But
+this behavior can be disabled by setting the \opt{rangetopair} option to
+\texttt{false}.
\DescribeOption{cap} %
\DescribeOption{nocap} %
@@ -666,8 +709,14 @@ means this option \emph{can't} be set at load time, as a package option. If
you want to set it globally, use \cs{zcsetup} instead.
\DescribeOption{titleref} %
+\DescribeOption{vario} %
The \opt{titleref} option receives no value and, when given, loads
-\pkg{zref}'s \pkg{zref-titleref} module. This is a preamble only option.
+\pkg{zref}'s \pkg{zref-titleref} module. Similarly, the \opt{vario} option
+loads the \pkg{zref-vario} package. These are a preamble only options. Note
+that \pkg{zref-vario} loads \pkg{varioref}, which has known load order
+interaction with other packages, prominently with \pkg{hyperref}. Hence,
+depending on your document, you may wish to load \pkg{zref-vario} separately,
+instead of through the option.
\DescribeOption{note} %
The \opt{note} option receives as value some text to be typeset at the end of
@@ -847,7 +896,7 @@ the \cs{appendix}.
One more observation about ``reference types'' is due here. A \emph{type} is
not really ``defined'' in the sense a variable or a function is. It is more
-of a ``string'' which \pkg{zref-clever} uses to look for a whole set of
+of a ``name'' which \pkg{zref-clever} uses to look for a whole set of
type-specific reference format options (see \zcref{sec:reference-format}).
Each of these options individually may be ``set'' or not, ``defined'' or not.
And, depending on the setup and the relevant precedence rules for this, some
@@ -908,42 +957,44 @@ more detail soon, and lists the scopes in which each is available.
\centering
\begin{tabular}{l>{\ttfamily}lcccc}
\toprule
- & & General & Type & \multicolumn{2}{c}{Language} \\
- \cmidrule(lr){5-6}
- & & & & Type & Default \\
- & & (i) & (ii) & (iii) & (iv) \\
+ & & General & Type & \multicolumn{2}{c}{Language} \\
+ \cmidrule(lr){5-6}
+ & & & & Type & Default \\
+ & & (i) & (ii) & (iii) & (iv) \\
\midrule
- Typesetting & tpairsep & $\bullet$ & & & $\bullet$ \\
- (necessarily not & tlistsep & $\bullet$ & & & $\bullet$ \\
- type-specific) & tlastsep & $\bullet$ & & & $\bullet$ \\
- & notesep & $\bullet$ & & & $\bullet$ \\
+ Typesetting & tpairsep & $\bullet$ & & & $\bullet$ \\
+ (necessarily not & tlistsep & $\bullet$ & & & $\bullet$ \\
+ type-specific) & tlastsep & $\bullet$ & & & $\bullet$ \\
+ & notesep & $\bullet$ & & & $\bullet$ \\
\addlinespace
- Typesetting & namesep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
- (possibly & pairsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
- type-specific) & listsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
- & lastsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
- & rangesep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
- & refbounds & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ Typesetting & namesep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ (possibly & pairsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ type-specific) & listsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & lastsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & rangesep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & refbounds & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
\addlinespace
- Typesetting & Name-sg & & $\bullet$ & $\bullet$ & \\
- (necessarily & name-sg & & $\bullet$ & $\bullet$ & \\
- type-specific) & Name-pl & & $\bullet$ & $\bullet$ & \\
- & name-pl & & $\bullet$ & $\bullet$ & \\
- & Name-sg-ab & & $\bullet$ & $\bullet$ & \\
- & name-sg-ab & & $\bullet$ & $\bullet$ & \\
- & Name-pl-ab & & $\bullet$ & $\bullet$ & \\
- & name-pl-ab & & $\bullet$ & $\bullet$ & \\
+ Typesetting & Name-sg & & $\bullet$ & $\bullet$ & \\
+ (necessarily & name-sg & & $\bullet$ & $\bullet$ & \\
+ type-specific) & Name-pl & & $\bullet$ & $\bullet$ & \\
+ & name-pl & & $\bullet$ & $\bullet$ & \\
+ & Name-sg-ab & & $\bullet$ & $\bullet$ & \\
+ & name-sg-ab & & $\bullet$ & $\bullet$ & \\
+ & Name-pl-ab & & $\bullet$ & $\bullet$ & \\
+ & name-pl-ab & & $\bullet$ & $\bullet$ & \\
\addlinespace
- Font & namefont & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
- & reffont & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ Font & namefont & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & reffont & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
\addlinespace
- Other & cap & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
- & abbrev & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ Other & cap & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & abbrev & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & endrange & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
+ & rangetopair & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
\bottomrule
\end{tabular}
\caption{Reference format options and their scopes}
@@ -1490,71 +1541,40 @@ set around a cross-reference ``task'' we'd like to perform with
\pkg{zref-clever}.
-\subsection{Context sensitive page references}
+\subsection{Extended page references (\pkg{varioref})}
\zctask{Make cross-references to pages which are sensitive to the relative
- position between the reference and the label being referred to.}
-
-It is frequently useful to make a reference to both a document element and its
-page. For example:
-\begin{zcexample}
-\zcref{fig:1} on \zcpageref{fig:1}
-\end{zcexample}
-
-However, while this works well when the object and the reference are somewhat
-distant, we may want to adjust this to something different when the label and
-the reference are close to each other. If both are on the same page, we may
-want to drop the \cs{zcpageref}, or replace it with ``above'' or ``below''.
-And, if both are on contiguous pages, then something like ``on the following
-page'' or ``on the preceding page'' may be preferred. Since we don't usually
-know the relative position of the reference to the label, particularly for
-floats, making these kinds of adjustments manually is an uphill battle, and
-error prone, in the absence of some support for it.
-
-\pkg{zref-clever}'s integration with \pkg{zref-check} offers some assistance
-in making these kinds of references, by providing checks for the relation
-between the reference and the label. For example, you may use:
-\begin{zcexample}
-\zcref[check=nextpage,note={on the following page}]{fig:1}
-\end{zcexample}
-and if \texttt{fig:1} is not on the next page relative to the reference, a
-compilation warning can be issued by \pkg{zref-check} (according to the
-package's options), so that the problem can be easily identified and
-corrected. Evidently, this does not fully automate the typeset results, but
-it does automate the checking that the reference context is the intended one.
-
-And to make use of this feature, one does not need to rely on compiling the
-document, make the reference according to the current state of things, and
-then adjusting it over and over, as the document gets edited. This feature is
-best used within a certain workflow, which starts by making a standard
-reference with a page reference, but adding the \texttt{pagegap} check to it:
-\begin{zcexample}
-\zcref{fig:1} on \zcpageref[check=pagegap]{fig:1}
-\end{zcexample}
+ position between the reference and the label being referred to using
+ \pkg{varioref}.}
-During the initial editing of the document, this reference will be formally
-correct, even if less than ideal in certain cases. At a certain point, when
-you choose to give finishing touches to your document, then you can cater for
-\pkg{zref-check}'s warnings (the package has options to control them, for
-example, enabling warnings only when the \opt{draft} option is not in use).
-The \texttt{pagegap} check will pass if there's one or more pages between the
-reference and the label, in which case, that reference is already what we
-want. However, if the referenced object lies in the previous page, the same
-page, or the next page, the \texttt{pagegap} check will issue a warning. Thus
-telling us if there's an opportunity, or need, to adjust the context
-information of the reference. Then we can go with one of the below, according
-to the situation:
-\begin{zcexample}
-\zcref[check=thispage]{fig:1}
-\zcref[check=above,note={above}]{fig:1}
-\zcref[check=below,note={below}]{fig:1}
-\zcref[check=nextpage,note={on the following page}]{fig:1}
-\zcref[check=prevpage,note={on the preceding page}]{fig:1}
-\zcref[check=facing,note={on the facing page}]{fig:1}
-\end{zcexample}
+\pkg{zref-vario}, which can be enabled with package option \opt{vario}, offers
+a layer of compatibility with \pkg{varioref} and provides
+\texttt{\textbackslash{}z}\dots{} counterparts for the latter's main reference
+commands.
-See \pkg{zref-check}'s documentation for details, and further available
-checks.
+\begin{zchowto}[caption={\pkg{zref-vario}}]
+\documentclass{article}
+\usepackage[vario]{zref-clever}
+\begin{document}
+\section{Section 1}
+\zlabel{sec:section-1}
+\begin{figure}
+ A figure.
+ \caption{Figure 1}
+ \zlabel{fig:figure-1}
+\end{figure}
+\begin{figure}
+ Another figure.
+ \caption{Figure 2}
+ \zlabel{fig:figure-2}
+\end{figure}
+\zvref[S]{sec:section-1}
+\zvpageref{fig:figure-1}
+\zvrefrange{fig:figure-1}{fig:figure-2}
+\zvpagerefrange{fig:figure-1}{fig:figure-2}
+\zfullref{fig:figure-1}
+\end{document}
+\end{zchowto}
\subsection{\cs{newtheorem}}
@@ -2087,16 +2107,20 @@ refer to the main equation number, that is, right after
usage example. The module also ensures proper \opt{currentcounter} values are
in place for the display math environments, for which it uses environment
hooks, and sets the font of equation references to \cs{upshape}, following
-\pkg{amsmath}'s \cs{eqref}. Note, however, that \pkg{zref-clever} is not the
-only package to redefine \cs{ltx@label}, and compatibility problems may arise
-if this module is used with such packages or with document classes that do the
-same. In case of trouble, you can load \pkg{zref-clever} with option
-\texttt{nocompat=amsmath} and either use the standard referencing system's
-facilities to refer to \pkg{amsmath}'s equations or check the code
-documentation for the technique used for this (which is pretty standard) and
-adapt it to your case. Given that any trouble that may arise here is one of
-the proper ``timing'' of the redefinition, it should not be particularly
-complicated to make such adjustments.
+\pkg{amsmath}'s \cs{eqref}. Finally, the module also provides a
+\texttt{subeq} property, for display math environments used inside the
+\env{subequations} environment, which can be used to refer to them directly
+with the \opt{ref} option, or to build terse ranges with the \opt{endrange}
+option. Note that \pkg{zref-clever} is not the only package to redefine
+\cs{ltx@label}, and compatibility problems may arise if this module is used
+with such packages or with document classes that do the same. In case of
+trouble, you can load \pkg{zref-clever} with option \texttt{nocompat=amsmath}
+and either use the standard referencing system's facilities to refer to
+\pkg{amsmath}'s equations or check the code documentation for the technique
+used for this (which is pretty standard) and adapt it to your case. Given
+that any trouble that may arise here is one of the proper ``timing'' of the
+redefinition, it should not be particularly complicated to make such
+adjustments.
\DescribeOption{mathtools} %
\pkg{mathtools} has a feature to show the numbers only for those equations