summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/zref-check/zref-check.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2022-02-09 03:00:53 +0000
committerNorbert Preining <norbert@preining.info>2022-02-09 03:00:53 +0000
commit8363587176bd1746ab2d65ee183b196e6d3458cf (patch)
tree64a89e6416d2b23d149b3dd918af467ae0b7441a /macros/latex/contrib/zref-check/zref-check.dtx
parent98810f6d7d064e61186d0ce674c4ee9de47a1f55 (diff)
CTAN sync 202202090300
Diffstat (limited to 'macros/latex/contrib/zref-check/zref-check.dtx')
-rw-r--r--macros/latex/contrib/zref-check/zref-check.dtx248
1 files changed, 106 insertions, 142 deletions
diff --git a/macros/latex/contrib/zref-check/zref-check.dtx b/macros/latex/contrib/zref-check/zref-check.dtx
index 57f5e26ca4..6392f43c43 100644
--- a/macros/latex/contrib/zref-check/zref-check.dtx
+++ b/macros/latex/contrib/zref-check/zref-check.dtx
@@ -4,7 +4,7 @@
%
% This file is part of the LaTeX package "zref-check".
%
-% Copyright (C) 2021 Gustavo Barros
+% Copyright (C) 2021-2022 Gustavo Barros
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -121,7 +121,6 @@
% allowing for them to be consistently verified.
%
%
-%
% \section{Loading the package}
% \label{sec:loading-package}
%
@@ -190,6 +189,16 @@
% Sets \pkg{zref-check}'s options (see Section~\ref{sec:options}).
% \end{function}
%
+% \bigskip{}
+%
+% All user commands of \pkg{zref-check} have their \marg{label} arguments
+% protected for \pkg{babel} active characters using \pkg{zref}'s
+% \cs{zref@wrapper@babel}, so that we should have equivalent support in that
+% regard, as \pkg{zref} itself does. \pkg{zref-check} depends on \pkg{zref},
+% as the name entails, which means it is able to work with \pkg{zref} labels,
+% in general created by \cs{zlabel}, but also with \cs{zctarget} and the
+% \texttt{zcregion} environment provided by this package.
+%
%
% \section{Checks}
% \label{sec:checks}
@@ -229,6 +238,9 @@
% \item[nextpage] \meta{label} occurs on the next page relative to
% \cs{zcheck}.
%
+% \item[otherpage] \meta{label} occurs on a page different from that of
+% \cs{zcheck}, that is, it does \emph{not} occur on \opt{thispage}.
+%
% \item[pagegap] There is a page gap between \meta{label} and \cs{zcheck}, in
% other words, \meta{label} does \emph{not} occur on \opt{thispage},
% \opt{prevpage} or \opt{nextpage}.
@@ -357,69 +369,6 @@
% value, with default 5.
%
%
-% \DescribeOption{labelcmd} %
-% Defines the command used to set the user labels in \cs{zctarget} and
-% \texttt{zcregion}. Takes a control sequence \emph{name} as value, and the
-% default sets labels with the minimal required properties, those of the
-% \texttt{zrefcheck} property list. This is a preamble only option. The
-% specified control sequence must receive one mandatory argument (the
-% \marg{label}) and must generate a \texttt{zref label} with at least the
-% properties in the \texttt{zrefcheck} property list. The intended use case
-% is that of the user creating a convenience macro which calls both \cs{label}
-% and \cs{zlabel}, as suggested in Section~\ref{sec:labels}, so that the same
-% labels are accessible either from the standard reference system or from
-% \pkg{zref}. For example:
-%
-% \begin{verbatim}
-% \NewDocumentCommand\mybothlabels{m}{\label{#1}\zlabel{#1}}
-% \zrefchecksetup{labelcmd=mybothlabels}
-% \end{verbatim}
-%
-% Note that the value of the underlying counter used for labels in
-% \cs{zctarget} and \texttt{zcregion} -- what you'd get with a plain \cs{ref}
-% here -- is not really meaningful. But you get to use
-% \cs{pageref}\marg{label}, or \pkg{hyperref}'s
-% \cs{hyperref}\oarg{label}\marg{text} on the labels used in \cs{zctarget} and
-% \texttt{zcregion} with this procedure.
-%
-%
-% \section{Labels}
-% \label{sec:labels}
-%
-% \pkg{zref-check} depends on \pkg{zref}, as the name entails, which means it
-% is able to work with \pkg{zref} labels, in general created by \cs{zlabel},
-% but also with \cs{zctarget} and the \texttt{zcregion} environment provided
-% by this package. This has some advantages, particularly the data
-% flexibility of \pkg{zref}, and the absence of the ubiquitous ``load-order''
-% and compatibility problems which are well known to afflict \LaTeX{} packages
-% of this area of functionality. On the other hand, the reliance on
-% \pkg{zref} labels may be seen as an inconvenience, since users of the
-% standard cross-reference infrastructure may need to add extra labels for
-% this. That's true. But \pkg{zref-check} is not meant to replace the
-% existing functionality of the kernel or of the traditional packages in this
-% area (to my knowledge, it only intersects directly with \pkg{varioref} and,
-% even so, it is quite different in scope). Indeed, it is easy to see the use
-% in tandem with standard references, for example:
-%
-% \begin{verbatim}
-% ... Figure~\ref{fig:figure-1}, \zcheck*[nextpage]{fig:figure-1}{on
-% the next page}.
-% \end{verbatim}
-%
-% Besides, \pkg{zref} does not share the label name-space with the standard
-% labels, so that you can call both \cs{label} and \cs{zlabel} with the same
-% label name (manually, or through a convenience macro), to ease the label set
-% administration. The example above presumes that was the case.
-%
-% All user commands of \pkg{zref-check} have their \marg{label} arguments
-% protected for \pkg{babel} active characters using \pkg{zref}'s
-% \cs{zref@wrapper@babel}, so that we should have equivalent support in that
-% regard, as \pkg{zref} itself does. However, \pkg{zref-check} sets labels
-% which either start with \texttt{zrefcheck@} or end with \texttt{@zrefcheck},
-% for internal use. Label names with either of those are considered reserved
-% by the package.
-%
-%
% \section{Limitations}
%
% There are three qualitatively different kinds of checks being used by
@@ -561,7 +510,7 @@
%
% Identify the package.
% \begin{macrocode}
-\ProvidesExplPackage {zref-check} {2021-12-20} {0.2.3}
+\ProvidesExplPackage {zref-check} {2022-02-08} {0.2.4}
{Flexible cross-references with contextual checks based on zref}
% \end{macrocode}
%
@@ -614,9 +563,9 @@
% These are the lists of properties to be used by \pkg{zref-check}, that is,
% the list of properties the references and targets store. This is the
% minimum set required, more properties may be added according to options.
-% For labels set with \cs{@@_target_label:n}, that is, user facing labels, we
-% must use the \texttt{main} property list, so that \pkg{zref-clever} can also
-% retrieve the properties it needs to refer to them.
+% For user facing labels, we must use the \texttt{main} property list, so that
+% \pkg{zref-clever} can also retrieve the properties it needs to refer to
+% them.
% \begin{macrocode}
\zref@newlist { zrefcheck-check }
\zref@addprops { zrefcheck-check }
@@ -634,6 +583,16 @@
zc@abssec
}
% \end{macrocode}
+% For \pkg{zref-vario} we only need page information, since we only perform
+% \opt{above} and \opt{below} checks there.
+% \begin{macrocode}
+\zref@newlist { zrefcheck-zrefvario }
+\zref@addprops { zrefcheck-zrefvario }
+ {
+ page , % for messages
+ abspage ,
+ }
+% \end{macrocode}
%
%
% \section{Plumbing}
@@ -694,11 +653,13 @@
Control~sequence~named~'#1'~used~in~option~'labelcmd'~is~not~defined.~
Using~default~value.
}
-\msg_new:nnn { zref-check } { option-deprecated }
+\msg_new:nnn { zref-check } { option-deprecated-with-alternative }
{
- Option~'#1'~has~been~deprecated.\iow_newline:
- Use~'#2'~as~a~replacement.
+ Option~'#1'~has~been~deprecated~\msg_line_context:.\iow_newline:
+ Use~'#2'~instead.
}
+\msg_new:nnn { zref-check } { option-deprecated }
+ { Option~'#1'~has~been~deprecated~\msg_line_context:. }
% \end{macrocode}
%
%
@@ -838,13 +799,13 @@
msglevel / obeydraft .code:n =
{
% NOTE Option value deprecated in 2021-12-07 for v0.2.2.
- \msg_warning:nnnn { zref-check }{ option-deprecated }
+ \msg_warning:nnnn { zref-check }{ option-deprecated-with-alternative }
{ msglevel=obeydraft } { msglevel=infoifdraft }
} ,
msglevel / obeyfinal .code:n =
{
% NOTE Option value deprecated in 2021-12-07 for v0.2.2.
- \msg_warning:nnnn { zref-check }{ option-deprecated }
+ \msg_warning:nnnn { zref-check }{ option-deprecated-with-alternative }
{ msglevel=obeyfinal } { msglevel=warniffinal }
} ,
msglevel .value_required:n = true ,
@@ -900,13 +861,13 @@
onpage / obeydraft .code:n =
{
% NOTE Option value deprecated in 2021-12-07 for v0.2.2.
- \msg_warning:nnnn { zref-check }{ option-deprecated }
+ \msg_warning:nnnn { zref-check }{ option-deprecated-with-alternative }
{ onpage=obeydraft } { onpage=labelseqifdraft }
} ,
onpage / obeyfinal .code:n =
{
% NOTE Option value deprecated in 2021-12-07 for v0.2.2.
- \msg_warning:nnnn { zref-check }{ option-deprecated }
+ \msg_warning:nnnn { zref-check }{ option-deprecated-with-alternative }
{ onpage=obeyfinal } { onpage=msgiffinal }
} ,
onpage .value_required:n = true ,
@@ -941,66 +902,18 @@
%
% \subsubsection*{\opt{labelcmd} option}
%
-% \begin{variable}{\l_@@_target_label_tl}
-% I'd love to receive the macro itself rather than it's name, but this would
-% bring unwarranted complications:
-% \url{https://tex.stackexchange.com/a/489570}.
% \begin{macrocode}
-\tl_new:N \l_@@_target_label_tl
-\bool_new:N \l_@@_target_label_bool
\keys_define:nn { zref-check }
{
labelcmd .code:n =
{
- \tl_set:Nn \l_@@_target_label_tl {#1}
- \bool_set_true:N \l_@@_target_label_bool
+ % NOTE Option value deprecated in 2022-02-08 for v0.2.4.
+ \msg_warning:nnn { zref-check }{ option-deprecated }
+ { labelcmd }
} ,
- labelcmd .value_required:n = true ,
}
% \end{macrocode}
-% \end{variable}
-%
-% \begin{macro}{\@@_target_label:n}
-% Default definition of the function for user label setting in \cs{zctarget}
-% and \texttt{zcregion}. It may be redefined at \texttt{begindocument}
-% according to option \opt{labelcmd}.
-% \begin{macrocode}
-\cs_new_protected:Npn \@@_target_label:n #1
- { \zref@label {#1} }
-% \end{macrocode}
-% \end{macro}
%
-% \begin{macrocode}
-\AddToHook { begindocument }
- {
- \bool_if:NT \l_@@_target_label_bool
- {
- \tl_if_blank:VT \l_@@_target_label_tl
- { \tl_clear:N \l_@@_target_label_tl }
- \cs_if_exist:cTF { \l_@@_target_label_tl }
- {
- \cs_set_protected:Npx \@@_target_label:n #1
- {
- \exp_not:o
- { \cs:w \l_@@_target_label_tl \cs_end: }
- {#1}
- }
- }
- {
- \exp_args:Nnno \msg_warning:nnn { zref-check }
- { labelcmd-undefined } { \l_@@_target_label_tl }
- }
- }
- \keys_define:nn { zref-check }
- {
- labelcmd .code:n =
- {
- \msg_warning:nnn { zref-check }
- { option-preamble-only } { labelcmd }
- }
- }
- }
-% \end{macrocode}
%
%
% \subsubsection*{Package options}
@@ -1191,6 +1104,11 @@
% complications it brings, this check was a slippery slope. All in all, I've
% decided to drop it.
%
+% There's an interesting answer by David Carlisle at
+% \url{https://tex.stackexchange.com/a/419189} to decide whether to typeset
+% ``above'' or ``below'' using a method which essentially boils down to
+% ``position in the \file{.aux} file''.
+%
%
%
% \subsection{Counter}
@@ -1516,7 +1434,7 @@
% \begin{macrocode}
\group_begin:
\refstepcounter { zrefcheck }
- \zref@wrapper@babel \@@_target_label:n {#1}
+ \zref@wrapper@babel \zref@label {#1}
#2
\tl_if_empty:nF {#2}
{
@@ -1538,7 +1456,7 @@
\NewDocumentEnvironment {zcregion} { m }
{
\refstepcounter { zrefcheck }
- \zref@wrapper@babel \@@_target_label:n {#1}
+ \zref@wrapper@babel \zref@label {#1}
}
{
\zref@wrapper@babel
@@ -1643,6 +1561,7 @@
prevpage ,
nextpage ,
facing ,
+ otherpage ,
pagegap ,
above ,
below ,
@@ -1799,19 +1718,31 @@
\@@_check_thispage:nnT
{#2} {#3}
{ \bool_set_true:N \l_@@_onpage_bool }
- \@@_check_thispage:nnT
- {#2} { \@@_end_lblfmt:n {#3} }
- { \bool_set_true:N \l_@@_onpage_bool }
- \zref@ifrefundefined { \@@_end_lblfmt:n {#2} }
- {}
+ \zref@ifrefundefined { \@@_end_lblfmt:n {#3} }
+ {
+ \zref@ifrefundefined { \@@_end_lblfmt:n {#2} }
+ {}
+ {
+ \@@_check_thispage:nnT
+ { \@@_end_lblfmt:n {#2} } {#3}
+ { \bool_set_true:N \l_@@_onpage_bool }
+ }
+ }
{
\@@_check_thispage:nnT
- { \@@_end_lblfmt:n {#2} } {#3}
- { \bool_set_true:N \l_@@_onpage_bool }
- \@@_check_thispage:nnT
- { \@@_end_lblfmt:n {#2} }
- { \@@_end_lblfmt:n {#3} }
+ {#2} { \@@_end_lblfmt:n {#3} }
{ \bool_set_true:N \l_@@_onpage_bool }
+ \zref@ifrefundefined { \@@_end_lblfmt:n {#2} }
+ {}
+ {
+ \@@_check_thispage:nnT
+ { \@@_end_lblfmt:n {#2} } {#3}
+ { \bool_set_true:N \l_@@_onpage_bool }
+ \@@_check_thispage:nnT
+ { \@@_end_lblfmt:n {#2} }
+ { \@@_end_lblfmt:n {#3} }
+ { \bool_set_true:N \l_@@_onpage_bool }
+ }
}
}
\bool_if:NTF \l_@@_passedcheck_bool
@@ -1836,6 +1767,7 @@
}
\group_end:
}
+\cs_generate_variant:Nn \@@_do_check:nnn { nnV }
% \end{macrocode}
% \end{macro}
%
@@ -1861,7 +1793,7 @@
%
% \subsubsection{This page}
%
-% \begin{macro}{\@@_check_thispage:nn}
+% \begin{macro}{\@@_check_thispage:nn, \@@_check_otherpage:nn}
% \begin{macrocode}
\prg_new_protected_conditional:Npnn \@@_check_thispage:nn #1#2 { T , F , TF }
{
@@ -1880,13 +1812,19 @@
% shipped out, will receive value `1'. So, if we do find `0' here, better
% signal something is wrong. This comment extends to all page number checks.
% \begin{macrocode}
- ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
- ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
+ ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
+ ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
}
{ \group_insert_after:N \prg_return_true: }
{ \group_insert_after:N \prg_return_false: }
\group_end:
}
+\prg_new_protected_conditional:Npnn \@@_check_otherpage:nn #1#2 { T , F , TF }
+ {
+ \@@_check_thispage:nnTF {#1} {#2}
+ { \prg_return_false: }
+ { \prg_return_true: }
+ }
% \end{macrocode}
% \end{macro}
%
@@ -2424,6 +2362,32 @@
% \end{macro}
%
%
+%
+% \section{\pkg{zref-vario} integration}
+%
+%
+% \begin{macro}
+% {
+% \zrefcheck_zrefvario_label: ,
+% \zrefcheck_zrefvario_run_check_on_label:n
+% }
+% \begin{macrocode}
+\cs_new_protected:Npn \zrefcheck_zrefvario_label:
+ {
+ \int_gincr:N \g_@@_id_int
+ \tl_set:Nx \l_@@_checkbeg_tl
+ { \@@_check_lblfmt:n { \g_@@_id_int } }
+ \zref@labelbylist { \l_@@_checkbeg_tl } { zrefcheck-zrefvario }
+ }
+\cs_new_protected:Npn \zrefcheck_zrefvario_run_check_on_label:nn #1#2
+ { \@@_do_check:nnV {#1} {#2} \l_@@_checkbeg_tl }
+\cs_generate_variant:Nn \zrefcheck_zrefvario_run_check_on_label:nn { Vn }
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+%
% \begin{macrocode}
%</package>
% \end{macrocode}