zref-check (17sep21)

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

1 files changed, 283 insertions, 217 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 29c48befbd3..584cf1b316d 100644
--- a/Master/texmf-dist/source/latex/zref-check/zref-check.dtx
+++ b/Master/texmf-dist/source/latex/zref-check/zref-check.dtx
@@ -231,6 +231,10 @@
 % \item[nextpage] \meta{label} occurs on the next page relative to
 %   \cs{zcheck}.
 %
+% \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}.
+%
 % \item[facing] On a \texttt{twoside} document, both \meta{label} and
 %   \cs{zcheck} fall onto a double spread, each on one of the two facing
 %   pages.
@@ -512,6 +516,16 @@
 % may be needed for these checks to work as expected.
 %
 %
+%
+% \section{Change history}
+%
+% A change log with relevant changes for each version, eventual upgrade
+% instructions, and upcoming changes, is maintained in the package's
+% repository, at
+% \url{https://github.com/gusbrs/zref-check/blob/main/CHANGELOG.md}.
+%
+%
+%
 % \end{documentation}
 %
 %
@@ -549,7 +563,7 @@
 %
 % Identify the package.
 %    \begin{macrocode}
-\ProvidesExplPackage {zref-check} {2021-08-17} {0.2.0}
+\ProvidesExplPackage {zref-check} {2021-09-16} {0.2.1}
   {Flexible cross-references with contextual checks based on zref}
 %    \end{macrocode}
 %
@@ -600,14 +614,29 @@
 %    \end{macrocode}
 %
 %
-% This is the list 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.
+% 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.
 %    \begin{macrocode}
-\zref@newlist { zrefcheck }
-\zref@addprops { zrefcheck }
+\zref@newlist { zrefcheck-check }
+\zref@addprops { zrefcheck-check }
+  {
+    page , % for messages
+    abspage ,
+    zc@abschap ,
+    zc@abssec
+  }
+\zref@newlist { zrefcheck-target }
+\zref@addprops { zrefcheck-target }
+  {
+    page , % so that \zpageref can refer to it
+    abspage ,
+    zc@abschap ,
+    zc@abssec
+  }
+\zref@newlist { zrefcheck-end }
+\zref@addprops { zrefcheck-end }
   {
-    page ,
     abspage ,
     zc@abschap ,
     zc@abssec
@@ -621,7 +650,7 @@
 %
 % \begin{macro}{\@@_message:nnnn, \@@_message:nnnx}
 %    \begin{macrocode}
-\cs_new:Npn \@@_message:nnnn #1#2#3#4
+\cs_new_protected:Npn \@@_message:nnnn #1#2#3#4
   {
     \use:c { msg_ \l_@@_msglevel_tl :nnnnn }
       { zref-check } {#1} {#2} {#3} {#4}
@@ -632,29 +661,20 @@
 %
 %    \begin{macrocode}
 \msg_new:nnn { zref-check } { check-failed }
-  {
-    Failed~check~'#1'~for~label~'#2' \iow_newline:
-    on~page~#3~on~input~line~\msg_line_number:.
-  }
+  { Failed~check~'#1'~for~label~'#2'~on~page~#3~\msg_line_context:. }
 \msg_new:nnn { zref-check } { double-check }
-  {
-    Double-check~'#1'~for~label~'#2' \iow_newline:
-    on~page~#3~on~input~line~\msg_line_number:.
-  }
+  { Double-check~'#1'~for~label~'#2'~on~page~#3~\msg_line_context:. }
 %    \end{macrocode}
 %
 %    \begin{macrocode}
 \msg_new:nnn { zref-check } { check-missing }
-  { Check~'#1'~not~defined~on~input~line~\msg_line_number:. }
+  { Check~'#1'~not~defined~\msg_line_context:. }
 \msg_new:nnn { zref-check } { property-undefined }
-  { Property~'#1'~not~defined~on~input~line~\msg_line_number:. }
+  { Property~'#1'~not~defined~\msg_line_context:. }
 \msg_new:nnn { zref-check } { property-not-in-label }
-  { Label~'#1'~has~no~property~'#2'~on~input~line~\msg_line_number:. }
+  { Label~'#1'~has~no~property~'#2'~\msg_line_context:. }
 \msg_new:nnn { zref-check } { property-not-integer }
-  {
-    Property~'#1'~for~label~'#2'~not~an~integer \iow_newline:
-    on~input~line~\msg_line_number:.
-  }
+  { Property~'#1'~for~label~'#2'~not~an~integer~\msg_line_context:. }
 %    \end{macrocode}
 %
 %    \begin{macrocode}
@@ -671,14 +691,11 @@
     Use~option~'msglevel'~instead.
   }
 \msg_new:nnn { zref-check } { option-preamble-only }
-  {
-    Option~'#1'~only~available~in~the~preamble \iow_newline:
-    on~input~line~\msg_line_number:.
-  }
+  { Option~'#1'~only~available~in~the~preamble~\msg_line_context:. }
 \msg_new:nnn { zref-check } { closerange-not-positive-integer }
   {
-    Option~'closerange'~not~a~positive~integer \iow_newline:
-    on~input~line~\msg_line_number:.~Using~default~value.
+    Option~'closerange'~not~a~positive~integer~\msg_line_context:.~
+    Using~default~value.
   }
 \msg_new:nnn { zref-check } { labelcmd-undefined }
   {
@@ -781,7 +798,7 @@
         \bool_if:NT \l_@@_use_hyperref_bool
           {
             \RequirePackage { zref-hyperref }
-            \zref@addprop { zrefcheck } { anchor }
+            \zref@addprop { zrefcheck-target } { anchor }
           }
       }
       {
@@ -930,8 +947,8 @@
 %   and \texttt{zcregion}.  It may be redefined at \texttt{begindocument}
 %   according to option \opt{labelcmd}.
 %    \begin{macrocode}
-\cs_new:Npn \@@_target_label:n #1
-  { \zref@labelbylist {#1} { zrefcheck } }
+\cs_new_protected:Npn \@@_target_label:n #1
+  { \zref@labelbylist {#1} { zrefcheck-target } }
 %    \end{macrocode}
 % \end{macro}
 %
@@ -944,7 +961,7 @@
           { \tl_clear:N \l_@@_target_label_tl }
         \cs_if_exist:cTF { \l_@@_target_label_tl }
           {
-            \cs_set:Npx \@@_target_label:n #1
+            \cs_set_protected:Npx \@@_target_label:n #1
               {
                 \exp_not:o
                   { \cs:w \l_@@_target_label_tl \cs_end: }
@@ -952,7 +969,7 @@
               }
           }
           {
-            \exp_args:NnnV \msg_warning:nnn { zref-check }
+            \exp_args:Nnno \msg_warning:nnn { zref-check }
               { labelcmd-undefined } { \l_@@_target_label_tl }
           }
       }
@@ -1214,9 +1231,11 @@
 %   property values as arguments in the checks, however we use here a number
 %   of non-expandable operations.  Hence, we receive a local \texttt{tl/int}
 %   variable as third argument and set that, so that it is available (and
-%   expandable) at the place of use.  For this reason, we do not group here,
-%   because we are passing a local variable around, but it is expected this
-%   function will be called within a group.
+%   expandable) at the place of use, and also make these functions `protected'
+%   (see egreg's \url{https://tex.stackexchange.com/a/572903}: ``a function
+%   that performs assignments should be \texttt{protected}'').  For this
+%   reason, we do not group here, because we are passing a local variable
+%   around, but it is expected this function will be called within a group.
 %
 %   We're returning \cs{c_empty_tl} in case of failure to find the intended
 %   property value (explicitly in \cs{zref@extractdefault}, but that is also
@@ -1226,7 +1245,7 @@
 %     \cs{zrefcheck_get_astl:nnn} \Arg{label} \Arg{prop} \Arg{tl var}
 %   \end{syntax}
 %    \begin{macrocode}
-\cs_new:Npn \zrefcheck_get_astl:nnn #1#2#3
+\cs_new_protected:Npn \zrefcheck_get_astl:nnn #1#2#3
   {
     \tl_clear:N #3
     \tl_if_eq:nnTF {#2} { lblseq }
@@ -1308,7 +1327,7 @@
 %     \cs{zrefcheck_get_asint:nnn} \Arg{label} \Arg{prop} \Arg{int var}
 %   \end{syntax}
 %    \begin{macrocode}
-\cs_new:Npn \zrefcheck_get_asint:nnn #1#2#3
+\cs_new_protected:Npn \zrefcheck_get_asint:nnn #1#2#3
   {
     \zrefcheck_get_astl:nnn {#1} {#2} { \l_@@_propval_tl }
     \@@_is_integer:nTF { \l_@@_propval_tl }
@@ -1357,8 +1376,7 @@
 %   \end{syntax}
 %
 %    \begin{macrocode}
-\NewDocumentCommand \zcheck
-  { s O { } > { \SplitList { , } } m m }
+\NewDocumentCommand \zcheck { s O { } m m }
   { \zref@wrapper@babel \@@_zcheck:nnnn {#3} {#1} {#2} {#4} }
 %    \end{macrocode}
 % \end{macro}
@@ -1366,17 +1384,17 @@
 %
 % \begin{variable}
 %   {
+%     \l_@@_zcheck_labels_seq ,
 %     \g_@@_id_int ,
 %     \l_@@_checkbeg_tl ,
-%     \l_@@_checkend_tl ,
 %     \l_@@_link_label_tl ,
 %     \l_@@_link_anchor_tl ,
 %     \l_@@_link_star_bool
 %   }
 %    \begin{macrocode}
+\seq_new:N \l_@@_zcheck_labels_seq
 \int_new:N \g_@@_id_int
 \tl_new:N \l_@@_checkbeg_tl
-\tl_new:N \l_@@_checkend_tl
 \tl_new:N \l_@@_link_label_tl
 \tl_new:N \l_@@_link_anchor_tl
 \bool_new:N \l_@@_link_star_bool
@@ -1395,36 +1413,31 @@
 %   \end{syntax}
 %
 %    \begin{macrocode}
-\cs_new:Npn \@@_zcheck:nnnn #1#2#3#4
+\cs_new_protected:Npn \@@_zcheck:nnnn #1#2#3#4
   {
     \group_begin:
 %    \end{macrocode}
-% Set checks keys.
-%    \begin{macrocode}
-      \@@_set_checks_keys:
-%    \end{macrocode}
 % Process local options and checks.
 %    \begin{macrocode}
-      \keys_set:nn { zref-check } {#3}
+      \keys_set:nn { zref-check / zcheck } {#3}
+      \seq_set_from_clist:Nn \l_@@_zcheck_labels_seq {#1}
 %    \end{macrocode}
-% Names of the labels for this zrefcheck call.
+% Names of the labels for this zcheck call.
 %    \begin{macrocode}
       \int_gincr:N \g_@@_id_int
       \tl_set:Nx \l_@@_checkbeg_tl
         { \@@_check_lblfmt:n { \g_@@_id_int } }
-      \tl_set:Nx \l_@@_checkend_tl
-        { \@@_end_lblfmt:n { \l_@@_checkbeg_tl } }
 %    \end{macrocode}
 % Set checkbeg label.
 %    \begin{macrocode}
-      \zref@labelbylist { \l_@@_checkbeg_tl } { zrefcheck }
+      \zref@labelbylist { \l_@@_checkbeg_tl } { zrefcheck-check }
 %    \end{macrocode}
 % Typeset \marg{text}, with hyperlink when appropriate.  Even though the first
 % argument can receive a list of labels, there is no meaningful way to set
 % links to multiple targets.  Hence, only the first one is considered for
 % hyperlinking.
 %    \begin{macrocode}
-      \tl_set:Nn \l_@@_link_label_tl { \tl_head:n {#1} }
+      \seq_get:NN \l_@@_zcheck_labels_seq \l_@@_link_label_tl
       \bool_set:Nn \l_@@_link_star_bool {#2}
       \zref@ifrefundefined { \l_@@_link_label_tl }
 %    \end{macrocode}
@@ -1448,16 +1461,21 @@
 %    \end{macrocode}
 % Set checkend label.
 %    \begin{macrocode}
-      \zref@labelbylist { \l_@@_checkend_tl } { zrefcheck }
+      \bool_if:NT \l_@@_zcheck_end_label_bool
+        {
+          \zref@labelbylist
+            { \@@_end_lblfmt:n { \l_@@_checkbeg_tl } }
+            { zrefcheck-end }
+        }
 %    \end{macrocode}
 % Check if \meta{labels} are defined.
 %    \begin{macrocode}
-      \tl_map_function:nN {#1} \zref@refused
+      \seq_map_function:NN \l_@@_zcheck_labels_seq \zref@refused
 %    \end{macrocode}
 % Run the checks.
 %    \begin{macrocode}
-      \@@_run_checks:nnv
-        { \l_@@_zcheck_checks_seq } {#1} { l_@@_checkbeg_tl }
+      \@@_run_checks:nnx { \l_@@_zcheck_checks_seq }
+        { \l_@@_zcheck_labels_seq } { \l_@@_checkbeg_tl }
     \group_end:
   }
 %    \end{macrocode}
@@ -1483,7 +1501,7 @@
     \zref@wrapper@babel \@@_target_label:n {#1}
     #2
     \zref@wrapper@babel
-      \zref@labelbylist { \@@_end_lblfmt:n {#1} } { zrefcheck }
+      \zref@labelbylist { \@@_end_lblfmt:n {#1} } { zrefcheck-end }
     \group_end:
   }
 %    \end{macrocode}
@@ -1503,7 +1521,7 @@
   }
   {
     \zref@wrapper@babel
-      \zref@labelbylist { \@@_end_lblfmt:n {#1} } { zrefcheck }
+      \zref@labelbylist { \@@_end_lblfmt:n {#1} } { zrefcheck-end }
   }
 %    \end{macrocode}
 % \end{macro}
@@ -1516,7 +1534,7 @@
 %
 % First, a conditional function defined with:
 %
-% \cs{prg_new_conditional:Npnn} \cs{@@_check_\meta{check}:nn} |#1#2 { F }|
+% \cs{prg_new_protected_conditional:Npnn} \cs{@@_check_\meta{check}:nn} |#1#2 { F }|
 %
 % \noindent where \meta{check} is the name of the check, the first argument is
 % the \Arg{label} and the second the \Arg{reference}.  The existence of the
@@ -1545,145 +1563,122 @@
 % \cs{zref@addprop} and friends, as usual.
 %
 % Third, the check must be registered as a key which gets setup in
-% \cs{zcheck} by \cs{@@_set_checks_keys:}.
+% \cs{zcheck} by the \texttt{ zref-check / zcheck } key set.
+%
+% Fourth, if the check requires only a single label to work, it should be
+% registered in \cs{c_@@_single_label_checks_seq}.
+%
+%
+% \subsection{Single label checks}
+%
+%
+% Some checks do not require an ``end label'' in \cs{zcheck}, notably the
+% sectioning ones, which don't rely on page boundaries.  Hence, in case
+% \cs{zcheck} only calls checks in this set, we can spare the setting of the
+% end label.
+%
+% \begin{variable}{\c_@@_single_label_checks_seq}
+%    \begin{macrocode}
+\seq_new:N \c_@@_single_label_checks_seq
+\seq_set_from_clist:Nn \c_@@_single_label_checks_seq
+  {
+    thischap ,
+    prevchap ,
+    nextchap ,
+    chapsbefore ,
+    chapsafter ,
+    thissec ,
+    prevsec ,
+    nextsec ,
+    secsbefore ,
+    secsafter ,
+  }
+%    \end{macrocode}
+% \end{variable}
+%
 %
 %
 % \subsection{Setup}
 %
-% \begin{variable}{\l_@@_zcheck_checks_seq}
+% \begin{variable}{\l_@@_zcheck_checks_seq,\l_@@_end_label_required_bool}
 %    \begin{macrocode}
 \seq_new:N \l_@@_zcheck_checks_seq
+\bool_new:N \l_@@_zcheck_end_label_bool
 %    \end{macrocode}
 % \end{variable}
 %
-% \begin{macro}{\@@_set_checks_keys:}
+%
+% First, we inherit all the main options into the keys of \texttt{zref-check /
+% zcheck}.
 %    \begin{macrocode}
-\cs_new:Npn \@@_set_checks_keys:
+\keys_define:nn { } { zref-check / zcheck .inherit:n = zref-check }
+%    \end{macrocode}
+%
+% Then we add the checks to it.
+%    \begin{macrocode}
+\clist_map_inline:nn
+  {
+    thispage ,
+    prevpage ,
+    nextpage ,
+    facing ,
+    pagegap ,
+    above ,
+    below ,
+    pagesbefore ,
+    ppbefore ,
+    pagesafter ,
+    ppafter ,
+    before ,
+    after ,
+    thischap ,
+    prevchap ,
+    nextchap ,
+    chapsbefore ,
+    chapsafter ,
+    thissec ,
+    prevsec ,
+    nextsec ,
+    secsbefore ,
+    secsafter ,
+    close ,
+    far ,
+  }
   {
-    \keys_define:nn  { zref-check }
+    \keys_define:nn { zref-check / zcheck }
       {
-        thispage .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { thispage } } ,
-        thispage .value_forbidden:n = true ,
-
-        prevpage .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { prevpage } } ,
-        prevpage .value_forbidden:n = true ,
-
-        nextpage .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { nextpage } } ,
-        nextpage .value_forbidden:n = true ,
-
-        facing .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { facing } } ,
-        facing .value_forbidden:n = true ,
-
-        above .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { above } } ,
-        above .value_forbidden:n = true ,
-
-        below .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { below } } ,
-        below .value_forbidden:n = true ,
-
-        pagesbefore .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { pagesbefore } } ,
-        pagesbefore .value_forbidden:n = true ,
-
-        ppbefore .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { ppbefore } } ,
-        ppbefore .value_forbidden:n = true ,
-
-        pagesafter .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { pagesafter } } ,
-        pagesafter .value_forbidden:n = true ,
-
-        ppafter .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { ppafter } } ,
-        ppafter .value_forbidden:n = true ,
-
-        before .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { before } } ,
-        before .value_forbidden:n = true ,
-
-        after .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { after } } ,
-        after .value_forbidden:n = true ,
-
-        thischap .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { thischap } } ,
-        thischap .value_forbidden:n = true ,
-
-        prevchap .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { prevchap } } ,
-        prevchap .value_forbidden:n = true ,
-
-        nextchap .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { nextchap } } ,
-        nextchap .value_forbidden:n = true ,
-
-        chapsbefore .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { chapsbefore } } ,
-        chapsbefore .value_forbidden:n = true ,
-
-        chapsafter .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { chapsafter } } ,
-        chapsafter .value_forbidden:n = true ,
-
-        thissec .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { thissec } } ,
-        thissec .value_forbidden:n = true ,
-
-        prevsec .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { prevsec } } ,
-        prevsec .value_forbidden:n = true ,
-
-        nextsec .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { nextsec } } ,
-        nextsec .value_forbidden:n = true ,
-
-        secsbefore .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { secsbefore } } ,
-        secsbefore .value_forbidden:n = true ,
-
-        secsafter .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { secsafter } } ,
-        secsafter .value_forbidden:n = true ,
-
-        close .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { close } } ,
-        close .value_forbidden:n = true ,
-
-        far .code:n =
-          { \seq_put_right:Nn \l_@@_zcheck_checks_seq { far } } ,
-        far .value_forbidden:n = true ,
-      }
+        #1 .code:n =
+          {
+            \seq_put_right:Nn \l_@@_zcheck_checks_seq {#1}
+            \seq_if_in:NnF \c_@@_single_label_checks_seq {#1}
+              { \bool_set_true:N \l_@@_zcheck_end_label_bool }
+          } ,
+        #1 .value_forbidden:n = true ,
+     }
   }
 %    \end{macrocode}
-% \end{macro}
-%
 %
 %
 %
 % \subsection{Running}
 %
-% \begin{macro}{\@@_run_checks:nnn, \@@_run_checks:nnv}
+% \begin{macro}{\@@_run_checks:nnn}
 %   \begin{syntax}
 %     \cs{@@_run_checks:nnn} \Arg{checks} \Arg{labels} \Arg{reference}
 %   \end{syntax}
 %   \meta{checks} are expected to be received as a sequence variable.
 %    \begin{macrocode}
-\cs_new:Npn \@@_run_checks:nnn #1#2#3
+\cs_new_protected:Npn \@@_run_checks:nnn #1#2#3
   {
     \group_begin:
-      \tl_map_inline:nn {#2}
+      \seq_map_inline:Nn #2
         {
           \seq_map_inline:Nn #1
             { \@@_do_check:nnn {####1} {##1} {#3} }
         }
     \group_end:
   }
-\cs_generate_variant:Nn \@@_run_checks:nnn { nnv }
+\cs_generate_variant:Nn \@@_run_checks:nnn { nnx }
 %    \end{macrocode}
 % \end{macro}
 %
@@ -1714,7 +1709,7 @@
 %     \cs{@@_do_check:nnn} \Arg{check} \Arg{label beg} \Arg{reference beg}
 %   \end{syntax}
 %    \begin{macrocode}
-\cs_new:Npn \@@_do_check:nnn #1#2#3
+\cs_new_protected:Npn \@@_do_check:nnn #1#2#3
   {
     \group_begin:
 %    \end{macrocode}
@@ -1732,37 +1727,45 @@
               \bool_set_false:N \l_@@_onpage_bool
               \cs_if_exist:cTF { @@_check_ #1 :nnF }
                 {
-%    \end{macrocode}
-% ``label beg'' vs ``reference beg''.
-%    \begin{macrocode}
+                  % ``label beg'' vs ``reference beg''.
                   \use:c { @@_check_ #1 :nnF }
                     {#2} {#3}
                     { \bool_set_false:N \l_@@_passedcheck_bool }
-%    \end{macrocode}
-% ``label beg'' vs ``reference end''.
-%    \begin{macrocode}
-                  \exp_args:Nnno \use:c { @@_check_ #1 :nnF }
-                    {#2} { \@@_end_lblfmt:n {#3} }
-                    { \bool_set_false:N \l_@@_passedcheck_bool }
-%    \end{macrocode}
-% ``label end'' \emph{may} have been created by the target commands.
-%    \begin{macrocode}
-                  \zref@ifrefundefined { \@@_end_lblfmt:n {#2} }
-                    {}
+                  % ``reference end'' \emph{may} exist or not depending on the
+                  % checks.
+                  \zref@ifrefundefined { \@@_end_lblfmt:n {#3} }
                     {
-%    \end{macrocode}
-% ``label end'' vs ``reference beg''.
-%    \begin{macrocode}
-                      \exp_args:Nno \use:c { @@_check_ #1 :nnF }
-                        { \@@_end_lblfmt:n {#2} } {#3}
-                        { \bool_set_false:N \l_@@_passedcheck_bool }
-%    \end{macrocode}
-% ``label end'' vs ``reference end''.
-%    \begin{macrocode}
-                      \exp_args:Nnoo \use:c { @@_check_ #1 :nnF }
-                        { \@@_end_lblfmt:n {#2} }
-                        { \@@_end_lblfmt:n {#3} }
+                      % ``label end'' \emph{may} have been created by the
+                      % target commands.
+                      \zref@ifrefundefined { \@@_end_lblfmt:n {#2} }
+                        {}
+                        {
+                          % ``label end'' vs ``reference beg''.
+                          \exp_args:Nno \use:c { @@_check_ #1 :nnF }
+                            { \@@_end_lblfmt:n {#2} } {#3}
+                            { \bool_set_false:N \l_@@_passedcheck_bool }
+                        }
+                    }
+                    {
+                      % ``label beg'' vs ``reference end''.
+                      \exp_args:Nnno \use:c { @@_check_ #1 :nnF }
+                        {#2} { \@@_end_lblfmt:n {#3} }
                         { \bool_set_false:N \l_@@_passedcheck_bool }
+                      % ``label end'' \emph{may} have been created by the
+                      % target commands.
+                      \zref@ifrefundefined { \@@_end_lblfmt:n {#2} }
+                        {}
+                        {
+                          % ``label end'' vs ``reference beg''.
+                          \exp_args:Nno \use:c { @@_check_ #1 :nnF }
+                            { \@@_end_lblfmt:n {#2} } {#3}
+                            { \bool_set_false:N \l_@@_passedcheck_bool }
+                          % ``label end'' vs ``reference end''.
+                          \exp_args:Nnoo \use:c { @@_check_ #1 :nnF }
+                            { \@@_end_lblfmt:n {#2} }
+                            { \@@_end_lblfmt:n {#3} }
+                            { \bool_set_false:N \l_@@_passedcheck_bool }
+                        }
                     }
 %    \end{macrocode}
 % Handle option \opt{onpage=msg}.  This is only granted for tests which
@@ -1839,7 +1842,7 @@
 %
 % \begin{macro}{\@@_check_thispage:nn}
 %    \begin{macrocode}
-\prg_new_conditional:Npnn \@@_check_thispage:nn #1#2 { T , F , TF }
+\prg_new_protected_conditional:Npnn \@@_check_thispage:nn #1#2 { T , F , TF }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -1871,7 +1874,7 @@
 %
 % \begin{macro}{\@@_check_above:nn, \@@_check_below:nn}
 %    \begin{macrocode}
-\prg_new_conditional:Npnn \@@_check_above:nn #1#2 { F , TF }
+\prg_new_protected_conditional:Npnn \@@_check_above:nn #1#2 { F , TF }
   {
     \group_begin:
       \@@_check_thispage:nnTF {#1} {#2}
@@ -1893,7 +1896,7 @@
         { \group_insert_after:N \prg_return_false: }
     \group_end:
   }
-\prg_new_conditional:Npnn \@@_check_below:nn #1#2 { F , TF }
+\prg_new_protected_conditional:Npnn \@@_check_below:nn #1#2 { F , TF }
   {
     \@@_check_thispage:nnTF {#1} {#2}
       {
@@ -1911,7 +1914,7 @@
 %
 % \begin{macro}{\@@_check_before:nn, \@@_check_after:nn}
 %    \begin{macrocode}
-\prg_new_conditional:Npnn \@@_check_before:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_before:nn #1#2 { F }
   {
     \@@_check_pagesbefore:nnTF {#1} {#2}
       { \prg_return_true: }
@@ -1921,7 +1924,7 @@
           { \prg_return_false: }
       }
   }
-\prg_new_conditional:Npnn \@@_check_after:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_after:nn #1#2 { F }
   {
     \@@_check_pagesafter:nnTF {#1} {#2}
       { \prg_return_true: }
@@ -1945,10 +1948,11 @@
 %     \@@_check_ppbefore:nn ,
 %     \@@_check_pagesafter:nn ,
 %     \@@_check_ppafter:nn ,
+%     \@@_check_pagegap:nn ,
 %     \@@_check_facing:nn
 %   }
 %    \begin{macrocode}
-\prg_new_conditional:Npnn \@@_check_nextpage:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_nextpage:nn #1#2 { F }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -1966,7 +1970,7 @@
         { \group_insert_after:N \prg_return_false: }
     \group_end:
   }
-\prg_new_conditional:Npnn \@@_check_prevpage:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_prevpage:nn #1#2 { F }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -1984,7 +1988,7 @@
         { \group_insert_after:N \prg_return_false: }
     \group_end:
   }
-\prg_new_conditional:Npnn \@@_check_pagesbefore:nn #1#2 { F , TF }
+\prg_new_protected_conditional:Npnn \@@_check_pagesbefore:nn #1#2 { F , TF }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2003,7 +2007,7 @@
     \group_end:
   }
 \cs_new_eq:NN \@@_check_ppbefore:nnF \@@_check_pagesbefore:nnF
-\prg_new_conditional:Npnn \@@_check_pagesafter:nn #1#2 { F , TF }
+\prg_new_protected_conditional:Npnn \@@_check_pagesafter:nn #1#2 { F , TF }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2022,7 +2026,25 @@
     \group_end:
   }
 \cs_new_eq:NN \@@_check_ppafter:nnF \@@_check_pagesafter:nnF
-\prg_new_conditional:Npnn \@@_check_facing:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_pagegap:nn #1#2 { F }
+  {
+    \group_begin:
+      \bool_set_true:N \l_@@_integer_bool
+      \zrefcheck_get_asint:nnn {#1} { abspage } { \l_@@_lbl_int }
+      \zrefcheck_get_asint:nnn {#2} { abspage } { \l_@@_ref_int }
+      \bool_lazy_and:nnTF
+        { \l_@@_integer_bool }
+        {
+          \int_compare_p:nNn
+            { \int_abs:n { \l_@@_lbl_int - \l_@@_ref_int } } > { 1 } &&
+          ! \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_facing:nn #1#2 { F }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2065,7 +2087,7 @@
 %
 % \begin{macro}{\@@_check_close:nn, \@@_check_far:nn}
 %    \begin{macrocode}
-\prg_new_conditional:Npnn \@@_check_close:nn #1#2 { F , TF }
+\prg_new_protected_conditional:Npnn \@@_check_close:nn #1#2 { F , TF }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2085,7 +2107,7 @@
         { \group_insert_after:N \prg_return_false: }
     \group_end:
   }
-\prg_new_conditional:Npnn \@@_check_far:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_far:nn #1#2 { F }
   {
     \@@_check_close:nnTF {#1} {#2}
       { \prg_return_false: }
@@ -2106,7 +2128,7 @@
 %     \@@_check_chapsbefore:nn
 %   }
 %    \begin{macrocode}
-\prg_new_conditional:Npnn \@@_check_thischap:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_thischap:nn #1#2 { F }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2132,7 +2154,7 @@
         { \group_insert_after:N \prg_return_false: }
     \group_end:
   }
-\prg_new_conditional:Npnn \@@_check_nextchap:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_nextchap:nn #1#2 { F }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2149,7 +2171,7 @@
         { \group_insert_after:N \prg_return_false: }
     \group_end:
   }
-\prg_new_conditional:Npnn \@@_check_prevchap:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_prevchap:nn #1#2 { F }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2167,7 +2189,7 @@
         { \group_insert_after:N \prg_return_false: }
     \group_end:
   }
-\prg_new_conditional:Npnn \@@_check_chapsafter:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_chapsafter:nn #1#2 { F }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2184,7 +2206,7 @@
         { \group_insert_after:N \prg_return_false: }
     \group_end:
   }
-\prg_new_conditional:Npnn \@@_check_chapsbefore:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_chapsbefore:nn #1#2 { F }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2217,7 +2239,7 @@
 %     \@@_check_secsbefore:nn
 %   }
 %    \begin{macrocode}
-\prg_new_conditional:Npnn \@@_check_thissec:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_thissec:nn #1#2 { F }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2247,7 +2269,7 @@
         { \group_insert_after:N \prg_return_false: }
     \group_end:
   }
-\prg_new_conditional:Npnn \@@_check_nextsec:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_nextsec:nn #1#2 { F }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2268,7 +2290,7 @@
         { \group_insert_after:N \prg_return_false: }
     \group_end:
   }
-\prg_new_conditional:Npnn \@@_check_prevsec:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_prevsec:nn #1#2 { F }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2290,7 +2312,7 @@
         { \group_insert_after:N \prg_return_false: }
     \group_end:
   }
-\prg_new_conditional:Npnn \@@_check_secsafter:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_secsafter:nn #1#2 { F }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2311,7 +2333,7 @@
         { \group_insert_after:N \prg_return_false: }
     \group_end:
   }
-\prg_new_conditional:Npnn \@@_check_secsbefore:nn #1#2 { F }
+\prg_new_protected_conditional:Npnn \@@_check_secsbefore:nn #1#2 { F }
   {
     \group_begin:
       \bool_set_true:N \l_@@_integer_bool
@@ -2337,6 +2359,50 @@
 % \end{macro}
 %
 %
+%
+% \section{\pkg{zref-clever} integration}
+%
+%
+% There are four tasks \pkg{zref-clever} needs to do, in order to offer
+% integration with \pkg{zref-check} from the options of \cs{zcref}: i) set the
+% ``beg label''; ii) set the checks options; iii) run the checks; iv)
+% (possibly) set the ``end label''.  Since `ii)' can be done directly by
+% running |\keys_set:nn { zref-check / zcheck }| on the options received, we
+% provide convenience functions for the other three tasks.
+%
+%
+% \begin{macro}
+%   {
+%     \zrefcheck_zcref_beg_label: ,
+%     \zrefcheck_zcref_end_label_maybe: ,
+%     \zrefcheck_zcref_run_checks_on_labels:n
+%   }
+%    \begin{macrocode}
+\cs_new_protected:Npn \zrefcheck_zcref_beg_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-check }
+  }
+\cs_new_protected:Npn \zrefcheck_zcref_end_label_maybe:
+  {
+    \bool_if:NT \l_@@_zcheck_end_label_bool
+      {
+        \zref@labelbylist
+          { \@@_end_lblfmt:n { \l_@@_checkbeg_tl } }
+          { zrefcheck-end }
+      }
+  }
+\cs_new_protected:Npn \zrefcheck_zcref_run_checks_on_labels:n #1
+  {
+    \@@_run_checks:nnx
+      { \l_@@_zcheck_checks_seq } {#1} { \l_@@_checkbeg_tl }
+  }
+%    \end{macrocode}
+% \end{macro}
+%
+%
 %    \begin{macrocode}
 %</package>
 %    \end{macrocode}