diff options
Diffstat (limited to 'macros/latex/contrib/zref-check/zref-check.dtx')
| -rw-r--r-- | macros/latex/contrib/zref-check/zref-check.dtx | 119 |
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} |