From 0bfca40c9f89076ad634464a530fcc3e55d1d4e1 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Wed, 8 Dec 2021 03:02:13 +0000
Subject: CTAN sync 202112080302

---
 macros/latex/contrib/zref-check/zref-check.dtx | 119 +++++++++++++++----------
 1 file changed, 74 insertions(+), 45 deletions(-)

(limited to 'macros/latex/contrib/zref-check/zref-check.dtx')

diff --git a/macros/latex/contrib/zref-check/zref-check.dtx b/macros/latex/contrib/zref-check/zref-check.dtx
index 584cf1b316..fb4e93c857 100644
--- a/macros/latex/contrib/zref-check/zref-check.dtx
+++ b/macros/latex/contrib/zref-check/zref-check.dtx
@@ -24,9 +24,7 @@
 %                                 zref-check.ins,
 %                                 zref-check.tex,
 %                                 zref-check-code.tex,
-%           and the derived files zref-check.sty and
-%                                 zref-check.pdf,
-%                                 zref-check-code.pdf.
+%         and the files listed in MANIFEST.md.
 %
 % The released version of this package is available from CTAN.
 %
@@ -306,7 +304,7 @@
 % Section~\ref{sec:user-interface}) in the preamble.  Most options can also be
 % used with local effects, through the optional argument of \cs{zcheck}.
 %
-% \DescribeOption{hyperref}
+% \DescribeOption{hyperref} %
 % Controls the use of \pkg{hyperref} by \pkg{zref-check} and takes values
 % \opt{auto}, \opt{true}, \opt{false}.  The default value, \opt{auto}, makes
 % \pkg{zref-check} use \pkg{hyperref} if it is loaded, meaning \cs{zcheck} can
@@ -319,47 +317,47 @@
 % hyperlinking by means of its starred version.
 %
 %
-% \DescribeOption{msglevel}
+% \DescribeOption{msglevel} %
 % Sets the level of messages issued by \cs{zcheck} failed checks and takes
-% values \opt{warn}, \opt{info}, \opt{none}, \opt{obeydraft}, \opt{obeyfinal}.
-% The default value, \opt{warn}, issues messages both to the terminal and to
-% the log file, \opt{info} issues messages to the log file only, \opt{none}
-% suppresses all messages.  \opt{obeydraft} corresponds to \opt{info} if
-% option \opt{draft} is passed to \cs{documentclass}, and to \opt{warn}
-% otherwise.  \opt{obeyfinal} corresponds to \opt{warn} if option \opt{final}
-% is (explicitly) passed to \cs{documentclass} and \opt{info} otherwise.
-% \opt{ignore} is provided as convenience alias for \opt{msglevel=none} for
-% local use only.  This option only affects the messages issued by the checks
-% in \cs{zcheck}, not other messages or warnings of the package.  In
-% particular, it does not affect warnings issued for undefined labels, which
-% just use \cs{zref@refused} and thus are the same as standard \LaTeX{} ones
-% for this purpose.
-%
-%
-% \DescribeOption{onpage}
+% values \opt{warn}, \opt{info}, \opt{none}, \opt{infoifdraft},
+% \opt{warniffinal}.  The default value, \opt{warn}, issues messages both to
+% the terminal and to the log file, \opt{info} issues messages to the log file
+% only, \opt{none} suppresses all messages.  \opt{infoifdraft} corresponds to
+% \opt{info} if option \opt{draft} is passed to \cs{documentclass}, and to
+% \opt{warn} otherwise.  \opt{warniffinal} corresponds to \opt{warn} if option
+% \opt{final} is (explicitly) passed to \cs{documentclass} and \opt{info}
+% otherwise.  \opt{ignore} is provided as convenience alias for
+% \opt{msglevel=none} for local use only.  This option only affects the
+% messages issued by the checks in \cs{zcheck}, not other messages or warnings
+% of the package.  In particular, it does not affect warnings issued for
+% undefined labels, which just use \cs{zref@refused} and thus are the same as
+% standard \LaTeX{} ones for this purpose.
+%
+%
+% \DescribeOption{onpage} %
 % Allows to control the messaging style for ``within page checks'', and takes
-% values \opt{labelseq}, \opt{msg}, \opt{obeydraft}, \opt{obeyfinal}.  The
-% default, \opt{labelseq}, uses the labels' shipout sequence, as retrieved
+% values \opt{labelseq}, \opt{msg}, \opt{labelseqifdraft}, \opt{msgiffinal}.
+% The default, \opt{labelseq}, uses the labels' shipout sequence, as retrieved
 % from the \file{.aux} file, to infer relative position within the page.
 % \opt{msg} also uses the same method for checking relative position, but
 % issues a (different) message \emph{even if the check passes}, to provide a
 % simple workflow for robust checking of ``false negatives'', considering the
 % label sequence is not fool proof (for details and workflow recommendations,
 % see Section~\ref{sec:within-page-checks}).  \opt{msg} also issues its
-% messages at the same level defined in \opt{msglevel}.  \opt{obeydraft}
+% messages at the same level defined in \opt{msglevel}.  \opt{labelseqifdraft}
 % corresponds to \opt{labelseq} if option \opt{draft} is passed to
-% \cs{documentclass} and to \opt{msg} otherwise.  \opt{obeyfinal} corresponds
+% \cs{documentclass} and to \opt{msg} otherwise.  \opt{msgiffinal} corresponds
 % to \opt{msg} if option \opt{final} is (explicitly) passed to
 % \cs{documentclass}, and to \opt{labelseq} otherwise.
 %
 %
-% \DescribeOption{closerange}
+% \DescribeOption{closerange} %
 % Defines the width of the range of pages, relative to the reference, that are
 % considered ``close'' by the \opt{close} check.  Takes a positive integer as
 % value, with default 5.
 %
 %
-% \DescribeOption{labelcmd}
+% \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
@@ -486,12 +484,12 @@
 % false positives (getting a warning when it was not due), but with false
 % negatives (not getting a warning when it was due).  Hence, setting
 % \opt{onpage} to \opt{msg} at a final typesetting stage (or just set it to
-% \opt{obeydraft} or \opt{obeyfinal} if that's part of your workflow) provides
-% a way to easily identify all cases of such checks (failing or passing), and
-% double-check them.  In case the test is passing though, the message is
-% different from that of a failing check, to quickly convey why you are
-% getting the message.  This option can also be set at the local level, if the
-% page in question is known to be problematic, or just atypical.
+% \opt{labelseqifdraft} or \opt{msgiffinal} if that's part of your workflow)
+% provides a way to easily identify all cases of such checks (failing or
+% passing), and double-check them.  In case the test is passing though, the
+% message is different from that of a failing check, to quickly convey why you
+% are getting the message.  This option can also be set at the local level, if
+% the page in question is known to be problematic, or just atypical.
 %
 %
 % \subsection{Sectioning checks}
@@ -563,7 +561,7 @@
 %
 % Identify the package.
 %    \begin{macrocode}
-\ProvidesExplPackage {zref-check} {2021-09-16} {0.2.1}
+\ProvidesExplPackage {zref-check} {2021-12-07} {0.2.2}
   {Flexible cross-references with contextual checks based on zref}
 %    \end{macrocode}
 %
@@ -582,10 +580,9 @@
 %   Provide absolute counters for section and chapter, and respective
 %   \pkg{zref} properties, so that we can make checks about relation of
 %   chapters/sections regardless of internal counters, since we don't get
-%   those for the unnumbered (starred) ones.  About the proper place to make
-%   the hooks for this purpose, see
-%   \url{https://tex.stackexchange.com/q/605533/105447} (thanks Ulrike
-%   Fischer).
+%   those for the unnumbered (starred) ones.  Thanks Ulrike Fischer for
+%   suggestions at TeX.SX about the proper place to make the hooks for this
+%   purpose.
 %    \begin{macrocode}
 \int_new:N \g_@@_abschap_int
 \int_new:N \g_@@_abssec_int
@@ -681,7 +678,7 @@
 \msg_new:nnn { zref-check } { hyperref-preamble-only }
   {
     Option~'hyperref'~only~available~in~the~preamble. \iow_newline:
-    Use~the~starred~version~of~'\noexpand\zcheck'~instead.
+    Use~the~starred~version~of~'\iow_char:N\\zcheck'~instead.
   }
 \msg_new:nnn { zref-check } { missing-hyperref }
   { Missing~'hyperref'~package. \iow_newline: Setting~'hyperref=false'. }
@@ -702,6 +699,11 @@
     Control~sequence~named~'#1'~used~in~option~'labelcmd'~is~not~defined.~
     Using~default~value.
   }
+\msg_new:nnn { zref-check } { option-deprecated }
+  {
+    Option~'#1'~has~been~deprecated.\iow_newline:
+    Use~'#2'~as~a~replacement.
+  }
 %    \end{macrocode}
 %
 %
@@ -829,18 +831,30 @@
       { \tl_set:Nn \l_@@_msglevel_tl { info } } ,
     msglevel / none .code:n =
       { \tl_set:Nn \l_@@_msglevel_tl { none } } ,
-    msglevel / obeydraft .code:n =
+    msglevel / infoifdraft .code:n =
       {
         \ifdraft
           { \tl_set:Nn \l_@@_msglevel_tl { info } }
           { \tl_set:Nn \l_@@_msglevel_tl { warning } }
       } ,
-    msglevel / obeyfinal .code:n =
+    msglevel / warniffinal .code:n =
       {
         \ifoptionfinal
           { \tl_set:Nn \l_@@_msglevel_tl { warning } }
           { \tl_set:Nn \l_@@_msglevel_tl { info } }
       } ,
+    msglevel / obeydraft .code:n =
+      {
+        % NOTE Option value deprecated in 2021-12-07 for v0.2.2.
+        \msg_warning:nnnn { zref-check }{ option-deprecated }
+          { 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 }
+          { msglevel=obeyfinal } { msglevel=warniffinal }
+      } ,
     msglevel .value_required:n = true ,
     msglevel .initial:n = warn ,
 %    \end{macrocode}
@@ -879,18 +893,30 @@
       {
         \bool_set_true:N \l_@@_msgonpage_bool
       } ,
-    onpage / obeydraft .code:n =
+    onpage / labelseqifdraft .code:n =
       {
         \ifdraft
           { \bool_set_false:N \l_@@_msgonpage_bool }
           { \bool_set_true:N \l_@@_msgonpage_bool }
       } ,
-    onpage / obeyfinal .code:n =
+    onpage / msgiffinal .code:n =
       {
         \ifoptionfinal
           { \bool_set_true:N \l_@@_msgonpage_bool }
           { \bool_set_false:N \l_@@_msgonpage_bool }
       } ,
+    onpage / obeydraft .code:n =
+      {
+        % NOTE Option value deprecated in 2021-12-07 for v0.2.2.
+        \msg_warning:nnnn { zref-check }{ option-deprecated }
+          { 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 }
+          { onpage=obeyfinal } { onpage=msgiffinal }
+      } ,
     onpage .value_required:n = true ,
     onpage .initial:n = labelseq
   }
@@ -1500,8 +1526,11 @@
     \refstepcounter { zrefcheck }
     \zref@wrapper@babel \@@_target_label:n {#1}
     #2
-    \zref@wrapper@babel
-      \zref@labelbylist { \@@_end_lblfmt:n {#1} } { zrefcheck-end }
+    \tl_if_empty:nF {#2}
+      {
+        \zref@wrapper@babel
+          \zref@labelbylist { \@@_end_lblfmt:n {#1} } { zrefcheck-end }
+      }
     \group_end:
   }
 %    \end{macrocode}
-- 
cgit v1.2.3

