summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/zref-clever/zref-clever.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/zref-clever/zref-clever.tex')
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever.tex246
1 files changed, 161 insertions, 85 deletions
diff --git a/macros/latex/contrib/zref-clever/zref-clever.tex b/macros/latex/contrib/zref-clever/zref-clever.tex
index c2fa9f19b2..4da3b2453d 100644
--- a/macros/latex/contrib/zref-clever/zref-clever.tex
+++ b/macros/latex/contrib/zref-clever/zref-clever.tex
@@ -24,7 +24,7 @@
% zref-clever.ins,
% zref-clever.tex,
% zref-clever-code.tex,
-% and the derived files listed in MANIFEST.md.
+% and the files listed in MANIFEST.md.
%
% The released version of this package is available from CTAN.
%
@@ -56,6 +56,8 @@
\usepackage{listings}
\usepackage{microtype}
+% TEMP work-around for https://github.com/schlcht/microtype/issues/4
+\microtypesetup{nopatch=item}
\hypersetup{hidelinks}
@@ -120,12 +122,14 @@
\newcounter{zchowto}
\lstnewenvironment{zchowto}[1][]{%
\renewcommand{\lstlistingname}{How-to}%
+ \renewcommand*\theHlstlisting{ht.\thelstlisting}%
\lstset{#1}%
\setcounter{lstlisting}{\value{zchowto}}%
}{}
\newcounter{zcworkaround}
\lstnewenvironment{zcworkaround}[1][]{%
\renewcommand{\lstlistingname}{Work-around}%
+ \renewcommand*\theHlstlisting{wa.\thelstlisting}%
\lstset{#1}%
\setcounter{lstlisting}{\value{zcworkaround}}%
}{}
@@ -163,6 +167,9 @@
\title{%
The \pkg{zref-clever} package%
\thanks{This file describes \fileversion, released \filedate.}%
+ \texorpdfstring{\\{}\medskip{}}{ - }%
+ User manual%
+ \texorpdfstring{\medskip{}}{}%
}
\author{%
@@ -174,7 +181,11 @@
\maketitle
-\begin{abstract}
+\begin{center}
+ {\bfseries \abstractname\vspace{-.5em}\vspace{0pt}}
+\end{center}
+
+\begin{quotation}
\pkg{zref-clever} provides an user interface for making \LaTeX{}
cross-references which automates some of their typical features, thus easing
their input in the document and improving the consistency of typeset
@@ -183,17 +194,22 @@
compressed into ranges when due. The reference format is highly and easily
customizable, both globally and locally. \pkg{zref-clever} is based on
\pkg{zref}'s extensible referencing system.
-\end{abstract}
+\end{quotation}
+
+\bigskip{}
\begin{center}
- \small
\textbf{EXPERIMENTAL}
Please read \zcref{sec:warning} carefully.
\end{center}
+\clearpage{}
+
\tableofcontents
+\clearpage{}
+
\section{Introduction}
Cross-referencing is an area which lends itself quite naturally to automation.
@@ -237,12 +253,11 @@ carried over to \pkg{zref}, neither by the \pkg{zref} itself nor by other
packages.
\pkg{zref-clever} tries to cover this gap, by bringing a number of existing
-features available for the standard referencing system to \pkg{zref}, and
-hopefully making \pkg{zref} more accessible, and interesting, to the average
-user. And the package's name makes it clear that the core of the envisaged
-feature set is that of \pkg{cleveref}, even though the attempt was less one of
-replicating functionality per se than that of having it as a successful point
-of reference, from where we could then try to tap into \pkg{zref}'s potential.
+features available for the standard referencing system to \pkg{zref}. And the
+package's name makes it clear that the core of the envisaged feature set is
+that of \pkg{cleveref}, even though the attempt was less one of replicating
+functionality per se than that of having it as a successful point of
+reference, from where we could then try to tap into \pkg{zref}'s potential.
Indeed, although there is a significant intersection, the features of
\pkg{zref-clever} are neither a superset nor a subset of those of
\pkg{cleveref}. There are things either of them can do that the other can't.
@@ -254,16 +269,16 @@ 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, akin to those of \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
-limitations, of course (see \zcref{sec:limitations}). Still, all in all,
-hopefully \pkg{zref-clever} can be the missing piece for \pkg{zref} to fulfill
-the promise insinuated by the ``z'' in its name, and be your ``last ref''.
+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.
-\subsection{Warning}
+\section{Warning}
\zlabel{sec:warning}
This package is in its early days, and should be considered experimental. By
@@ -289,7 +304,7 @@ As usual:
\end{zcexample}
-\subsection{Dependencies}
+\section{Dependencies}
\pkg{zref-clever} requires \pkg{zref}, and \LaTeX{} kernel 2021-11-15, or
newer. It also needs \pkg{l3keys2e} and \pkg{ifdraft}. Some packages are
@@ -341,9 +356,9 @@ effects if ungrouped, e.g.\ in the preamble.
\cs{zcRefTypeSetup}\marg{type}\marg{options}
\end{syntax}
\end{function}
-Sets type-specific reference format options (see \zcref{sec:ref-format-opts}).
-Just as for \cs{zcsetup}, the settings performed by \cs{zcRefTypeSetup} are
-local, within the current group.
+Sets type-specific reference format options (see
+\zcref{sec:reference-format}). Just as for \cs{zcsetup}, the settings
+performed by \cs{zcRefTypeSetup} are local, within the current group.
\bigskip{}
@@ -355,12 +370,20 @@ of arguments by it and/or processing by \pkg{l3keys}, particularly with regard
to brace-stripping and space-trimming.
Furthermore, \pkg{zref-clever} loads \pkg{zref}'s \pkg{zref-user} module by
-default. So you also have its user commands available out of the box, notably
-\cs{zlabel}, but also \cs{zref} and \cs{zpageref} themselves.
+default. So you also have its user commands available out of the box,
+including \cs{zref} and \cs{zpageref}, but notably:
+\begin{function}{\zlabel}
+ \begin{syntax}
+ \cs{zlabel}\marg{label}
+ \end{syntax}
+\end{function}
+Sets \meta{label} for referencing with \cs{zref} and, thus, also \cs{zcref}.
+\cs{zlabel} is provided by \pkg{zref-user} and is the counterpart of
+\cs{label} for \pkg{zref}'s referencing system.
-\subsection{Options}
+\section{Options}
\zlabel{sec:options}
\pkg{zref-clever} is highly configurable, offering a lot of flexibility in
@@ -376,7 +399,7 @@ as a whole; and ``reference format options'', which control the detail of
reference formatting, including type-specific and language-specific settings.
This section covers the first group (for the second one, see
-\zcref{sec:ref-format-opts}). General options can be set globally either as
+\zcref{sec:reference-format}). General options can be set globally either as
package options at load-time (see \zcref{sec:loading-package}) or by means of
\cs{zcsetup} in the preamble (see \zcref{sec:user-interface}). They can also
be set locally with \cs{zcsetup} along the document or through the optional
@@ -570,7 +593,7 @@ equivalent to \texttt{nameinlink=true}.
\DescribeOption{preposinlink} %
The \opt{preposinlink} option controls whether the \opt{refpre} and
-\opt{refpos} reference format options (see \zcref{sec:ref-format-opts}) are
+\opt{refpos} reference format options (see \zcref{sec:reference-format}) are
included in the reference hyperlink or not. It is a boolean option. The
package's default is \texttt{preposinlink=false}, and the option given without
a value is equivalent to \texttt{preposinlink=true}.
@@ -578,7 +601,7 @@ a value is equivalent to \texttt{preposinlink=true}.
\DescribeOption{lang} %
The \opt{lang} option controls the language used by \cs{zcref} when looking
for language-specific reference format options (see
-\zcref{sec:ref-format-opts}). The default value, \texttt{current}, uses the
+\zcref{sec:reference-format}). The default value, \texttt{current}, uses the
current language, as defined by \pkg{babel} or \pkg{polyglossia} (or
\texttt{english} if none of them is loaded). Value \texttt{main} uses the
main document language, as defined by \pkg{babel} or \pkg{polyglossia} (or
@@ -620,8 +643,8 @@ is equivalent to \texttt{nudge=true} and the package's default is
a comma separated list of elements, and recognizes values \texttt{multitype},
\texttt{comptosing}, \texttt{gender}, and \texttt{all}. The
\texttt{multitype} nudge warns when the reference is composed by multiple type
-blocks (see \zcref{sec:ref-format-opts}). The \texttt{comptosing} nudge let's
-you know when multiple labels of the same type have been compressed to a
+blocks (see \zcref{sec:reference-format}). The \texttt{comptosing} nudge
+let's you know when multiple labels of the same type have been compressed to a
singular type name form. It can be combined with the \opt{sg} option, which
is the way to tell \cs{zcref} you know it's a singular and so not to nudge if
a compression to singular occurs, but to nudge if the contrary occurs, that
@@ -640,7 +663,7 @@ the ``nudging'' feature.
\DescribeOption{font} %
The \opt{font} option can receive font styling commands to change the
appearance of the whole reference list (see also the \opt{namefont} and
-\opt{reffont} reference format options in \zcref{sec:ref-format-opts}). It
+\opt{reffont} reference format options in \zcref{sec:reference-format}). It
does not affect the content of the \opt{note}, however. The option is
intended exclusively for commands that only change font attributes: style,
family, shape, weight, size, color, etc. Anything else, particularly commands
@@ -656,7 +679,7 @@ The \opt{titleref} option receives no value and, when given, loads
\DescribeOption{note} %
The \opt{note} option receives as value some text to be typeset at the end of
the whole reference list. It is separated from it by \opt{notesep} (see
-\zcref{sec:ref-format-opts}).
+\zcref{sec:reference-format}).
\DescribeOption{check} %
Provides integration of \pkg{zref-clever} with the \pkg{zref-check} package.
@@ -667,7 +690,7 @@ both checks and \cs{zcheck}'s options. And the checks are performed for each
label in \marg{labels} received as argument by \cs{zcref}. See the User
manual of \pkg{zref-check} for details. The checks done by the \opt{check}
option in \cs{zcref} comprise the complete reference, including the \opt{note}
-(see \zcref{sec:ref-format-opts}). If \pkg{zref-check} was not loaded in the
+(see \zcref{sec:reference-format}). If \pkg{zref-check} was not loaded in the
preamble, at begin document the option is made no-op and issues a warning.
\DescribeOption{countertype} %
@@ -763,10 +786,8 @@ available modules and details about each of them, see
\opt{nocompat} without a value (or an empty one). This is a preamble only
option.
-\section{Reference format}
-\zlabel{sec:reference-format}
-\subsection{Reference types}
+\section{Reference types}
\zlabel{sec:reference-types}
A ``reference type'' is the basic \pkg{zref-clever} setup unit for specifying
@@ -834,7 +855,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
-type-specific reference format options (see \zcref{sec:ref-format-opts}).
+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
of them may be required and some not. In practice, \pkg{zref-clever} uses the
@@ -842,8 +863,8 @@ of them may be required and some not. In practice, \pkg{zref-clever} uses the
compilation warning when it cannot find a suitable value.
-\subsection{Reference format options}
-\zlabel{sec:ref-format-opts}
+\section{Reference format}
+\zlabel{sec:reference-format}
Formatting how the reference is to be typeset is, quite naturally, a big part
of the user interface of \pkg{zref-clever}. In this area, we tried to balance
@@ -1070,7 +1091,7 @@ of these language packages, or to a language specified directly by the user.
This is primarily relevant for reference format options, particularly
reference type \emph{names} (though not only, since most reference format
options can have language-specific values, or ``translations'', see
-\zcref{sec:ref-format-opts}). But other features of the package also cater
+\zcref{sec:reference-format}). But other features of the package also cater
for language specific needs.
As far as language selection is concerned, if the language is declared and
@@ -1211,7 +1232,7 @@ the user. \cs{zcDeclareLanguageAlias} is preamble only.
\end{syntax}
\end{function}
Sets language-specific reference format options for \meta{language} (see
-\zcref{sec:ref-format-opts}), be they type-specific or not. \meta{language}
+\zcref{sec:reference-format}), be they type-specific or not. \meta{language}
must be already known to \pkg{zref-clever}. Besides reference format options,
\cs{zcLanguageSetup} knows three other keys: \opt{type}, \opt{case}, and
\opt{gender}. The first two work like a ``switch'' affecting the options
@@ -1226,7 +1247,7 @@ For \opt{case} this means the default declension case, which is the first
element of the list provided to the \opt{declension} option in
\cs{zcDeclareLanguage}. For \opt{type} this means ``default translations'',
which are language-specific but not type-specific option values (see
-\zcref{sec:ref-format-opts}). An empty valued \texttt{type=} key can also
+\zcref{sec:reference-format}). An empty valued \texttt{type=} key can also
``unset'' the type. The \opt{gender} key sets the gender of the current
\texttt{type} (provided the value it receives is one of the declared genders
for \meta{language}). \cs{zcLanguageSetup} is preamble only.
@@ -1384,49 +1405,68 @@ set around a cross-reference ``task'' we'd like to perform with
\subsection{Context sensitive references}
\zctask{Make cross-references which are sensitive to the relative position
- between the reference and the label being referred to, à la \pkg{varioref}.}
-
-\pkg{varioref}'s \cs{vref} provides for varied references for three different
-basic cases: when the reference and the label are on the same page, it
-typesets a plain reference; when the reference and the label are in contiguous
-pages (next, previous, or facing), it typesets the reference and a fixed
-string corresponding to the relative position; when the reference and the
-label are in different non-contiguous pages, it typesets a regular reference
-and a page reference. The same end result, but with a different user
-interface concept can be achieved through \pkg{zref-clever}'s integration with
-\pkg{zref-check}. For this, the later must be loaded, which can be most
-conveniently done with the \opt{check} option in the preamble. With that in
-place, the different cases could be covered by the following examples:
+ 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=thispage]{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}
+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 one such reference according to the current state of things,
+and then adjusting them over and over, as the document gets edited. This
+feature is best used within a certain workflow, which starts by making a
+standard reference, but adding the \texttt{pagegap} check to it:
+\begin{zcexample}
\zcref[check=pagegap]{fig:1} on \zcpageref{fig:1}
\end{zcexample}
-And, similarly for the cases of \cs{vpageref}:
-
+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[noref,check=thispage,note={on this page}]{fig:1}
-\zcref[noref,check=nextpage,note={on the following page}]{fig:1}
-\zcref[noref,check=prevpage,note={on the preceding page}]{fig:1}
-\zcref[noref,check=facing,note={on the facing page}]{fig:1}
-\zcref[noref,check=pagegap]{fig:1} on \zcpageref{fig:1}
+\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}
-Since \cs{zcref} can receive multiple labels, and make ranges out of them, it
-is not difficult to extend these examples to the functionality of
-\cs{vrefrange} and \cs{vpagerefrange}.
-
-Evidently, this does not fully automate the typeset results, but it does
-automate the checking that the reference context is the intended one. If the
-relation between the reference and the label does not correspond to the
-specified one, a compilation warning is issued (according to the options given
-to \pkg{zref-check}), so that the problem can be easily identified and
-corrected. See \pkg{zref-check}'s documentation for details, and further
-available checks.
+See \pkg{zref-check}'s documentation for details, and further available
+checks.
\subsection{\cs{newtheorem}}
@@ -1783,10 +1823,7 @@ be the following.
\end{document}
\end{zchowto}
-\section{Compatibility}
-\zlabel{sec:compatibility}
-
-\subsection{Limitations}
+\section{Limitations}
\zlabel{sec:limitations}
Being based on \pkg{zref} entails one quite sizable advantage for
@@ -1852,7 +1889,7 @@ whether \pkg{zref-clever} is able to provide some specific support when a
reasonable way to do so is within reach.
-\subsection{Compatibility modules}
+\section{Compatibility modules}
\zlabel{sec:comp-modules}
This section gives a description of each compatibility module provided by
@@ -2043,7 +2080,7 @@ This module just sets appropriate \opt{countertype} and \opt{counterresetby}
for the \texttt{subfigure} and \texttt{subtable} counters.
-\subsection{Work-arounds}
+\section{Work-arounds}
\marginpar{\raggedleft\raisebox{-1.5ex}{\dbend}}As should be clear by now, the
use of \pkg{zref}'s \cs{zlabel} and thus of \pkg{zref-clever} may occasionally
@@ -2142,9 +2179,48 @@ be in their absence.
Besides these more general acknowledgments, a number of people have
contributed to \pkg{zref-clever}, whether they are aware of it or not.
Suggestions, ideas, solutions to problems, bug reports or even encouragement
-were generously provided by: Ulrike Fischer, Frank Mittelbach, Phelype
-Oleinik, Jonathan P.\ Spratte, Enrico Gregorio, Steven B.\ Segletes,
-\texttt{@samcarter}, Alan Munn, Florent Rougon, and David Carlisle.
+were generously provided by (in chronological order):
+ Ulrike Fischer,
+ % 2021-07-03: It's Ulrike's fault :-) : https://tex.stackexchange.com/questions/603514/#comment1513982_603514
+ % 2021-08-20: https://tex.stackexchange.com/q/611424/105447 (comments)
+ % 2021-09-06: https://github.com/ho-tex/zref/issues/13
+ % 2021-10-26: https://github.com/latex3/latex2e/issues/687
+ Phelype Oleinik,
+ % 2021-08-20: https://tex.stackexchange.com/q/611370 (comments)
+ % 2021-09-09: https://tex.stackexchange.com/a/614704
+ % 2021-10-06: https://tex.stackexchange.com/a/617998
+ % 2021-10-21: https://github.com/latex3/latex2e/pull/699
+ Enrico Gregorio,
+ % 2021-08-20: https://tex.stackexchange.com/a/611385
+ % 2021-08-20: https://tex.stackexchange.com/q/611370/#comment1529282_611385
+ Steven B.\ Segletes,
+ % 2021-08-20: https://tex.stackexchange.com/a/611373
+ Jonathan P.\ Spratte,
+ % 2021-09-09: https://tex.stackexchange.com/a/614719
+ % 2021-09-09: https://github.com/latex3/latex3/pull/988
+ David Carlisle,
+ % 2021-10-10: https://tex.stackexchange.com/questions/618434/#comment1544401_618439
+ Frank Mittelbach,
+ % 2021-10-14: https://github.com/latex3/latex2e/issues/687
+ \texttt{@samcarter},
+ % 2021-10-14: https://chat.stackexchange.com/transcript/message/59361777#59361777
+ % 2021-10-21: https://chat.stackexchange.com/transcript/message/59418309#59418309
+ Alan Munn,
+ % 2021-10-14: https://chat.stackexchange.com/transcript/message/59364073#59364073
+ % 2021-10-21: https://chat.stackexchange.com/transcript/message/59418189#59418189
+ Florent Rougon,
+ % https://github.com/frougon/xcref has been an useful reference for
+ % declension support.
+ Denis Bitouzé,
+ % 2021-11-25: https://github.com/gusbrs/zref-clever/issues/1
+ Marcel Krüger,
+ % 2021-11-26: https://github.com/latex3/l3build/issues/215
+ and Jürgen Spitzmüller.
+ % 2021-11-28: https://github.com/gusbrs/zref-clever/issues/2
+
+The package's dictionaries have been provided or improved thanks to:
+ Denis Bitouzé (French).
+ % 2021-11-25: https://github.com/gusbrs/zref-clever/issues/1
If I have inadvertently left anyone off the list I apologize, and please let
me know, so that I can correct the oversight.