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