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