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.tex166
1 files changed, 140 insertions, 26 deletions
diff --git a/macros/latex/contrib/zref-clever/zref-clever.tex b/macros/latex/contrib/zref-clever/zref-clever.tex
index 2ebf1b6739..ac47747529 100644
--- a/macros/latex/contrib/zref-clever/zref-clever.tex
+++ b/macros/latex/contrib/zref-clever/zref-clever.tex
@@ -64,6 +64,10 @@
\NewDocumentCommand\opt{m}{\texttt{#1}}
+\NewDocumentCommand\username{m}{`\texttt{#1}'}
+
+\setlength{\marginparsep}{2\labelsep}
+
\definecolor{reffmtbox}{gray}{0.15}
\definecolor{reffmtback}{gray}{0.85}
\NewDocumentCommand\reffmt{m}{%
@@ -96,6 +100,17 @@
text,
lstset,
condition,
+ RenewDocumentCommand,
+ NewCommandCopy,
+ ltx@gobble,
+ zref@label,
+ zref@wrapper@babel,
+ zref@ifpropundefined,
+ zref@setcurrent,
+ beamer@old@zref@label,
+ alt,
+ beamer@nameslide,
+ beamer@dummynameslide,
}
}
\lstdefinestyle{zrefclever}{
@@ -380,6 +395,12 @@ available at \zcref{sec:how-tos}.
The package does not accept load-time options, package options must be set
using \cs{zcsetup} (see \zcref{sec:user-interface}).
+\pkg{zref-clever} requires a recent \LaTeX{} kernel (2021-11-15 or newer) and
+the packages \pkg{zref}, including some of its modules, and \pkg{ifdraft}. It
+also requires UTF-8 input encoding, which has been the kernel's default for
+some time.
+
+
\section{Dependencies}
\pkg{zref-clever} requires \pkg{zref}, and \LaTeX{} kernel 2021-11-15, or
@@ -774,10 +795,7 @@ appearance of the whole reference list (see also the \opt{namefont} and
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
-that may generate typeset output, is not supported. Given how package options
-are handled by \LaTeX{}, the fact that this option receives commands as value
-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.
+that may generate typeset output, is not supported.
\DescribeOption{note} %
The \opt{note} option receives as value some text to be typeset at the end of
@@ -1246,8 +1264,8 @@ ones, and ``\texttt{last}'' to the last reference of the type-block. Less
obviously, but hopefully still mnemonic enough, ``\texttt{sg}'' stands for
``single'', ``\texttt{pb}'' and ``\texttt{pe}'' for ``pair begin'' and ``pair
end'', and finally ``\texttt{rb}'' and ``\texttt{re}'' for ``range begin'' and
-``range end''. Each of them which receives as value a comma separated list of
-four items in the form \texttt{\{preref*,preref,postref,postref*\}}, just like
+``range end''. Each of them receives as value a comma separated list of four
+items in the form \texttt{\{preref*,preref,postref,postref*\}}, just like
\opt{refbounds}.
The base options are mutually exclusive, which means, for example, that it is
@@ -1258,13 +1276,12 @@ beginning of a range. Setting a group of them is the purpose of the derived
options. Each of these sets all options under it. Some examples.
\opt{+refbounds-first} sets \opt{refbounds-first}, \opt{refbounds-first-sg},
\opt{refbounds-first-pb}, and \opt{refbounds-first-rg}. In turn,
-\opt{+refbounds-first-rb} sets \opt{refbounds-first-rb} and
-\opt{refbounds-first-rb}. And quite conveniently, \opt{+refbounds} sets
-\opt{+refbounds-first}, \opt{+refbounds-mid}, and \opt{+refbounds-last}, it is
-hence sufficient to set it to define the behavior of what is typeset around
-all references for the whole type-block. As you probably guessed by now, the
-\opt{refbounds} option presented in \zcref{tab:reference-format} is an alias
-of \opt{+refbounds}.
+\opt{+refbounds-rb} sets \opt{refbounds-first-rb} and \opt{refbounds-mid-rb}.
+And quite conveniently, \opt{+refbounds} sets \opt{+refbounds-first},
+\opt{+refbounds-mid}, and \opt{+refbounds-last}, it is hence sufficient to set
+it to define the behavior of what is typeset around all references for the
+whole type-block. As you probably guessed by now, the \opt{refbounds} option
+presented in \zcref{tab:reference-format} is an alias of \opt{+refbounds}.
Given that base and derived options are actually setting the same group of
underlying options (the base ones), the order in which they are given is
@@ -1318,6 +1335,7 @@ indeed required, without users having to worry about it at all.
\toprule
Language & Aliases \\
\midrule
+ dutch & \\
english & american \\
& australian \\
& british \\
@@ -1326,9 +1344,7 @@ indeed required, without users having to worry about it at all.
& UKenglish \\
& USenglish \\
french & acadian \\
- & canadien \\
- & francais \\
- & frenchb \\
+ & \\
\bottomrule
\end{tabular}
\quad
@@ -1336,17 +1352,16 @@ indeed required, without users having to worry about it at all.
\toprule
Language & Aliases \\
\midrule
- german & austrian \\
- & germanb \\
- & ngerman \\
+ german & ngerman \\
+ & austrian \\
& naustrian \\
- & nswissgerman \\
& swissgerman \\
+ & nswissgerman \\
+ italian & \\
portuguese & brazilian \\
& brazil \\
& portuges \\
spanish & \\
- dutch & \\
\bottomrule
\end{tabular}
\caption{Declared languages and aliases}
@@ -1395,12 +1410,13 @@ in effect for the languages declared by \pkg{zref-clever}.
\toprule
Language & declension & gender & allcaps \\
\midrule
+ dutch & -- & f,m,n & -- \\
english & -- & -- & -- \\
french & -- & f,m & -- \\
german & N,A,D,G & f,m,n & yes \\
+ italian & -- & f,m & -- \\
portuguese & -- & f,m & -- \\
spanish & -- & f,m & -- \\
- dutch & -- & f,m,n & -- \\
\bottomrule
\end{tabular}
\caption{Options for declared languages}
@@ -2315,6 +2331,99 @@ Of course, you can always adapt things to your needs and, e.g., make the
separate \opt{zlabel} option.
+\subsection*{\cls{beamer}}
+
+\cls{beamer} does some really atypical things with regard to cross-references.
+To start with, it redefines \cs{label} to receive an optional
+\texttt{<\meta{overlay specification}>} argument. Then, presumably to support
+overlays, it goes on and hijacks \pkg{hyperref}'s anchoring system, sets
+anchors (\cs{hypertarget}s) to each \emph{label} in the \file{.snm} file,
+while letting every standard label's anchor in the \file{.aux} file default to
+\texttt{Doc-Start}. Of course, having rendered useless \pkg{hyperref}'s
+anchoring, it has to redefine \cs{ref} so that it uses its own \file{.snm}
+provided ``label anchors'' to make hyperlinks. In particular, from our
+perspective, there is no support at all for \pkg{zref} provided by
+\cls{beamer}. Which is specially unfortunate since the above procedures also
+appear to break \pkg{cleveref}.\footnote{See, for example,
+ \url{https://tex.stackexchange.com/q/266080},
+ \url{https://tex.stackexchange.com/q/668998}, and
+ \url{https://github.com/josephwright/beamer/issues/750}. The workaround
+ provided at \url{https://tex.stackexchange.com/a/266109} is not general
+ enough since it breaks \pkg{cleveref}'s ability to receive a list of labels
+ as argument.}
+
+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
+meantime.
+
+\begin{zcworkaround}[caption={\cls{beamer}}]
+\documentclass{beamer}
+\usepackage{zref-clever}
+\makeatletter
+\RenewDocumentCommand{\zlabel}{ D<>{1} m }{%
+ \ifx\label\ltx@gobble
+ \else
+ \zref@wrapper@babel{\zref@label<#1>}{#2}%
+ \fi
+}
+\NewCommandCopy\beamer@old@zref@label\zref@label
+\RenewDocumentCommand{\zref@label}{ D<>{1} m }{%
+ \alt<#1>{%
+ \zref@ifpropundefined{anchor}{}{\zref@setcurrent{anchor}{#2}}%
+ \beamer@old@zref@label{#2}%
+ \beamer@nameslide{#2}%
+ }{%
+ \beamer@dummynameslide%
+ }%
+}
+\makeatother
+\begin{document}
+\begin{frame}
+ \begin{table}
+ \begin{tabular}{cc}
+ 1 & 2 \\
+ 3 & 4 \\
+ \end{tabular}
+ \caption{Table 1}
+ \zlabel{tab:1}
+ \end{table}
+\end{frame}
+\begin{frame}
+ \begin{figure}
+ \rule{5cm}{5cm}
+ \caption{Figure 1}
+ \zlabel{fig:1}
+ \end{figure}
+\end{frame}
+\begin{frame}
+ \zcref{tab:1,fig:1}
+\end{frame}
+\end{document}
+\end{zcworkaround}
+
+This work-around redefines \cs{zlabel} so that it takes an overlay
+specification argument, and provides that the work done by \cls{beamer} for
+the standard \cs{label} is also done for it. And it works by setting the
+\texttt{anchor} to the \emph{label} so as to be able to speak the
+``\cls{beamer}-lingo'' of anchors.
+
+A couple of caveats though. First, there's probably still some work to be
+done there in defining and setting reference types for \cls{beamer} specific
+document objects, e.g. overlays. But it can be done by the standard user
+interface of \pkg{zref-clever}. Second, since \cls{beamer}'s anchoring system
+does not provide for uniqueness of anchors as \pkg{hyperref} does, the
+procedure used by \pkg{zref-clever} in its \opt{amsmath} compatibility module
+of setting both \cs{label} and \cs{zlabel} in \pkg{amsmath}'s display math
+environments will result in duplicate anchors for labels set in them, with
+corresponding \pkg{hyperref} warnings of ``destination with the same
+identifier has been already used, duplicate ignored''. The warning is
+actually harmless in this case, since both labels are set in the same place,
+and thus have identical anchors. But, if it bothers you enough, you can look
+at the \opt{amsmath} compatibility module in the code documentation, and
+adjust things so that it sets only a \cs{zlabel}.
+
+
\section{Acknowledgments}
\pkg{zref-clever} would not be possible without other people's previous work
@@ -2374,9 +2483,11 @@ were generously provided by (in chronological order):
% 2021-10-10: https://tex.stackexchange.com/questions/618434/#comment1544401_618439
% 2022-01-12: https://chat.stackexchange.com/transcript/message/60129096#60129096
% and following discussion.
+ % 2022-12-26: https://chat.stackexchange.com/transcript/message/62644791#62644791
+ % and following discussion.
Frank Mittelbach,
% 2021-10-14: https://github.com/latex3/latex2e/issues/687
- `\texttt{samcarter}',
+ \username{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,
@@ -2391,17 +2502,20 @@ 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 `\texttt{niluxv}'.
+ and \username{niluxv}.
% 2022-01-05: https://github.com/gusbrs/zref-clever/issues/4
- % 2022-01-05: https://github.com/gusbrs/zref-clever/pull/5
The package's language files have been provided or improved thanks to:
Denis Bitouzé (French),
% 2021-11-25: https://github.com/gusbrs/zref-clever/issues/1
François Lagarde (French), % 'flagarde'
% 2021-12-09: discussion at https://github.com/gusbrs/zref-clever/issues/1
- and `\texttt{niluxv}' (Dutch).
+ \username{niluxv} (Dutch),
% 2022-01-09: https://github.com/gusbrs/zref-clever/pull/5
+ % 2022-12-27: https://github.com/gusbrs/zref-clever/pull/12
+ % 2022-12-27: https://github.com/gusbrs/zref-clever/pull/13
+ and Matteo Ferrigato (Italian). % 'matteo339'
+ % 2022-12-12: https://github.com/gusbrs/zref-clever/issues/11
If I have inadvertently left anyone off the list I apologize, and please let
me know, so that I can correct the oversight.