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.tex130
1 files changed, 110 insertions, 20 deletions
diff --git a/macros/latex/contrib/zref-clever/zref-clever.tex b/macros/latex/contrib/zref-clever/zref-clever.tex
index ac47747529..78d6cc7f03 100644
--- a/macros/latex/contrib/zref-clever/zref-clever.tex
+++ b/macros/latex/contrib/zref-clever/zref-clever.tex
@@ -4,7 +4,7 @@
%
% This file is part of the LaTeX package "zref-clever".
%
-% Copyright (C) 2021-2022 Gustavo Barros
+% Copyright (C) 2021-2023 Gustavo Barros
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -103,14 +103,18 @@
RenewDocumentCommand,
NewCommandCopy,
ltx@gobble,
+ @currentcounter,
zref@label,
zref@wrapper@babel,
zref@ifpropundefined,
zref@setcurrent,
+ zref@newprop,
+ zref@addprop,
beamer@old@zref@label,
alt,
beamer@nameslide,
beamer@dummynameslide,
+ ordinal,
}
}
\lstdefinestyle{zrefclever}{
@@ -207,7 +211,7 @@
\end{center}
\begin{quotation}
- \pkg{zref-clever} provides an user interface for making \LaTeX{}
+ \pkg{zref-clever} provides a 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
results. A reference made with \cs{zcref} includes a ``name'' according to
@@ -814,9 +818,10 @@ optional argument of \cs{zcheck}, and can receive both checks and
\zcref{sec:reference-format}).
\DescribeOption{countertype} %
+\DescribeOption{reftype} %
The \opt{countertype} option allows to specify the ``reference type'' of each
counter, which is stored as a label property when the label is set. This
-``reference type'' is what determines how a reference to this label will
+reference type is what determines how a reference to this label will
eventually be typeset when it is referred to (see
\zcref{sec:reference-types}). A value like \texttt{countertype = \{foo =
bar\}} sets the \texttt{foo} counter to use the reference type \texttt{bar}.
@@ -826,8 +831,14 @@ the same name as the counter, unless otherwise specified. Also, the default
value of the option already sets appropriate types for basic \LaTeX{}
counters, including those from the standard classes. Setting a counter type
to an empty value removes any (explicit) type association for that counter, in
-practice, this means it then uses a type equal to its name. Since this option
-only affects how labels are set, it is not available in \cs{zcref}.
+practice, this means it then uses a type equal to its name. The \opt{reftype}
+option allows one to specify the reference type manually, regardless of the
+current counter. This can be used to locally override any \opt{countertype}
+settings of the package and, for those acquainted with it, is the equivalent
+of \pkg{cleveref}'s optional argument to \cs{label}. Normally, you'd want to
+use this option within a group, but if you must do otherwise, the default
+value can be restored by setting the option without a value. Since these
+options only affect how labels are set, they are not available in \cs{zcref}.
\DescribeOption{\raisebox{-.2em}{\dbend}\ counterresetters} %
\DescribeOption{counterresetby} %
@@ -884,11 +895,12 @@ option, but a way to tell \pkg{zref-clever} a piece of information it has no
means to retrieve automatically. The setting must correspond to the actual
``current counter'', meaning here ``the counter underlying
\cs{@currentlabel}'' in a given situation. Also, when using the
-\opt{currentcounter} option, make sure the setting is duly grouped because, if
-set, it has precedence over \cs{@currentcounter} and, contrary to the later,
-the former is not reset the next time \cs{refstepcounter} runs. Its default
-value is, quite naturally, \cs{@currentcounter}. Since this option only
-affects how labels are set, it is not available in \cs{zcref}.
+\opt{currentcounter} option, take care that the setting is duly grouped
+because, if set, it has precedence over \cs{@currentcounter} and, contrary to
+the later, the former is not reset the next time \cs{refstepcounter} runs.
+Its default value is, quite naturally, \cs{@currentcounter}. The default
+value can be reset by calling the option with no value. Since this option
+only affects how labels are set, it is not available in \cs{zcref}.
\DescribeOption{nocompat} %
Some packages, document classes, or LaTeX features may require specific
@@ -997,7 +1009,7 @@ is to provide a rich set of ``handles'' for fine tuning the reference format
but, at the same time, do not \emph{require} detailed setup by the users,
unless they really want it.
-With that in mind, we have settled with an user interface for reference
+With that in mind, we have settled with a user interface for reference
formatting which allows settings to be done in different scopes, with more or
less overarching effects, and some precedence rules to regulate the relation
of settings given in each of these scopes. There are four scopes in which
@@ -1827,8 +1839,7 @@ package in the setup, the same procedure can be used with \cls{memoir}'s
\subsection{\pkg{amsmath}}
-\zctask{Make references to \pkg{amsmath} display math environments with
- \cs{zcref}.}
+\zctask{Make references to \pkg{amsmath} display math environments.}
Given how \pkg{amsmath}'s display math environments work, they need to handle
\cs{label} specially, and this support is quite hard-wired into the
@@ -1867,10 +1878,48 @@ description of the \opt{amsmath} compatibility module at
\end{zchowto}
+\subsection{Overriding the reference type}
+
+\zctask{Make references to a system of equations, which should be referred to
+ in the plural.}
+
+Though, usually, setting the \opt{countertype} option may provide a more
+general and convenient way to set the reference type of a given counter,
+sometimes we just need to do it for a particular label or set of labels. The
+\opt{reftype} option allows us to do so and set the reference type directly,
+regardless of what the current counter is.
+
+\begin{zchowto}[caption={Overriding the reference type}]
+\documentclass{article}
+\usepackage{amsmath}
+\usepackage{zref-clever}
+\usepackage{hyperref}
+\zcRefTypeSetup{pluralequation}{
+ Name-sg = Equations ,
+ name-sg = equations ,
+ Name-pl = Equations ,
+ name-pl = equations ,
+}
+\begin{document}
+\section{Section 1}
+\begin{equation}
+ \zcsetup{reftype=pluralequation}
+ \zlabel{eq:1}
+ \begin{aligned}
+ A+B&=B+A\\
+ C&=D+E\\
+ E&=F
+ \end{aligned}
+\end{equation}
+\zcref{eq:1}
+\end{document}
+\end{zchowto}
+
+
\subsection{\pkg{listings}}
\zctask{Make references to a \env{lstlisting} environment from the
- \pkg{listings} package with \cs{zcref}.}
+ \pkg{listings} package.}
Being \env{lstlisting} a verbatim environment, setting labels inside it
requires special treatment. \pkg{zref-clever}'s \opt{listings} compatibility
@@ -1904,7 +1953,7 @@ description of the \opt{listings} compatibility module at
\subsection{\pkg{enumitem}}
\zctask{Setup a custom enumerate environment created with \pkg{enumitem} to be
- referred to with \cs{zcref}.}
+ referred to.}
Since the \texttt{enumerate} environment's counters are reset at each nesting
level, but not with the standard machinery, we have to inform
@@ -1956,8 +2005,7 @@ implicit counter-type association, and have to set it explicitly with the
\subsection{\pkg{zref-xr}}
-\zctask{Make references to labels set in an external document with
- \cs{zcref}.}
+\zctask{Make references to labels set in an external document.}
\pkg{zref} itself offers this functionality with module \pkg{zref-xr}, and
\pkg{zref-clever} is prepared to make use of it. Just a couple of details
@@ -2002,6 +2050,42 @@ be the following.
\end{document}
\end{zchowto}
+
+\subsection{Ordinal references}
+
+\zctask{Typesetting the references as ordinal numbers.}
+
+This example is intended as an illustration of the flexibility \pkg{zref}'s
+extensible referencing system grants us.\footnote{Though clearly simplified,
+ the example is less than academic.
+ See \url{https://tex.stackexchange.com/a/670088} for an application to add a
+ reference suffix needed in Turkish.} Getting references as ordinal numbers,
+something that would be normally a tricky task, can be handled with a simple
+custom \pkg{zref} property, which we then use to set \pkg{zref-clever}'s
+\opt{ref} option.
+
+\begin{zchowto}[caption={Ordinal references}]
+\documentclass{article}
+\usepackage{zref-clever}
+\usepackage{fmtcount}
+\makeatletter
+\zref@newprop{ordref}{\ordinal{\@currentcounter}}
+\zref@addprop{main}{ordref}
+\makeatother
+\zcsetup{ref=ordref}
+\begin{document}
+\section{Section 1}
+\zlabel{sec:section-1}
+\begin{figure}
+A figure.
+\caption{Figure 1}
+\zlabel{fig:figure-1}
+\end{figure}
+\zcref{sec:section-1,fig:figure-1}
+\end{document}
+\end{zchowto}
+
+
\section{Limitations}
\zlabel{sec:limitations}
@@ -2354,7 +2438,7 @@ appear to break \pkg{cleveref}.\footnote{See, for example,
Adding proper support for this is the business of \cls{beamer}, \pkg{zref},
and/or \pkg{hyperref}. Likely the former's really. But, taking advantage of
-\pkg{zref}'s flexibility, as an user, you can have a work-around in the
+\pkg{zref}'s flexibility, as a user, you can have a work-around in the
meantime.
\begin{zcworkaround}[caption={\cls{beamer}}]
@@ -2437,7 +2521,7 @@ will remain one of the main assets of \pkg{zref-clever} as it matures.
The name of the package makes no secret that a major inspiration for the kind
of ``feel'' I strove to achieve has been Toby Cubitt's \pkg{cleveref}.
-Indeed, I have been an user of \pkg{cleveref} for several years, and a happy
+Indeed, I have been a user of \pkg{cleveref} for several years, and a happy
one at that. But the role \pkg{cleveref} played in the development of
\pkg{zref-clever} extends beyond the visible influence in the design of user
facing functionality. Some technical solutions and, specially, the handling
@@ -2464,6 +2548,7 @@ were generously provided by (in chronological order):
% 2021-10-26: https://github.com/latex3/latex2e/issues/687
% 2022-01-12: https://chat.stackexchange.com/transcript/message/60129233#60129233
% 2022-04-09: https://github.com/latex3/hyperref/issues/229#issuecomment-1093870142
+ % 2023-01-02: https://tex.stackexchange.com/q/670399 (comments)
Phelype Oleinik,
% 2021-08-20: https://tex.stackexchange.com/q/611370 (comments)
% 2021-09-09: https://tex.stackexchange.com/a/614704
@@ -2485,6 +2570,8 @@ were generously provided by (in chronological order):
% and following discussion.
% 2022-12-26: https://chat.stackexchange.com/transcript/message/62644791#62644791
% and following discussion.
+ % 2023-01-02: https://chat.stackexchange.com/transcript/message/62684358#62684358
+ % and following discussion.
Frank Mittelbach,
% 2021-10-14: https://github.com/latex3/latex2e/issues/687
\username{samcarter},
@@ -2502,8 +2589,11 @@ were generously provided by (in chronological order):
% 2021-11-26: https://github.com/latex3/l3build/issues/215
Jürgen Spitzmüller,
% 2021-11-28: https://github.com/gusbrs/zref-clever/issues/2
- and \username{niluxv}.
+ \username{niluxv},
% 2022-01-05: https://github.com/gusbrs/zref-clever/issues/4
+ and Joseph Wright.
+ % 2023-01-02: https://chat.stackexchange.com/transcript/message/62684358#62684358
+ % and following discussion.
The package's language files have been provided or improved thanks to:
Denis Bitouzé (French),