zref-check (8feb22)

git-svn-id: svn://tug.org/texlive/trunk@61950 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 108 insertions, 144 deletions

diff --git a/Master/texmf-dist/source/latex/zref-check/zref-check.dtx b/Master/texmf-dist/source/latex/zref-check/zref-check.dtx
index 57f5e26ca4f..6392f43c43d 100644
--- a/Master/texmf-dist/source/latex/zref-check/zref-check.dtx
+++ b/Master/texmf-dist/source/latex/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}
diff --git a/Master/texmf-dist/source/latex/zref-check/zref-check.ins b/Master/texmf-dist/source/latex/zref-check/zref-check.ins
index 6d3a14b1ccd..312a34c124a 100644
--- a/Master/texmf-dist/source/latex/zref-check/zref-check.ins
+++ b/Master/texmf-dist/source/latex/zref-check/zref-check.ins
@@ -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
@@ -50,7 +50,7 @@
 
 This file was generated from file(s) 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