summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/zref-clever/zref-clever.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/zref-clever/zref-clever.dtx')
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever.dtx210
1 files changed, 53 insertions, 157 deletions
diff --git a/macros/latex/contrib/zref-clever/zref-clever.dtx b/macros/latex/contrib/zref-clever/zref-clever.dtx
index cee60860c3..fff75c1b44 100644
--- a/macros/latex/contrib/zref-clever/zref-clever.dtx
+++ b/macros/latex/contrib/zref-clever/zref-clever.dtx
@@ -22,7 +22,7 @@
%
% This work consists of the files zref-clever.dtx,
% zref-clever.ins,
-% zref-clever.tex,
+% zref-clever-doc.tex,
% zref-clever-code.tex,
% and the files generated from them.
%
@@ -131,12 +131,11 @@
%
% Taking a stance on backward compatibility of the package. During initial
% development, we have used freely recent features of the kernel (albeit
-% refraining from \pkg{l3candidates}, even though I'd have loved to have used
-% \cs{bool_case_true:}\dots{}). We presume \pkg{xparse} (which made to the
-% kernel in the 2020-10-01 release), and \pkg{expl3} as well (which made to
-% the kernel in the 2020-02-02 release). We also just use UTF-8 for the
+% refraining from \pkg{l3candidates}). We presume \pkg{xparse} (which made to
+% the kernel in the 2020-10-01 release), and \pkg{expl3} as well (which made
+% to the kernel in the 2020-02-02 release). We also just use UTF-8 for the
% language files (which became the default input encoding in the 2018-04-01
-% release). Finally, a couple of changes came with the 2021-11-15 kernel
+% release). Also, a couple of changes came with the 2021-11-15 kernel
% release, which are important here. First, a fix was made to the new hook
% management system (\pkg{ltcmdhooks}), with implications to the hook we add
% to \cs{appendix} (by \contributor{Phelype Oleinik} at
@@ -144,18 +143,23 @@
% \url{https://github.com/latex3/latex2e/pull/699}). Second, the support for
% \cs{@currentcounter} has been improved, including \cs{footnote} and
% \pkg{amsmath} (by \contributor{Frank Mittelbach} and \contributor{Ulrike
-% Fischer} at \url{https://github.com/latex3/latex2e/issues/687}). Hence,
-% since we would not be able to go much backwards without special handling
-% anyway, we make the cut at the 2021-11-15 kernel release.
+% Fischer} at \url{https://github.com/latex3/latex2e/issues/687}). Finally,
+% and critically, the new \texttt{label} hook introduced in the 2023-06-01
+% release, alongside the corresponding new hooks with arguments, just
+% simplifies and improves label setting so much, by allowing \cs{zlabel} to be
+% set with \cs{label}, that it is definitely a must for \pkg{zref-clever}, so
+% we require that too. Hence we make the cut at the 2023-06-01 kernel
+% release.
%
% \begin{macrocode}
+\NeedsTeXFormat{LaTeX2e}
\providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
-\IfFormatAtLeastTF{2021-11-15}
+\IfFormatAtLeastTF{2023-06-01}
{}
{%
\PackageError{zref-clever}{LaTeX kernel too old}
{%
- 'zref-clever' requires a LaTeX kernel 2021-11-15 or newer.%
+ 'zref-clever' requires a LaTeX kernel 2023-06-01 or newer.%
\MessageBreak Loading will abort!%
}%
\endinput
@@ -165,7 +169,7 @@
%
% Identify the package.
% \begin{macrocode}
-\ProvidesExplPackage {zref-clever} {2023-02-21} {0.3.6}
+\ProvidesExplPackage {zref-clever} {2023-06-14} {0.4.0}
{Clever LaTeX cross-references based on zref}
% \end{macrocode}
%
@@ -3927,6 +3931,36 @@
% \end{macrocode}
%
%
+% \subsubsection*{\opt{labelhook} option}
+%
+% \begin{macrocode}
+\bool_new:N \l_@@_labelhook_bool
+\keys_define:nn { zref-clever/label }
+ {
+ labelhook .bool_set:N = \l_@@_labelhook_bool ,
+ labelhook .initial:n = true ,
+ labelhook .default:n = true ,
+ }
+% \end{macrocode}
+%
+% We \emph{must} use the lower level \cs{zref@label} in this context, and
+% hence also handle protection with \cs{zref@wrapper@babel}, because
+% \cs{zlabel} makes itself no-op when \cs{label} is equal to \cs{ltx@gobble},
+% and that's precisely the case inside the \pkg{amsmath}'s \env{multline}
+% environment (and possibly elsewhere?). See
+% \url{https://tex.stackexchange.com/a/402297} and
+% \url{https://github.com/ho-tex/zref/issues/4}.
+%
+% \begin{macrocode}
+\AddToHookWithArguments { label }
+ {
+ \bool_if:NT \l_@@_labelhook_bool
+ { \zref@wrapper@babel \zref@label {#1} }
+ }
+% \end{macrocode}
+%
+%
+%
% \subsubsection*{\opt{nocompat} option}
%
%
@@ -4007,8 +4041,8 @@
%
% This is a set of options related to reference typesetting which receive
% equal treatment and, hence, are handled in batch. Since we are dealing with
-% options to be passed to \cs{zcref} or to \cs{zcsetup} or at load time, only
-% ``not necessarily type-specific'' options are pertinent here.
+% options to be passed to \cs{zcref} or to \cs{zcsetup}, only ``not
+% necessarily type-specific'' options are pertinent here.
%
%
% \begin{macrocode}
@@ -7774,39 +7808,10 @@
% related features, mostly dealing with captions, subfloats, and notes. Some
% of them are implemented in ways which make difficult the use of \pkg{zref},
% particularly \cs{zlabel}, short of redefining the whole stuff ourselves.
-% Hopefully, these features are specialized enough to make \pkg{zref-clever}
-% useful enough with \cls{memoir} without much friction, but unless some
-% support is added upstream, it is difficult not to be a little intrusive
-% here.
+% Fortunately, however, the kernel's new \texttt{label} hook, and the
+% \opt{labelhook} option, make things somewhat easier.
%
% \begin{enumerate}
-% \item Caption functionality which receives \meta{label} as optional
-% argument, namely:
-% \begin{enumerate}
-% \item The \env{sidecaption} and \env{sidecontcaption} environments. These
-% environments \emph{store} the label in an internal macro,
-% \cs{m@mscaplabel}, at the begin environment code (more precisely in
-% \cs[replace=false]{@@sidecaption}), but both the call to
-% \cs{refstepcounter} and the expansion of \cs{m@mscaplabel} take place at
-% \cs{endsidecaption}. For this reason, hooks are not particularly
-% helpful, and there is not any easy way to grab the \meta{label} argument
-% to start with. I can see two ways to deal with these environments, none
-% of which I really like. First, map through \cs{m@mscaplabel} until
-% \cs{label} is found, then grab the next token which is the \meta{label}.
-% This can be used to set a \cs{zlabel} either with a kernel environment
-% hook, or with \cs{@mem@scap@afterhook} (the former requires running
-% \cs{refstepcounter} on our own, since the \texttt{env/.../end} hook
-% comes before this is done by \cs{endsidecaption}). Second, locally
-% redefine \cs{label} to set both labels inside the environments.
-% \item The bilingual caption commands: \cs{bitwonumcaption},
-% \cs{bionenumcaption}, and \cs{bicaption}. These commands do not support
-% setting the label in their arguments (the labels do get set, but they
-% end up included in the \texttt{title} property of the label too). So we
-% do the same for them as for \env{sidecaption}, just taking care of
-% grouping, since we can't count on the convenience of the environment
-% hook (luckily for us, they are scoped themselves, so we can add an extra
-% group there).
-% \end{enumerate}
% \item The \cs{subcaptionref} command, which makes a reference to the
% subcaption without the number of the main caption (e.g. ``(b)'', instead
% of ``2.3(b)''), for labels set inside the \meta{subtitle} argument of the
@@ -7860,36 +7865,6 @@
} ,
}
% \end{macrocode}
-% Support for caption \cls{memoir} features that require that \meta{label} be
-% supplied as an optional argument.
-% \begin{macrocode}
- \cs_new_protected:Npn \@@_memoir_both_labels:
- {
- \cs_set_eq:NN \@@_memoir_orig_label:n \label
- \cs_set:Npn \@@_memoir_label_and_zlabel:n ##1
- {
- \@@_memoir_orig_label:n {##1}
- \zlabel{##1}
- }
- \cs_set_eq:NN \label \@@_memoir_label_and_zlabel:n
- }
- \AddToHook { env / sidecaption / begin }
- { \@@_memoir_both_labels: }
- \AddToHook { env / sidecontcaption / begin }
- { \@@_memoir_both_labels: }
- \AddToHook{ cmd / bitwonumcaption / before }
- { \group_begin: \@@_memoir_both_labels: }
- \AddToHook{ cmd / bitwonumcaption / after }
- { \group_end: }
- \AddToHook{ cmd / bionenumcaption / before }
- { \group_begin: \@@_memoir_both_labels: }
- \AddToHook{ cmd / bionenumcaption / after }
- { \group_end: }
- \AddToHook{ cmd / bicaption / before }
- { \group_begin: \@@_memoir_both_labels: }
- \AddToHook{ cmd / bicaption / after }
- { \group_end: }
-% \end{macrocode}
% Support for \texttt{subcaption} reference.
% \begin{macrocode}
\zref@newprop { subcaption }
@@ -7930,7 +7905,8 @@
%
% \subsection{\opt{amsmath}}
%
-% About this, see \url{https://tex.stackexchange.com/a/402297}.
+% About this, see \url{https://tex.stackexchange.com/a/402297} and
+% \url{https://github.com/ho-tex/zref/issues/4}.
%
% \begin{macrocode}
\@@_compat_module:nn { amsmath }
@@ -7938,69 +7914,6 @@
\@@_if_package_loaded:nT { amsmath }
{
% \end{macrocode}
-% First, we define a function for label setting inside \pkg{amsmath} math
-% environments, we want it to set both \cs{zlabel} and \cs{label}. We may
-% ``get a ride'', but not steal the place altogether. This makes for
-% potentially redundant labels, but seems a good compromise. We \emph{must}
-% use the lower level \cs{zref@label} in this context, and hence also handle
-% protection with \cs{zref@wrapper@babel}, because \cs{zlabel} makes itself
-% no-op when \cs{label} is equal to \cs{ltx@gobble}, and that's precisely the
-% case inside the \env{multline} environment (and, damn!, I took a beating of
-% this detail\dots{}). See also \url{https://github.com/ho-tex/zref/issues/4}
-% and \url{https://github.com/latex3/latex2e/issues/272}.
-% \begin{macrocode}
- \cs_set_nopar:Npn \@@_ltxlabel:n #1
- {
- \@@_orig_ltxlabel:n {#1}
- \zref@wrapper@babel \zref@label {#1}
- }
-% \end{macrocode}
-% Then we must store the original value of \cs{ltx@label}, which is the macro
-% actually responsible for setting the labels inside \pkg{amsmath}'s math
-% environments. And, after that, redefine it to be \cs{@@_ltxlabel:n}
-% instead. We must handle \pkg{hyperref} here, which comes very late in the
-% preamble, and which loads \pkg{nameref} at \texttt{begindocument} (though
-% this has changed recently 2022-05-16, see
-% \url{https://github.com/latex3/hyperref/commit/a011ba9308a1b047dc151796de557da0bb22abaa}),
-% which in turn, lets \cs{ltx@label} be \cs{label}. This has to come after
-% \pkg{nameref}. Other classes packages also redefine \cs{ltx@label}, which
-% may cause some trouble. A \texttt{grep} on \texttt{texmf-dist} returns hits
-% for: \file{thm-restate.sty}, \file{smartref.sty}, \file{jmlrbook.cls},
-% \file{cleveref.sty}, \file{cryptocode.sty}, \file{nameref.sty},
-% \file{easyeqn.sty}, \file{empheq.sty}, \file{ntheorem.sty},
-% \file{nccmath.sty}, \file{nwejm.cls}, \file{nwejmart.cls},
-% \file{aguplus.sty}, \file{aguplus.cls}, \file{agupp.sty},
-% \file{amsmath.hyp}, \file{amsmath.sty} (surprise!), \file{amsmath.4ht},
-% \file{nameref.4ht}, \file{frenchle.sty}, \file{french.sty}, plus
-% corresponding documentations and different versions of the same packages.
-% That's not too many, but not ``just a few'' either. The critical ones are
-% explicitly handled here (\pkg{amsmath} itself, and \pkg{nameref}). A number
-% of those I'm really not acquainted with. For \pkg{cleveref}, in particular,
-% this procedure is not compatible with it. If we happen to come later than
-% it and override its definition, this may be a substantial problem for
-% \pkg{cleveref}, since it will find the label, but it won't contain the data
-% it is expecting. However, this should normally not occur, if the user has
-% followed the documented recommendation for \pkg{cleveref} to load it last,
-% or at least very late, and besides I don't see much of an use case for using
-% both \pkg{cleveref} and \pkg{zref-clever} together. I have documented in
-% the user manual that this module may cause potential issues, and how to work
-% around them. And I have made an upstream feature request for a hook, so
-% that this could be made more cleanly at
-% \url{https://github.com/latex3/hyperref/issues/212}.
-% \begin{macrocode}
- \@@_if_package_loaded:nTF { hyperref }
- {
- \AddToHook { package / nameref / after }
- {
- \cs_new_eq:NN \@@_orig_ltxlabel:n \ltx@label
- \cs_set_eq:NN \ltx@label \@@_ltxlabel:n
- }
- }
- {
- \cs_new_eq:NN \@@_orig_ltxlabel:n \ltx@label
- \cs_set_eq:NN \ltx@label \@@_ltxlabel:n
- }
-% \end{macrocode}
% The \env{subequations} environment uses \texttt{parentequation} and
% \texttt{equation} as counters, but only the later is subject to
% \cs{refstepcounter}. What happens is: at the start, \texttt{equation} is
@@ -8145,11 +8058,7 @@
% From the \pkg{breqn} documentation: \textquote{Use of the normal \cs{label}
% command instead of the \opt{label} option works, I think, most of the time
% (untested)}. Indeed, light testing suggests it does work for \cs{zlabel}
-% just as well. However, if it happens not to work, there was no easy
-% alternative handle I could find. In particular, it does not seem viable to
-% leverage the \opt{label=} option without hacking the package internals, even
-% if the case of doing so would not be specially tricky, just ``not very
-% civil''.
+% just as well.
%
% \begin{macrocode}
\@@_compat_module:nn { breqn }
@@ -8223,19 +8132,6 @@
counterresetby = { lstnumber = lstlisting } ,
}
% \end{macrocode}
-% Set (also) a \cs{zlabel} with the label received in the \texttt{label=}
-% option from the \texttt{lstlisting} environment. The \emph{only} place to
-% set this label is the \texttt{PreInit} hook. This hook, comes right after
-% \cs{lst@MakeCaption} in \cs{lst@Init}, which runs \cs{refstepcounter} on
-% \texttt{lstlisting}, so we must come after it. Also \pkg{listings} itself
-% sets \cs{@currentlabel} to \cs{thelstnumber} in the \texttt{Init} hook,
-% which comes right after the \texttt{PreInit} one in \cs{lst@Init}. Since,
-% if we add to \texttt{Init} here, we go to the end of it, we'd be seeing the
-% wrong \cs{@currentlabel} at that point.
-% \begin{macrocode}
- \lst@AddToHook { PreInit }
- { \tl_if_empty:NF \lst@label { \zlabel { \lst@label } } }
-% \end{macrocode}
% Set \texttt{currentcounter} to \texttt{lstnumber} in the \texttt{Init} hook,
% since \pkg{listings} itself sets \cs{@currentlabel} to \cs{thelstnumber}
% here. Note that \pkg{listings} \emph{does use} \cs{refstepcounter} on