summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/zref-clever
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2023-06-14 20:14:56 +0000
committerKarl Berry <karl@freefriends.org>2023-06-14 20:14:56 +0000
commitb0f67e19778c30606a0ec495b335739647431937 (patch)
tree10eed90e0954d39d37e5358435b873167697649b /Master/texmf-dist/doc/latex/zref-clever
parent7e2af6eaaed92aa41c00d6b9e6d3c12c92a821f4 (diff)
zref-clever (14jun23)
git-svn-id: svn://tug.org/texlive/trunk@67369 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/zref-clever')
-rw-r--r--Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md34
-rw-r--r--Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdfbin1283670 -> 1273255 bytes
-rw-r--r--Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex2
-rw-r--r--Master/texmf-dist/doc/latex/zref-clever/zref-clever-doc.pdfbin0 -> 346306 bytes
-rw-r--r--Master/texmf-dist/doc/latex/zref-clever/zref-clever-doc.tex (renamed from Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex)324
-rw-r--r--Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdfbin345913 -> 0 bytes
6 files changed, 201 insertions, 159 deletions
diff --git a/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md b/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md
index 8cbd673f55c..7c02e101a03 100644
--- a/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md
+++ b/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md
@@ -1,6 +1,38 @@
# Changelog
-## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.3.6...HEAD)
+## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.4.0...HEAD)
+
+## [v0.4.0](https://github.com/gusbrs/zref-clever/compare/v0.3.6...v0.4.0) (2023-06-14)
+
+### Added
+- `labelhook` option, controlling whether to set a `\zlabel` alongside a
+ standard `\label`. This option uses the kernel's new `label` hook, which
+ significantly improves and simplifies the task of setting a `\zlabel` in
+ places where this is not directly supported. The option is enabled by
+ default, and strongly recommended. It is not expected that this change will
+ bring backward compatibility problems, `\zlabel`s continue to work just as
+ before, and the places where a `\label` is required will also continue to
+ work the same way. The only case I see where you might need to adjust
+ existing documents is if you already had both `\label`s and `\zlabel`s with
+ the same names, in which case now you'll have a duplicate `zlabel` and will
+ indeed have to correct it. Also, you may be interested in taking a look at
+ the "`\label` or `\zlabel`?" section of the User manual, since the option
+ opens the possibility of a different approach in label setting in your
+ documents.
+
+### Changed
+- Given the new `labelhook` option and the fact that it requires both the new
+ `label` hook and the new hooks with options released in the latest LaTeX
+ kernel, the kernel version required by `zref-clever` has been bumped to
+ 2023-06-01.
+
+### Removed
+- Given the new `labelhook` option, the parts of compatibility modules which
+ provided for setting `\zlabel`s with `\label` in places where the former is
+ not supported have been removed. These would conflict with the new option,
+ and the use of the `label` hook for this purpose renders them unnecessary
+ and is superior in every aspect. Namely, the compatibility modules changed
+ in this fashion are: `amsmath`, `memoir`, and `listings`.
## [v0.3.6](https://github.com/gusbrs/zref-clever/compare/v0.3.5...v0.3.6) (2023-02-21)
diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf
index 87eb00b7d80..f2e55277a18 100644
--- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf
+++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex
index ba3a5eaaa23..ec9210dd67c 100644
--- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex
+++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex
@@ -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.
%
diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-doc.pdf b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-doc.pdf
new file mode 100644
index 00000000000..46429193c93
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-doc.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-doc.tex
index 138e4e938e1..23645f429e0 100644
--- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex
+++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-doc.tex
@@ -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.
%
@@ -331,7 +331,11 @@ Indeed, to use \pkg{zref}, instead of setting a \cs{label} and making a
\cs{ref}, one would set a \cs{zlabel} and make \cs{zref}s to it, in pretty
much the same way as for the standard system. \pkg{zref-clever} introduces
the more featureful \cs{zcref} for making references, but relies on
-\pkg{zref}'s \cs{zlabel} for label setting.
+\pkg{zref}'s \cs{zlabel} for label setting. \pkg{zref-clever} provides that a
+\cs{label} also sets a \cs{zlabel} with the same name using the kernel's
+\texttt{label} hook (see the \opt{labelhook} option in \zcref{sec:options}),
+so that you can use it too with standard \cs{label}s (see the
+\zcref{sec:label-or-zlabel} for discussion).
A basic document using \pkg{zref-clever} is shown in \zcref{how:basic} which,
despite the small necessary adjustments, should feel very familiar to any
@@ -403,7 +407,7 @@ 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
+\pkg{zref-clever} requires a recent \LaTeX{} kernel (2023-06-01 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.
@@ -411,7 +415,7 @@ some time.
\section{Dependencies}
-\pkg{zref-clever} requires \pkg{zref}, and \LaTeX{} kernel 2021-11-15, or
+\pkg{zref-clever} requires \pkg{zref}, and \LaTeX{} kernel 2023-06-01, or
newer. It also needs \pkg{ifdraft}. Some packages are leveraged by
\pkg{zref-clever} if they are present, but are not loaded by default or
required by it, namely: \pkg{hyperref}, \pkg{zref-check}, and \pkg{zref}'s
@@ -487,6 +491,49 @@ Sets \meta{label} for referencing with \cs{zref} and, thus, also \cs{zcref}.
\cs{label} for \pkg{zref}'s referencing system.
+\section{\cs{label} or \cs{zlabel}?}
+\zlabel{sec:label-or-zlabel}
+
+Technically, \pkg{zref}'s referencing system, and thus also \pkg{zref-clever},
+require a label set with \cs{zlabel} to make a reference. However, the
+\opt{labelhook} option (see \zcref{sec:options}) leverages the kernel's
+\texttt{label} hook to also set a \cs{zlabel} when a standard \cs{label} is
+called, so that we can simply use \cs{label}s in our document and refer to
+them with either referencing system. Indeed, in some places the use of
+\cs{label} this way may be required (see
+\zcref{sec:limitations,sec:comp-modules}). That given, which is to be
+preferred: use \cs{label} all around or normally use \cs{zlabel} and,
+occasionally resort to \cs{label} where required? I guess it depends, but we
+can reason the pros and cons of both alternatives.
+
+Simply using \cs{label} across your document clearly speaks for convenience.
+You don't have to worry with the exceptional case where a \cs{zlabel} may not
+work or setting it is not possible. You can use either referencing system for
+your labels as desired. Your favorite editor may have some facilities to ease
+the insertion of labels, but does not support \cs{zlabel}. And so on. The
+only disadvantage I can see with this approach is that two labels end up in
+the \file{.aux} file which, arguably, may be seen as a redundancy, or waste.
+
+It is probably fair to consider this redundancy, in most use cases, as a
+negligible cost. But you may disagree, or the size of your document or your
+requirements may say otherwise, in which case you may prefer the second
+approach and use \cs{zlabel} normally, with some occasional \cs{label} where
+needed. Known relevant cases where \cs{label} is required are documented in
+the manual (see \zcref{sec:how-tos,sec:limitations,sec:comp-modules}), but
+some trial and error can easily cover the gap for the remaining cases. They
+are also rare cases. So finding out where \cs{label} is required should not
+be much of a trouble either.
+
+I think the first approach does deserve the status of ``recommended'' for
+normal use cases and documents. Despite that, note that the examples of this
+manual typically use the second approach. There's a historic reason for this,
+since most of them were created before the kernel's \texttt{label} hook was
+available, so that it was really the only approach. However, I'll keep the
+examples this way, notwithstanding this recommendation, because it is also
+important to document the limitations of directly using \cs{zlabel}, for those
+who may want to use the second approach.
+
+
\section{Options}
\zlabel{sec:options}
@@ -906,6 +953,19 @@ 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{\raisebox{.4em}{\dbend}\ labelhook} %
+\opt{labelhook} is a boolean option which controls whether \pkg{zref-clever}
+uses the kernel's \texttt{label} hook to, whenever a standard \cs{label} is
+called, also set a \cs{zlabel} with the same name. The package's default
+value is \texttt{true} so that one can use \cs{label}s along the document and
+refer to them (also) with \pkg{zref} and \pkg{zref-clever} reference commands.
+This value is not only the default, but also a recommended value. Disabling
+this option means you are on your own to handle cases where \cs{zlabel} does
+not work, which are not many, but can be tricky to deal with where they occur.
+Since this option only affects how labels are set, it is not available in
+\cs{zcref}. See \zcref{sec:label-or-zlabel} for some discussion of different
+labeling approaches this options allows for.
+
\DescribeOption{nocompat} %
Some packages, document classes, or LaTeX features may require specific
support to work with \pkg{zref-clever} (see \zcref{sec:limitations}).
@@ -1845,14 +1905,19 @@ package in the setup, the same procedure can be used with \cls{memoir}'s
\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
-environments, but it is not extended to \cs{zlabel}. \pkg{zref-clever}'s
-\opt{amsmath} compatibility module provides that a \cs{label} used inside
-these environments set both a regular \cs{label} and a \cs{zlabel}, so that we
-can refer to the equations with both referencing systems. Note the use of
-\cs{zlabel} for \env{subequations} though. For more details, see the
-description of the \opt{amsmath} compatibility module at
+\pkg{amsmath}'s display math environments have their contents processed twice,
+once for measuring and the second does the final typesetting. Hence,
+\pkg{amsmath} needs to handle \cs{label} specially inside these environments,
+otherwise we'd have duplicate labels all around, and indeed it does redefine
+\cs{label} locally inside them. Alas, the same treatment is not granted to
+\cs{zlabel}. Therefore, you must use \cs{label} (not \cs{zlabel}) inside
+\pkg{amsmath}'s display math environments, and the \opt{labelhook} option
+provides that a \cs{label} sets both a regular \cs{label} and a \cs{zlabel},
+so that we can refer to the equations with both referencing systems. The
+following environments are subject to this usage restriction: \env{equation},
+\env{align}, \env{alignat}, \env{flalign}, \env{xalignat}, \env{gather},
+\env{multline}, and their respective starred versions. For more details, see
+the description of the \opt{amsmath} compatibility module at
\zcref{sec:comp-modules}.
\begin{zchowto}[caption={\pkg{amsmath}},label={how:amsmath}]
@@ -1870,7 +1935,7 @@ description of the \opt{amsmath} compatibility module at
A^{(1)}_l =\begin{cases} n!,&\text{if }l =1\\
0,&\text{otherwise}.\end{cases}
\end{equation*}
-\begin{subequations}\zlabel{eq:3}
+\begin{subequations}\label{eq:3}
\begin{align}
A+B&=B+A\\
C&=D+E\label{eq:3b}\\
@@ -1926,14 +1991,13 @@ regardless of what the current counter is.
\pkg{listings} package.}
Being \env{lstlisting} a verbatim environment, setting labels inside it
-requires special treatment. \pkg{zref-clever}'s \opt{listings} compatibility
-module provides that a label given to the \opt{label} option gets set with
-both a regular \cs{label} and a \cs{zlabel}, so that we can refer to it with
-both referencing systems. Setting labels for specific lines of the
-environment can be done with \cs{zlabel} directly, subject to the same
-escaping as for the standard \cs{label}. For more details, see the
-description of the \opt{listings} compatibility module at
-\zcref{sec:comp-modules}.
+requires special treatment. \pkg{zref-clever}'s \opt{labelhook} option
+provides that a label given to the \opt{label} option gets set with both a
+regular \cs{label} and a \cs{zlabel}, so that we can refer to it with both
+referencing systems. Setting labels for specific lines of the environment can
+be done with \cs{zlabel} directly, subject to the same escaping as for the
+standard \cs{label}. For more details, see the description of the
+\opt{listings} compatibility module at \zcref{sec:comp-modules}.
\begin{zchowto}[caption={\pkg{listings}},label={how:listings},escapeinside=`']
\documentclass{article}
@@ -2101,7 +2165,50 @@ with the \opt{label type} option.
This is \zcref{th:theo} on \zcpageref{th:theo} and it is titled
``\zcref[noname,ref=title]{th:theo}''.
\end{mytheo}
-\end{document}\end{zchowto}
+\end{document}
+\end{zchowto}
+
+
+\subsection{\pkg{breqn}}
+
+\zctask{Make references to \pkg{breqn} math environments.}
+
+\pkg{breqn}'s math environments \env{dgroup}, \env{dmath}, \env{dseries}, and
+\env{darray} offer a \opt{label} option (plus \opt{labelprefix}) for the
+purpose of label setting. \pkg{breqn}'s documentation says the following
+about the use of \cs{label} inside its environments: \textquote{Use of the
+ normal \cs{label} command instead of the \opt{label} option works, I think,
+ most of the time (untested)}. My light testing suggests the same is true
+for \cs{zlabel}, which can then be used directly in these environments.
+Either way, given the \opt{labelhook} option, we can just use \pkg{breqn}'s
+\opt{label} option and be at ease. Also, \pkg{breqn} does not use
+\cs{refstepcounter} to increment the equation counters and, as a result, fails
+to set \pkg{hyperref} anchors for the equations (thus affecting standard
+labels too). You may wish to use the work-around provided by Heiko Oberdiek
+at \url{https://tex.stackexchange.com/a/241150}.
+
+\begin{zchowto}[caption={\pkg{breqn}},label={how:breqn}]
+\documentclass{article}
+\usepackage{zref-clever}
+\usepackage{breqn}
+\usepackage{hyperref}
+% From https://tex.stackexchange.com/a/241150.
+\usepackage{etoolbox}
+\makeatletter
+\patchcmd\eq@setnumber{\stepcounter}{\refstepcounter}{}{%
+ \errmessage{Patching \noexpand\eq@setnumber failed}}
+\makeatother
+\begin{document}
+\section{Section 1}
+\begin{dmath}[label={eq:1}]
+ f(x)=\frac{1}{x} \condition{for $x\neq 0$}
+\end{dmath}
+\begin{dmath}[labelprefix={eq:},label={2}]
+ H_2^2 = x_1^2 + x_1 x_2 + x_2^2 - q_1 - q_2
+\end{dmath}
+\zcref{eq:1, eq:2}
+\end{document}
+\end{zchowto}
\subsection{Ordinal references}
@@ -2181,6 +2288,15 @@ verbatim-like environments it depends on how they are defined and whether they
provide a proper place or option to do so. But other places may be
problematic too, for example, \pkg{amsmath} display math environments also
handle \cs{label} specially and the same work is not done for \cs{zlabel}.
+Classes and packages may offer label setting by means of arguments or options,
+and those usually only cater for the standard referencing system, etc.
+Fortunately for us, the \texttt{label} hook introduced by the \LaTeX{} kernel
+in the 2023-06-01 release improves the situation considerably.
+\pkg{zref-clever} makes use of it with the \opt{labelhook} option, enabled by
+default, so that a standard \cs{label} also sets a \cs{zlabel} with the same
+name, thus providing a very general and reliable way to deal with these places
+where setting a \cs{zlabel} directly is problematic: just set a standard
+label.
Regarding the second, a correctly set \cs{@currentcounter} is critical for the
task of \pkg{zref-clever}: the reference type will depend on that and,
@@ -2198,7 +2314,7 @@ which at least allows for some viable work-arounds when the value of
to set it, depends on the case. Still, \cs{refstepcounter} is ubiquitous
enough a tool that we can count on \cs{@currentcounter} most of the time.
-All in all, most things work, but some things don't. And if the later will
+All in all, most things work, but some things may not. And if the later will
eventually work depends essentially on whether support for \pkg{zref} is
provided by the relevant packages and classes or not. Or, failing that,
whether \pkg{zref-clever} is able to provide some specific support when a
@@ -2260,62 +2376,22 @@ features with support for the following: i) set counter types for counters
\texttt{subfigure}, \texttt{subtable}, and \texttt{poemline} (used in the
\env{verse} environment); ii) configure resetting behavior
(\opt{counterresetby} option) for \texttt{subfigure} and \texttt{subtable}
-counters; iii) provide that the \meta{label} arguments to environments
-\env{sidecaption} and \env{sidecontcaption} and commands \cs{bitwonumcaption},
-\cs{bionenumcaption}, and \cs{bicaption} \emph{also} set a \cs{zlabel} of the
-same name; iv) provide the \pkg{zref} property ``\texttt{subcaption}'' so that
+counters; iii) provide the \pkg{zref} property ``\texttt{subcaption}'' so that
we can refer to, for example, \texttt{\cs{zcref}[ref=subcaption]\{subcap-1\}}
-to emulate the functionality of \cls{memoir}'s \cs{subcaptionref}; v) provide
+to emulate the functionality of \cls{memoir}'s \cs{subcaptionref}; iv) provide
that \cs{footnote}, \cs{verbfootnote}, \cs{sidefootnote}, and \cs{pagenote}
get a proper \opt{currentcounter} set; and v) set counter types for counters
-\texttt{sidefootnote} and \texttt{pagenote}. Naturally, the sheer number of
-features that required some specific support implies that some gymnastics were
-needed here. But the most sensitive changes are: i) a local redefinition of
-\cs{label} inside the environments \env{sidecaption} and \env{sidecontcaption}
-and the commands \cs{bitwonumcaption}, \cs{bionenumcaption}, and
-\cs{bicaption}; and ii) the use of \pkg{ltcmdhooks} command hooks on
-\cs{bitwonumcaption}, \cs{bionenumcaption}, \cs{bicaption},
-\cs{@memsubcaption}, \cs{@makefntext}, and \cs{@makesidefntext}.
+\texttt{sidefootnote} and \texttt{pagenote}. The most sensitive changes are
+the use of \pkg{ltcmdhooks} command hooks on \cs{@memsubcaption},
+\cs{@makefntext}, and \cs{@makesidefntext}.
\DescribeOption{amsmath} %
-\pkg{amsmath}'s display math environments have their contents processed twice,
-once for measuring and the second does the final typesetting. Hence,
-\pkg{amsmath} needs to handle \cs{label} specially inside these environments,
-otherwise we'd have duplicate labels all around, and indeed it does redefine
-\cs{label} locally inside them. Alas, the same treatment is not granted to
-\cs{zlabel}. However, \cs{label} is set basically to \emph{store} the value
-of the argument inside the environments, and its global meaning is kept in
-\cs{ltx@label} which is called at the appropriate time to actually set the
-label. So, what \pkg{zref-clever} does is redefine \cs{ltx@label} to set
-\texttt{both} a regular \cs{label} and a \cs{zlabel} for the same \meta{label}
-(which does not generate a duplicate label problem since the referencing
-systems are independent). Therefore, you must use \cs{label} (not
-\cs{zlabel}) inside \pkg{amsmath}'s display math environments, and this
-compatibility module arranges that you can also refer to that label with
-\pkg{zref} and, thus, with \cs{zcref} as well. The following environments are
-subject to this usage restriction: \env{equation}, \env{align}, \env{alignat},
-\env{flalign}, \env{xalignat}, \env{gather}, \env{multline}, and their
-respective starred versions. In particular, the same is not the case for the
-\env{subequations} environment, inside which \cs{zlabel} works as usual (to
-refer to the main equation number, that is, right after
-\texttt{\cs{begin}\{subequations\}}). See the \zcref{how:amsmath} for an
-usage example. The module also ensures proper \opt{currentcounter} values are
-in place for the display math environments, for which it uses environment
-hooks, and sets the font of equation references to \cs{upshape}, following
-\pkg{amsmath}'s \cs{eqref}. Finally, the module also provides a
-\texttt{subeq} property, for display math environments used inside the
-\env{subequations} environment, which can be used to refer to them directly
-with the \opt{ref} option, or to build terse ranges with the \opt{endrange}
-option. Note that \pkg{zref-clever} is not the only package to redefine
-\cs{ltx@label}, and compatibility problems may arise if this module is used
-with such packages or with document classes that do the same. In case of
-trouble, you can load \pkg{zref-clever} with option \texttt{nocompat=amsmath}
-and either use the standard referencing system's facilities to refer to
-\pkg{amsmath}'s equations or check the code documentation for the technique
-used for this (which is pretty standard) and adapt it to your case. Given
-that any trouble that may arise here is one of the proper ``timing'' of the
-redefinition, it should not be particularly complicated to make such
-adjustments.
+The module ensures proper \opt{currentcounter} values are in place for the
+display math environments, for which it uses environment hooks. The module
+also provides a \texttt{subeq} property, for display math environments used
+inside the \env{subequations} environment, which can be used to refer to them
+directly with the \opt{ref} option, or to build terse ranges with the
+\opt{endrange} option.
\DescribeOption{mathtools} %
\pkg{mathtools} has a feature to show the numbers only for those equations
@@ -2330,33 +2406,14 @@ side.
\DescribeOption{breqn} %
This compatibility module only sets proper \opt{currentcounter} values for the
environments \env{dgroup}, \env{dmath}, \env{dseries}, and \env{darray}, and
-uses environment hooks for the purpose. Note that these environments offer a
-\opt{label} option for label setting, but implements it in a way that is
-somewhat tricky to grab for our purposes, so we don't do it. However,
-\pkg{breqn}'s documentation says the following about the use of \cs{label}
-inside its environments: \textquote{Use of the normal \cs{label} command
- instead of the \opt{label} option works, I think, most of the time
- (untested)}. My light testing suggests the same is true for \cs{zlabel},
-which can then be used directly in these environments. But the ``second
-class'' status for this use is the one granted by \pkg{breqn}, there's not
-much we can do here. If you have any trouble with this, you may wish to check
-\zcref{wkrnd:breqn}.
+uses environment hooks for the purpose. See the \zcref{how:breqn} for an
+usage example.
\DescribeOption{listings} %
-Being \env{lstlisting}s environments what they are, one cannot simply place a
-label inside them without special treatment. \pkg{listings} arranges to this
-by providing a \opt{label} option for setting a label for the whole
-environment, and a properly escaped label command inside the environment can
-be used to refer to the line number. While the later can also be used to set
-a \cs{zlabel} to make line number references, the \opt{label} option is
-catered to the standard labels exclusively. Hence, this compatibility module
-uses the same label name -- which luckily and atypically is stored in a
-variable -- and sets a \cs{zlabel} as well. This is done by using
-\pkg{listings}' \texttt{PreInit} hook, se we don't have to redefine or tamper
-with anything for the purpose. Besides this, the module also sets appropriate
-\opt{countertype}, \opt{counterresetby} and \opt{currentcounter} values for
-the \pkg{listings}' counters: \texttt{lstlisting} and \texttt{lstnumber}. See
-the \zcref{how:listings} for an usage example.
+The module sets appropriate \opt{countertype}, \opt{counterresetby} and
+\opt{currentcounter} values for the \pkg{listings}' counters:
+\texttt{lstlisting} and \texttt{lstnumber}. See the \zcref{how:listings} for
+an usage example.
\DescribeOption{enumitem} %
\LaTeX{}'s \env{enumerate} environment requires some special treatment from
@@ -2407,54 +2464,6 @@ sort, but from \pkg{zref-clever}'s perspective, their status is ``not
supported''.
-\subsection*{\pkg{breqn}}
-
-As mentioned in \opt{breqn}'s compatibility module (\zcref{sec:comp-modules}),
-\pkg{breqn}'s math environments \env{dgroup}, \env{dmath}, \env{dseries}, and
-\env{darray} offer a \opt{label} option (plus \opt{labelprefix}) for the
-purpose of label setting. Setting a \cs{zlabel} alongside with a regular
-\cs{label} based on that option requires redefining some of \pkg{breqn}
-internals. Also, \pkg{breqn} does not use \cs{refstepcounter} to increment
-the equation counters and, as a result, fails to set \pkg{hyperref} anchors
-for the equations (thus affecting standard labels too). The example below
-also provides to that.\footnote{The later work-around thanks to Heiko
- Oberdiek, at \url{https://tex.stackexchange.com/a/241150}.}
-
-
-\begin{zcworkaround}[caption={\pkg{breqn}},label={wkrnd:breqn}]
-\documentclass{article}
-\usepackage{zref-clever}
-\usepackage{breqn}
-\makeatletter
-\define@key{breqn}{label}{%
- \edef\next@label{%
- \noexpand\label{\next@label@pre#1}%
- \noexpand\zlabel{\next@label@pre#1}}%
- \let\next@label@pre\@empty}
-\makeatother
-\usepackage{hyperref}
-\usepackage{etoolbox}
-\makeatletter
-\patchcmd\eq@setnumber{\stepcounter}{\refstepcounter}{}{%
- \errmessage{Patching \noexpand\eq@setnumber failed}}
-\makeatother
-\begin{document}
-\section{Section 1}
-\begin{dmath}[label={eq:1}]
- f(x)=\frac{1}{x} \condition{for $x\neq 0$}
-\end{dmath}
-\begin{dmath}[labelprefix={eq:},label={2}]
- H_2^2 = x_1^2 + x_1 x_2 + x_2^2 - q_1 - q_2
-\end{dmath}
-\zcref{eq:1, eq:2}
-\end{document}
-\end{zcworkaround}
-
-Of course, you can always adapt things to your needs and, e.g., make the
-\opt{label} option set just \cs{zlabel} instead of both labels, or create a
-separate \opt{zlabel} option.
-
-
\subsection*{\cls{beamer}}
\cls{beamer} does some really atypical things with regard to cross-references.
@@ -2536,16 +2545,13 @@ 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}.
+does not provide for uniqueness of anchors as \pkg{hyperref} does, if you
+(need to) use \cs{label} to set both \cs{label} and \cs{zlabel}, relying on
+the \opt{labelhook} option, this 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, it is nevertheless there.
\section{Acknowledgments}
@@ -2589,6 +2595,7 @@ were generously provided by (in chronological order):
% 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)
+ % 2023-06-01: https://github.com/latex3/latex2e/pull/956
Phelype Oleinik,
% 2021-08-20: https://tex.stackexchange.com/q/611370 (comments)
% 2021-09-09: https://tex.stackexchange.com/a/614704
@@ -2596,6 +2603,7 @@ were generously provided by (in chronological order):
% 2021-10-21: https://github.com/latex3/latex2e/pull/699
% 2022-01-12: https://tex.stackexchange.com/questions/629946/#comment1571118_629946
% 2022-01-11: https://tex.stackexchange.com/questions/633341/#comment1579825_633347
+ % 2023-06-01: https://github.com/latex3/latex2e/pull/1020
Enrico Gregorio,
% 2021-08-20: https://tex.stackexchange.com/a/611385
% 2021-08-20: https://tex.stackexchange.com/q/611370/#comment1529282_611385
@@ -2637,9 +2645,11 @@ were generously provided by (in chronological order):
% and following discussion.
Thomas F. Sturm,
% 2023-02-09: https://github.com/T-F-S/tcolorbox/issues/206
+ % 2023-05-12: https://github.com/T-F-S/tcolorbox/issues/230
and Yukai Chou. % 'muzimuzhi'
% 2023-02-18: https://github.com/gusbrs/zref-clever/pull/14
% 2023-02-18: https://github.com/gusbrs/zref-clever/pull/15
+ % 2023-05-11: https://github.com/T-F-S/tcolorbox/issues/230
The package's language files have been provided or improved thanks to:
Denis Bitouzé (French),
diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf
deleted file mode 100644
index 4a4bfb147fb..00000000000
--- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf
+++ /dev/null
Binary files differ