diff options
Diffstat (limited to 'macros/latex/contrib/zref-clever/zref-clever.tex')
-rw-r--r-- | macros/latex/contrib/zref-clever/zref-clever.tex | 166 |
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. |