summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/zref-check/zref-check.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2021-12-08 03:02:13 +0000
committerNorbert Preining <norbert@preining.info>2021-12-08 03:02:13 +0000
commit0bfca40c9f89076ad634464a530fcc3e55d1d4e1 (patch)
tree7114d7d6b3ef883e247cfa80d6d36d0938b7c4f0 /macros/latex/contrib/zref-check/zref-check.dtx
parent6336c19969656f3ee5f0b0fed00aaf64369a40e7 (diff)
CTAN sync 202112080302
Diffstat (limited to 'macros/latex/contrib/zref-check/zref-check.dtx')
-rw-r--r--macros/latex/contrib/zref-check/zref-check.dtx119
1 files changed, 74 insertions, 45 deletions
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}