Debian Codegraph @

texmf-dist/source/latex/zref-check/zref-check.dtx

raw
1 % \iffalse meta-comment
2 %
3 % File: zref-check.dtx
4 %
5 % This file is part of the LaTeX package "zref-check".
6 %
7 % Copyright (C) 2021-2024 gusbrs
8 %
9 % It may be distributed and/or modified under the conditions of the
10 % LaTeX Project Public License (LPPL), either version 1.3c of this
11 % license or (at your option) any later version. The latest version
12 % of this license is in the file:
13 %
14 % https://www.latex-project.org/lppl.txt
15 %
16 % and version 1.3 or later is part of all distributions of LaTeX
17 % version 2005/12/01 or later.
18 %
19 %
20 % This work is "maintained" (as per LPPL maintenance status) by gusbrs.
21 %
22 % This work consists of the files zref-check.dtx,
23 % zref-check.ins,
24 % zref-check-doc.tex,
25 % zref-check-code.tex,
26 % and the files generated from them.
27 %
28 % The released version of this package is available from CTAN.
29 %
30 % -----------------------------------------------------------------------
31 %
32 % The development version of the package can be found at
33 %
34 % https://github.com/gusbrs/zref-check
35 %
36 % for those people who are interested.
37 %
38 % -----------------------------------------------------------------------
39 %
40 % \fi
41 %
42 % \iffalse
43 %<*driver>
44 \documentclass{l3doc}
45 % Have \GetFileInfo pick up date and version data
46 \usepackage{zref-check}
47 \NewDocumentCommand\opt{m}{\texttt{#1}}
48 \MakeShortVerb{\|}
49 \begin{document}
50 \DocInput{zref-check.dtx}
51 \end{document}
52 %</driver>
53 % \fi
54 %
55 %
56 %
57 % \section{Initial setup}
58 %
59 % Start the \pkg{DocStrip} guards.
60 % \begin{macrocode}
61 %<*package>
62 % \end{macrocode}
63 %
64 % Identify the internal prefix (\LaTeX3 \pkg{DocStrip} convention).
65 % \begin{macrocode}
66 %<@@=zrefcheck>
67 % \end{macrocode}
68 %
69 %
70 % For the \texttt{chapter} and \texttt{section} checks, \pkg{zref-check} uses
71 % the new hook system in \pkg{ltcmdhooks}, which was released with the
72 % 2021/06/01 \LaTeX{} kernel. And, since we followed the move to
73 % \texttt{e}-type expansion, to play safe we require the 2023-11-01 kernel or
74 % newer.
75 % \begin{macrocode}
76 \def\zrefcheck@required@kernel{2023-11-01}
77 \NeedsTeXFormat{LaTeX2e}[\zrefcheck@required@kernel]
78 \providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
79 \IfFormatAtLeastTF{\zrefcheck@required@kernel}
80 {}
81 {%
82 \PackageError{zref-check}{LaTeX kernel too old}
83 {%
84 'zref-check' requires a LaTeX kernel \zrefcheck@required@kernel\space or newer.%
85 }%
86 }%
87 % \end{macrocode}
88 %
89 % Identify the package.
90 % \begin{macrocode}
91 \ProvidesExplPackage {zref-check} {2024-11-28} {0.3.7}
92 {Flexible cross-references with contextual checks based on zref}
93 % \end{macrocode}
94 %
95 % \section{Dependencies}
96 %
97 % \begin{macrocode}
98 \RequirePackage { zref-user }
99 \RequirePackage { zref-abspage }
100 \RequirePackage { ifdraft }
101 % \end{macrocode}
102 %
103 %
104 % \section{\pkg{zref} setup}
105 %
106 % Provide absolute counters for section and chapter, and respective \pkg{zref}
107 % properties, so that we can make checks about relation of chapters/sections
108 % regardless of internal counters, since we don't get those for the unnumbered
109 % (starred) ones. Thanks Ulrike Fischer for suggestions at TeX.SX about the
110 % proper place to make the hooks for this purpose.
111 % \begin{macrocode}
112 \newcounter { zc@abschap }
113 \newcounter { zc@abssec } [ zc@abschap ]
114 % \end{macrocode}
115 %
116 %
117 % If the documentclass does not define \cs{chapter} the only thing that
118 % happens is that the chapter counter is never incremented, and the section
119 % one never reset.
120 % \begin{macrocode}
121 \AddToHook { cmd / chapter / before }
122 { \stepcounter { zc@abschap } }
123 \zref@newprop { zc@abschap } [0] { \int_use:N \c@zc@abschap }
124 \zref@addprop \ZREF@mainlist { zc@abschap }
125 % \end{macrocode}
126 %
127 % \begin{macrocode}
128 \AddToHook { cmd / section / before }
129 { \stepcounter { zc@abssec } }
130 \zref@newprop { zc@abssec } [0] { \int_use:N \c@zc@abssec }
131 \zref@addprop \ZREF@mainlist { zc@abssec }
132 % \end{macrocode}
133 %
134 %
135 % These are the lists of properties to be used by \pkg{zref-check}, that is,
136 % the list of properties the references and targets store. This is the
137 % minimum set required, more properties may be added according to options.
138 % For user facing labels, we must use the \texttt{main} property list, so that
139 % \pkg{zref-clever} can also retrieve the properties it needs to refer to
140 % them.
141 % \begin{macrocode}
142 \zref@newlist { zrefcheck-check }
143 \zref@addprops { zrefcheck-check }
144 {
145 page , % for messages
146 abspage ,
147 zc@abschap ,
148 zc@abssec
149 }
150 \zref@newlist { zrefcheck-end }
151 \zref@addprops { zrefcheck-end }
152 {
153 abspage ,
154 zc@abschap ,
155 zc@abssec
156 }
157 % \end{macrocode}
158 % For \pkg{zref-vario} we only need page information, since we only perform
159 % \opt{above} and \opt{below} checks there.
160 % \begin{macrocode}
161 \zref@newlist { zrefcheck-zrefvario }
162 \zref@addprops { zrefcheck-zrefvario }
163 {
164 page , % for messages
165 abspage ,
166 }
167 % \end{macrocode}
168 %
169 %
170 % \section{Plumbing}
171 %
172 % \subsection{Auxiliary}
173 %
174 % \begin{macro}
175 % {
176 % \l_@@_tmpa_tl ,
177 % \l_@@_tmpb_tl ,
178 % \g_@@_tmpa_tl ,
179 % \l_@@_tmpa_int ,
180 % \l_@@_tmpa_bool ,
181 % \g_@@_tmpa_ior ,
182 % }
183 % Temporary scratch variables.
184 % \begin{macrocode}
185 \tl_new:N \l_@@_tmpa_tl
186 \tl_new:N \l_@@_tmpb_tl
187 \tl_new:N \g_@@_tmpa_tl
188 \int_new:N \l_@@_tmpa_int
189 \bool_new:N \l_@@_tmpa_bool
190 \ior_new:N \g_@@_tmpa_ior
191 % \end{macrocode}
192 % \end{macro}
193 %
194 % \subsection{Messages}
195 %
196 % \begin{macro}{\@@_message:nnnn, \@@_message:nnne}
197 % \begin{macrocode}
198 \cs_new_protected:Npn \@@_message:nnnn #1#2#3#4
199 {
200 \use:c { msg_ \l_@@_msglevel_tl :nnnnn }
201 { zref-check } {#1} {#2} {#3} {#4}
202 }
203 \cs_generate_variant:Nn \@@_message:nnnn { nnne }
204 % \end{macrocode}
205 % \end{macro}
206 %
207 % \begin{macrocode}
208 \msg_new:nnn { zref-check } { check-failed }
209 {
210 Check~failed~\msg_line_context:.~
211 Failed~check~'#1'~for~label~'#2'~on~page~#3.
212 }
213 \msg_new:nnn { zref-check } { double-check }
214 {
215 Same~page~check~\msg_line_context:.~
216 Double-check~'#1'~for~label~'#2'~on~page~#3.
217 }
218 \msg_new:nnn { zref-check } { empty-label }
219 {
220 Check~failed~\msg_line_context:.~
221 Failed~check~'#1'~for~empty~label.
222 }
223 \msg_new:nnn { zref-check } { no-checks }
224 { No~checks~for~'\iow_char:N\\zcheck'~\msg_line_context:. }
225 % \end{macrocode}
226 %
227 % \begin{macrocode}
228 \msg_new:nnn { zref-check } { check-missing }
229 { Check~'#1'~not~defined~\msg_line_context:. }
230 \msg_new:nnn { zref-check } { property-undefined }
231 { Property~'#1'~not~defined~\msg_line_context:. }
232 \msg_new:nnn { zref-check } { property-not-in-label }
233 { Label~'#1'~has~no~property~'#2'~\msg_line_context:. }
234 \msg_new:nnn { zref-check } { property-not-integer }
235 { Property~'#1'~for~label~'#2'~not~an~integer~\msg_line_context:. }
236 % \end{macrocode}
237 %
238 % \begin{macrocode}
239 \msg_new:nnn { zref-check } { hyperref-preamble-only }
240 {
241 Option~'hyperref'~only~available~in~the~preamble. \iow_newline:
242 Use~the~starred~version~of~'\iow_char:N\\zcheck'~instead.
243 }
244 \msg_new:nnn { zref-check } { missing-hyperref }
245 { Missing~'hyperref'~package. \iow_newline: Setting~'hyperref=false'. }
246 \msg_new:nnn { zref-check } { ignore-ok-document-only }
247 {
248 Option~'#1'~only~available~in~the~document. \iow_newline:
249 Use~option~'msglevel'~instead.
250 }
251 \msg_new:nnn { zref-check } { option-preamble-only }
252 { Option~'#1'~is~preamble~only~\msg_line_context:. }
253 \msg_new:nnn { zref-check } { closerange-not-positive-integer }
254 {
255 Option~'closerange'~not~a~positive~integer~\msg_line_context:.~
256 Using~default~value.
257 }
258 \msg_new:nnn { zref-check } { labelcmd-undefined }
259 {
260 Control~sequence~named~'#1'~used~in~option~'labelcmd'~is~not~defined.~
261 Using~default~value.
262 }
263 \msg_new:nnn { zref-check } { option-deprecated-with-alternative }
264 {
265 Option~'#1'~has~been~deprecated~\msg_line_context:.\iow_newline:
266 Use~'#2'~instead.
267 }
268 \msg_new:nnn { zref-check } { option-deprecated }
269 { Option~'#1'~has~been~deprecated~\msg_line_context:. }
270 \msg_new:nnn { zref-check } { load-time-options }
271 {
272 'zref-check'~does~not~accept~load-time~options.~
273 To~configure~package~options,~use~'\iow_char:N\\zrefchecksetup'.
274 }
275 % \end{macrocode}
276 %
277 %
278 % \subsection{Integer testing}
279 %
280 % \begin{macro}{\@@_is_integer:n, \@@_int_to_roman:w}
281 % From \url{https://tex.stackexchange.com/a/244405} (thanks Enrico Gregorio,
282 % aka `egreg'), also see \url{https://tex.stackexchange.com/a/19769}.
283 % Following the \texttt{l3styleguide}, I made a copy of
284 % \cs{__int_to_roman:w}, since it is an internal function from the
285 % \texttt{int} module, but we still get a warning from \texttt{l3build doc},
286 % complaining about it. And we're using \cs{tl_if_empty:oTF} instead of
287 % \cs{tl_if_blank:oTF} as in egreg's answer, since \cs{romannumeral} is
288 % defined so that ``the expansion is empty if the number is zero or
289 % negative'', not ``blank''. A couple of comments about this technique: the
290 % underlying \cs{romannumeral} ignores space tokens and explicit signs
291 % (\texttt{+} and \texttt{-}) in the expansion and hence it can only be used
292 % to test positive integers; also the technique cannot distinguish whether
293 % it received an empty argument or if ``the expansion was empty'' as a
294 % result of receiving number as argument, so this must also be controlled
295 % for since, in our use case, this may happen.
296 % \begin{macrocode}
297 \cs_new_eq:NN \@@_int_to_roman:w \__int_to_roman:w
298 \prg_new_conditional:Npnn \@@_is_integer:n #1 { p, T , F , TF }
299 {
300 \tl_if_empty:oTF {#1}
301 { \prg_return_false: }
302 {
303 \tl_if_empty:oTF { \@@_int_to_roman:w -0#1 }
304 { \prg_return_true: }
305 { \prg_return_false: }
306 }
307 }
308 % \end{macrocode}
309 % \end{macro}
310 %
311 % \begin{macro}{\@@_is_integer_rgx:n}
312 % A possible alternative to \cs{@@_is_integer:n} is to use a straightforward
313 % regexp match (see \url{https://tex.stackexchange.com/a/427559}). It does
314 % not suffer from the mentioned caveats from the \cs{__int_to_roman:w}
315 % technique, however, while \cs{@@_is_integer:n} is expandable,
316 % \cs{@@_is_integer_rgx:n} is not. Also, \cs{@@_is_integer_rgx:n} is
317 % probably slower.
318 % \begin{macrocode}
319 \prg_new_protected_conditional:Npnn \@@_is_integer_rgx:n #1 { TF }
320 {
321 \regex_match:nnTF { \A\d+\Z } {#1}
322 { \prg_return_true: }
323 { \prg_return_false: }
324 }
325 % \end{macrocode}
326 % \end{macro}
327 %
328 %
329 %
330 % \subsection{Options}
331 %
332 %
333 % \subsubsection*{\opt{hyperref} option}
334 %
335 % \begin{variable}{\l_@@_use_hyperref_bool, \l_@@_warn_hyperref_bool}
336 % \begin{macrocode}
337 \bool_new:N \l_@@_use_hyperref_bool
338 \bool_new:N \l_@@_warn_hyperref_bool
339 \keys_define:nn { zref-check/setup }
340 {
341 hyperref .choice: ,
342 hyperref / auto .code:n =
343 {
344 \bool_set_true:N \l_@@_use_hyperref_bool
345 \bool_set_false:N \l_@@_warn_hyperref_bool
346 } ,
347 hyperref / true .code:n =
348 {
349 \bool_set_true:N \l_@@_use_hyperref_bool
350 \bool_set_true:N \l_@@_warn_hyperref_bool
351 } ,
352 hyperref / false .code:n =
353 {
354 \bool_set_false:N \l_@@_use_hyperref_bool
355 \bool_set_false:N \l_@@_warn_hyperref_bool
356 } ,
357 hyperref .initial:n = auto ,
358 hyperref .default:n = auto
359 }
360 % \end{macrocode}
361 % \end{variable}
362 %
363 % \begin{macrocode}
364 \AddToHook { begindocument }
365 {
366 \@ifpackageloaded { hyperref }
367 {
368 \bool_if:NT \l_@@_use_hyperref_bool
369 { \RequirePackage { zref-hyperref } }
370 }
371 {
372 \bool_if:NT \l_@@_warn_hyperref_bool
373 { \msg_warning:nn { zref-check } { missing-hyperref } }
374 \bool_set_false:N \l_@@_use_hyperref_bool
375 }
376 \keys_define:nn { zref-check/setup }
377 {
378 hyperref .code:n =
379 { \msg_warning:nn { zref-check } { hyperref-preamble-only } }
380 }
381 }
382 % \end{macrocode}
383 %
384 %
385 % \subsubsection*{\opt{msglevel} option}
386 %
387 % \begin{variable}{\l_@@_msglevel_tl}
388 % \begin{macrocode}
389 \tl_new:N \l_@@_msglevel_tl
390 \keys_define:nn { zref-check/setup }
391 {
392 msglevel .choice: ,
393 msglevel / warn .code:n =
394 { \tl_set:Nn \l_@@_msglevel_tl { warning } } ,
395 msglevel / info .code:n =
396 { \tl_set:Nn \l_@@_msglevel_tl { info } } ,
397 msglevel / none .code:n =
398 { \tl_set:Nn \l_@@_msglevel_tl { none } } ,
399 msglevel / infoifdraft .code:n =
400 {
401 \ifdraft
402 { \tl_set:Nn \l_@@_msglevel_tl { info } }
403 { \tl_set:Nn \l_@@_msglevel_tl { warning } }
404 } ,
405 msglevel / warniffinal .code:n =
406 {
407 \ifoptionfinal
408 { \tl_set:Nn \l_@@_msglevel_tl { warning } }
409 { \tl_set:Nn \l_@@_msglevel_tl { info } }
410 } ,
411 msglevel .value_required:n = true ,
412 msglevel .initial:n = warn ,
413 % \end{macrocode}
414 % \opt{ignore} and \opt{ok} are convenience aliases for \opt{msglevel=none},
415 % but only for use in the document body.
416 % \begin{macrocode}
417 ignore .code:n =
418 { \msg_warning:nnn { zref-check } { ignore-ok-document-only } { ignore } } ,
419 ignore .value_forbidden:n = true ,
420 ok .code:n =
421 { \msg_warning:nnn { zref-check } { ignore-ok-document-only } { ok } } ,
422 ok .value_forbidden:n = true ,
423 }
424 % \end{macrocode}
425 % \end{variable}
426 %
427 % \begin{macrocode}
428 \AddToHook { begindocument }
429 {
430 \keys_define:nn { zref-check/setup }
431 {
432 ignore .meta:n = { msglevel = none } ,
433 ok .meta:n = { msglevel = none } ,
434 }
435 }
436 % \end{macrocode}
437 %
438 %
439 % \subsubsection*{\opt{onpage} option}
440 %
441 % \begin{variable}{\l_@@_msgonpage_bool}
442 % \begin{macrocode}
443 \bool_new:N \l_@@_msgonpage_bool
444 \keys_define:nn { zref-check/setup }
445 {
446 onpage .choice: ,
447 onpage / labelseq .code:n =
448 {
449 \bool_set_false:N \l_@@_msgonpage_bool
450 } ,
451 onpage / msg .code:n =
452 {
453 \bool_set_true:N \l_@@_msgonpage_bool
454 } ,
455 onpage / labelseqifdraft .code:n =
456 {
457 \ifdraft
458 { \bool_set_false:N \l_@@_msgonpage_bool }
459 { \bool_set_true:N \l_@@_msgonpage_bool }
460 } ,
461 onpage / msgiffinal .code:n =
462 {
463 \ifoptionfinal
464 { \bool_set_true:N \l_@@_msgonpage_bool }
465 { \bool_set_false:N \l_@@_msgonpage_bool }
466 } ,
467 onpage .value_required:n = true ,
468 onpage .initial:n = labelseq
469 }
470 % \end{macrocode}
471 % \end{variable}
472 %
473 %
474 % \subsubsection*{\opt{closerange} option}
475 %
476 % \begin{variable}{\l_@@_close_range_int}
477 % \begin{macrocode}
478 \int_new:N \l_@@_close_range_int
479 \keys_define:nn { zref-check/setup }
480 {
481 closerange .code:n =
482 {
483 \@@_is_integer_rgx:nTF {#1}
484 { \int_set:Nn \l_@@_close_range_int { \int_eval:n {#1} } }
485 {
486 \msg_warning:nn { zref-check } { closerange-not-positive-integer }
487 \int_set:Nn \l_@@_close_range_int { 5 }
488 }
489 } ,
490 closerange .value_required:n = true ,
491 closerange .initial:n = 5
492 }
493 % \end{macrocode}
494 % \end{variable}
495 %
496 %
497 % \subsubsection*{Package options}
498 %
499 % \pkg{zref-check} does not accept load-time options. Despite the tradition
500 % of so doing, Joseph Wright has a point in recommending otherwise at
501 % \url{https://chat.stackexchange.com/transcript/message/60360822#60360822}:
502 % separating ``loading the package'' from ``configuring the package'' grants
503 % less trouble with ``option clashes'' and with expansion of options at
504 % load-time.
505 % \begin{macrocode}
506 \bool_lazy_and:nnT
507 { \tl_if_exist_p:c { opt@ zref-check.sty } }
508 { ! \tl_if_empty_p:c { opt@ zref-check.sty } }
509 { \msg_warning:nn { zref-check } { load-time-options } }
510 % \end{macrocode}
511 %
512 %
513 % \begin{macro}[int]{\zrefchecksetup}
514 % Provide \cs{zrefchecksetup}.
515 % \begin{macrocode}
516 \NewDocumentCommand \zrefchecksetup { m }
517 { \keys_set:nn { zref-check/setup } {#1} }
518 % \end{macrocode}
519 % \end{macro}
520 %
521 %
522 %
523 % \subsection{Position on page}
524 %
525 % Method for determining relative position within the page: the sequence in
526 % which the labels get shipped out, inferred from the sequence in which the
527 % labels occur in the \file{.aux} file.
528 %
529 % Some relevant info about the sequence of things:
530 % \url{https://tex.stackexchange.com/a/120978} and \texttt{texdoc lthooks},
531 % section ``Hooks provided by |\begin{document}|''.
532 %
533 %
534 % One first attempt at this was to use \cs{zref@newlabel}, which is the macro
535 % in which \pkg{zref} stores the label information in the aux file. When the
536 % \file{.aux} file is read at the beginning of the compilation, this macro is
537 % expanded for each of the labels. So, by redefining this macro we can feed a
538 % variable (a L3 sequence), and then do what it usually does, which is to
539 % define each label with the internal macro \cs{@newl@bel}, when the
540 % \file{.aux} file is read.
541 %
542 % Patching this macro for this is not possible. First, \cs{zref@newlabel} is
543 % one of those ``commands that look ahead'' mentioned in \pkg{ltcmdhooks}
544 % documentation. Indeed, \cs{@newl@bel} receives 3 arguments, and
545 % \cs{zref@newlabel} just passes the first, the following two will be scanned
546 % ahead. Second, the \pkg{ltcmdhooks} hooks are not actually available when
547 % the \file{.aux} file is read, they come only after |\begin{document}|.
548 % Hence, redefinition would be the only alternative. My attempts at this
549 % ended up registered at \url{https://tex.stackexchange.com/a/604744}. But
550 % the best result in these lines was:
551 %
552 % \begin{verbatim}
553 % \ZREF@Robust\edef\zref@newlabel#1{
554 % \noexpand\seq_gput_right:Nn \noexpand\g__zrefcheck_auxfile_lblseq_seq {#1}
555 % \noexpand\@newl@bel{\ZREF@RefPrefix}{#1}
556 % }
557 % \end{verbatim}
558 %
559 %
560 % However, better than the above is to just read it from the \file{.aux} file
561 % directly, which relieves us from hacking into any internals. That's what
562 % David Carlisle's answer at \url{https://tex.stackexchange.com/a/147705}
563 % does. This answer has actually been converted into the package
564 % \pkg{listlbls} by Norbert Melzer, but it is made to work with regular
565 % labels, not with \pkg{zref}'s. And it also does not really expose the
566 % information in a retrievable way (as far as I can tell). So, the below is
567 % adapted from Carlisle's answer's technique (a poor man's version of it...).
568 %
569 % There is some subtlety here as to whether this approach makes it safe for us
570 % to read the labels at this point without \cs{zref@wrapper@babel}. The
571 % common wisdom is that babel's shorthands are only active after
572 % |\begin{document}| (e.g., \url{https://tex.stackexchange.com/a/98897}).
573 % Alas, it is more complicated than that. Babel's documentation says (in
574 % section 9.5 Shorthands): ``To prevent problems with the loading of other
575 % packages after babel we reset the catcode of the character to the original
576 % one at the end of the package and of each language file (except with
577 % KeepShorthandsActive). It is re-activate[d] again at |\begin{document}|.
578 % We also need to make sure that the shorthands are active during the
579 % processing of the \file{.aux} file. Otherwise some citations may give
580 % unexpected results in the printout when a shorthand was used in the optional
581 % argument of |\bibitem| for example.'' This is done with
582 % |\if@filesw \immediate\write\@mainaux{...}|. In other words, the
583 % catcode change is written in the \file{.aux} file itself! Indeed, if you
584 % inspect the file, you'll find them there. Besides, there is still the
585 % ominous ``except with KeepShorthandsActive''.
586 %
587 % However, the \emph{method} we're using here is not quite the same as the
588 % usual run of the \file{.aux} file, because we're actively discarding the
589 % lines for which the first token is not equal to \cs{zref@newlabel}. I have
590 % tested the famous sensitive case for this: \pkg{babel} \opt{french} and
591 % labels with colons. And things worked as expected. Well, \emph{if}
592 % \opt{KeepShorthandsActive} is enabled \emph{with \opt{french}} and we load
593 % the package \emph{after babel} things do break, but not quite because of the
594 % colons in the labels. Even \pkg{siunitx} breaks in the same
595 % conditions\dots{}
596 %
597 % For reference: About what are valid characters for use in labels:
598 % \url{https://tex.stackexchange.com/a/18312}. About some problems with
599 % active colons: \url{https://tex.stackexchange.com/a/89470}. About the
600 % difference between L3 strings and token lists, see
601 % \url{https://tex.stackexchange.com/a/446381}, in particular Joseph Wright's
602 % comment: ``Strings are for data that will never be typeset, for example file
603 % names, identifiers, etc.: if the material may be used in typesetting, it
604 % should be a token list.'' See also moewe's (CW) answer in the same lines.
605 % Which suggests using L3 strings for the reference labels might be a good
606 % catch all approach, and possibly more robust. David Carlisle's comment
607 % about \pkg{inputenc} and how the strings work is a caveat (see
608 % \url{https://tex.stackexchange.com/q/446123#comment1516961_446381}, thanks
609 % David Carlisle). Still\dots{} let's stick to tradition as long as it works,
610 % \pkg{zref} already does a great job in this regard anyway.
611 %
612 %
613 % \begin{variable}{\g_@@_auxfile_lblseq_prop}
614 % \begin{macrocode}
615 \prop_new:N \g_@@_auxfile_lblseq_prop
616 % \end{macrocode}
617 % \end{variable}
618 %
619 % \begin{macrocode}
620 \tl_gset:Nn \g_@@_tmpa_tl { \c_sys_jobname_str .aux }
621 \file_if_exist:nT { \g_@@_tmpa_tl }
622 {
623 % \end{macrocode}
624 % Retrieve the information from the \file{.aux} file, and store it in a
625 % property list, so that the sequence can be retrieved in key-value fashion.
626 % \begin{macrocode}
627 \ior_open:Nn \g_@@_tmpa_ior { \g_@@_tmpa_tl }
628 \group_begin:
629 \int_zero:N \l_@@_tmpa_int
630 \tl_clear:N \l_@@_tmpa_tl
631 \tl_clear:N \l_@@_tmpb_tl
632 \bool_set_false:N \l_@@_tmpa_bool
633 \ior_map_variable:NNn \g_@@_tmpa_ior \l_@@_tmpa_tl
634 {
635 \tl_map_variable:NNn \l_@@_tmpa_tl \l_@@_tmpb_tl
636 {
637 \tl_if_eq:NnTF \l_@@_tmpb_tl { \zref@newlabel }
638 {
639 % \end{macrocode}
640 % Found a \cs{zref@label}, signal it.
641 % \begin{macrocode}
642 \bool_set_true:N \l_@@_tmpa_bool
643 }
644 {
645 \bool_if:NTF \l_@@_tmpa_bool
646 {
647 \bool_set_false:N \l_@@_tmpa_bool
648 \int_incr:N \l_@@_tmpa_int
649 \prop_gput:Nee \g_@@_auxfile_lblseq_prop
650 { \l_@@_tmpb_tl }
651 { \int_use:N \l_@@_tmpa_int }
652 }
653 {
654 % \end{macrocode}
655 % If there is not a match of the first token with \cs{zref@newlabel}, break
656 % the loop and discard the rest of the line, to ensure no babel calls to
657 % \cs{catcode} in the \file{.aux} file get expanded. This also breaks the
658 % loop and discards the rest of the \cs{zref@newlabel} lines after we got the
659 % label we wanted, since we reset \cs{l_@@_tmpa_bool} in the \texttt{T}
660 % branch.
661 % \begin{macrocode}
662 \tl_map_break:
663 }
664 }
665 }
666 }
667 \group_end:
668 \ior_close:N \g_@@_tmpa_ior
669 }
670 % \end{macrocode}
671 %
672 %
673 %
674 % The alternate method I had considered (more than that...) for this was using
675 % yx coordinates supplied by \pkg{zref}'s \pkg{savepos} module. However, this
676 % approach brought in a number of complexities, including the need to patch
677 % either \cs{zref@label} or \cs{ZREF@label}. In addition, the technique was
678 % at the bottom fundamentally flawed. Ulrike Fischer was very much right when
679 % she said that ``structure and position are two different beasts''
680 % (\url{https://github.com/ho-tex/zref/issues/12#issuecomment-880022576}). It
681 % is true that the checks based on it behaved decently, in normal
682 % circumstances, and except for outrageous label placement by the user, it
683 % would return the expected results. We don't really need exact coordinates
684 % to decide ``above/below''. Besides, it would do an exact job for the
685 % dedicated target macros of this package. It is also true that the ``page''
686 % for \cs{pageref} is stored with the value of where the \cs{label} is placed,
687 % wherever that may be. However, I could not conceive a situation where the
688 % \texttt{yx} criterion would perform clearly better than the
689 % \texttt{labelseq} one. And, if that's the case, and considering the
690 % complications it brings, this check was a slippery slope. All in all, I've
691 % decided to drop it.
692 %
693 % There's an interesting answer by David Carlisle at
694 % \url{https://tex.stackexchange.com/a/419189} to decide whether to typeset
695 % ``above'' or ``below'' using a method which essentially boils down to
696 % ``position in the \file{.aux} file''.
697 %
698 %
699 %
700 % \subsection{Counter}
701 %
702 % We need a dedicated counter for the labels generated by the checks and
703 % targets. The value of the counter is not relevant, we just need it to be
704 % able to set proper anchors with \cs{refstepcounter}. And, since I couldn't
705 % find a \cs{refstepcounter} equivalent in L3, we use a standard 2e counter
706 % here. I'm also using the technique to ensure the counter is never reset
707 % that is used by \file{zref-abspage.sty} and \cs{zref@require@unique}.
708 % Indeed, the requirements are the same, we need numbers ensured to be
709 % \emph{unique} in the counter.
710 %
711 % \begin{macrocode}
712 \begingroup
713 \let \@addtoreset \ltx@gobbletwo
714 \newcounter { zrefcheck }
715 \endgroup
716 \setcounter { zrefcheck } { 0 }
717 % \end{macrocode}
718 %
719 %
720 %
721 % \subsection{Label formats}
722 %
723 % \begin{macro}{\@@_check_lblfmt:n}
724 % \begin{syntax}
725 % \cs{@@_check_lblfmt:n} \Arg{check id int}
726 % \end{syntax}
727 % \begin{macrocode}
728 \cs_new:Npn \@@_check_lblfmt:n #1 { zrefcheck@ \int_use:N #1 }
729 % \end{macrocode}
730 % \end{macro}
731 %
732 % \begin{macro}{\@@_end_lblfmt:n}
733 % \begin{syntax}
734 % \cs{@@_end_lblfmt:n} \Arg{label}
735 % \end{syntax}
736 % \begin{macrocode}
737 \cs_new:Npn \@@_end_lblfmt:n #1 { #1 @zrefcheck }
738 % \end{macrocode}
739 % \end{macro}
740 %
741 %
742 %
743 % \subsection{Property values}
744 %
745 %
746 % \begin{macro}[int]{\zrefcheck_get_astl:nnn}
747 % A convenience function to retrieve property values from labels. Uses
748 % \cs{g_@@_auxfile_lblseq_prop} for \texttt{lblseq}, and calls
749 % \cs{zref@extractdefault} for everything else.
750 %
751 % We cannot use the ``return value'' of \cs{@@_get_astl:nnn} or
752 % \cs{@@_get_asint:nnn} directly, because we need to use the retrieved
753 % property values as arguments in the checks, however we use here a number
754 % of non-expandable operations. Hence, we receive a local \texttt{tl/int}
755 % variable as third argument and set that, so that it is available (and
756 % expandable) at the place of use, and also make these functions `protected'
757 % (see egreg's \url{https://tex.stackexchange.com/a/572903}: ``a function
758 % that performs assignments should be \texttt{protected}''). For this
759 % reason, we do not group here, because we are passing a local variable
760 % around, but it is expected this function will be called within a group.
761 %
762 % We're returning \cs{c_empty_tl} in case of failure to find the intended
763 % property value (explicitly in \cs{zref@extractdefault}, but that is also
764 % what \cs{tl_clear:N} does).
765 %
766 % \begin{syntax}
767 % \cs{zrefcheck_get_astl:nnn} \Arg{label} \Arg{prop} \Arg{tl var}
768 % \end{syntax}
769 % \begin{macrocode}
770 \cs_new_protected:Npn \zrefcheck_get_astl:nnn #1#2#3
771 {
772 \tl_clear:N #3
773 \tl_if_eq:nnTF {#2} { lblseq }
774 {
775 \prop_get:NnNF \g_@@_auxfile_lblseq_prop {#1} #3
776 {
777 \msg_warning:nnnn { zref-check }
778 { property-not-in-label } {#1} {#2}
779 }
780 }
781 {
782 % \end{macrocode}
783 % There are three things we need to check to ensure the information we are
784 % trying to retrieve here exists: the existence of \Arg{label}, the existence
785 % of \Arg{prop}, and whether the particular label being queried actually
786 % contains the property. If that's all in place, the value is passed to the
787 % checks, and it's their responsibility to verify the consistency of this
788 % value.
789 %
790 % The existence of the label is an user facing issue, and a warning for this
791 % is placed in \cs{@@_zcheck:nnnnn} (and done with \cs{zref@refused}). We do
792 % check here though for definition with \cs{zref@ifrefundefined} and silently
793 % do nothing if it is undefined, to reduce irrelevant warnings in a fresh
794 % compilation round. The other two are more ``internal'' problems, either
795 % some problem with the checks, or with the configuration of \pkg{zref} for
796 % their consumption.
797 % \begin{macrocode}
798 \zref@ifrefundefined {#1}
799 {}
800 {
801 \zref@ifpropundefined {#2}
802 { \msg_warning:nnnn { zref-check } { property-undefined } {#2} }
803 {
804 \zref@ifrefcontainsprop {#1} {#2}
805 {
806 \exp_args:NNNo \exp_args:NNo \tl_set:Nn #3
807 { \zref@extractdefault {#1} {#2} { \c_empty_tl } }
808 }
809 {
810 \msg_warning:nnnn
811 { zref-check } { property-not-in-label } {#1} {#2}
812 }
813 }
814 }
815 }
816 }
817 % \end{macrocode}
818 % \end{macro}
819 %
820 %
821 % \begin{variable}{\l_@@_integer_bool}
822 % \cs{zrefcheck_get_asint:nnn} is a very convenient wrapper around the more
823 % general \cs{zrefcheck_get_astl:nnn}, since almost always we'll be wanting
824 % to compare numbers in the checks. However, it is quite hard for it to
825 % ensure an integer is \emph{always} returned in the case of errors. And
826 % those do occur, even in a well structured document (e.g., in a first round
827 % of compilation). To complicate things, the L3 integer predicates are
828 % \emph{very} sensitive to receiving any other kind of data, and they
829 % \emph{scream}. To handle this \cs{zrefcheck_get_asint:nnn} uses
830 % \cs{l_@@_integer_bool} to signal if an integer could not be returned. To
831 % use this function always set \cs{l_@@_integer_bool} to true first, then
832 % call it as much as you need. If any of these calls got is returning
833 % anything which is not an integer, \cs{l_@@_integer_bool} will have been
834 % set to false, and you should check that this hasn't happened before
835 % actually comparing the integers (\cs{bool_lazy_and:nnTF} is your friend).
836 % \begin{macrocode}
837 \bool_new:N \l_@@_integer_bool
838 % \end{macrocode}
839 % \end{variable}
840 %
841 % \begin{variable}{\l_@@_propval_tl}
842 % \begin{macrocode}
843 \tl_new:N \l_@@_propval_tl
844 % \end{macrocode}
845 % \end{variable}
846 %
847 % \begin{macro}[int]{\zrefcheck_get_asint:nnn}
848 % \begin{syntax}
849 % \cs{zrefcheck_get_asint:nnn} \Arg{label} \Arg{prop} \Arg{int var}
850 % \end{syntax}
851 % \begin{macrocode}
852 \cs_new_protected:Npn \zrefcheck_get_asint:nnn #1#2#3
853 {
854 \zrefcheck_get_astl:nnn {#1} {#2} { \l_@@_propval_tl }
855 \@@_is_integer:nTF { \l_@@_propval_tl }
856 {
857 % \end{macrocode}
858 % Make it an integer data type.
859 % \begin{macrocode}
860 \int_set:Nn #3 { \int_eval:n { \l_@@_propval_tl } }
861 }
862 {
863 \bool_set_false:N \l_@@_integer_bool
864 \zref@ifrefundefined {#1}
865 % \end{macrocode}
866 % Keep silent if ref is undefined to reduce irrelevant warnings in a fresh
867 % compilation round. Again, this is also not the point to check for undefined
868 % references, that's a task for \cs{@@_zcheck:nnnnn}.
869 % \begin{macrocode}
870 { }
871 {
872 \msg_warning:nnnn { zref-check }
873 { property-not-integer } {#2} {#1}
874 }
875 }
876 }
877 % \end{macrocode}
878 % \end{macro}
879 %
880 %
881 %
882 %
883 % \section{User interface}
884 %
885 %
886 % \subsection{\cs{zcheck}}
887 %
888 % \begin{macro}[int]{\zcheck}
889 % The \marg{text} argument of \cs{zcheck} should not be long, since
890 % \cs{hyperlink} cannot receive a long argument. Besides, there is no
891 % reason for it to be. Note, also, that hyperlinks crossing page boundaries
892 % have some known issues: \url{https://tex.stackexchange.com/a/182769},
893 % \url{https://tex.stackexchange.com/a/54607},
894 % \url{https://tex.stackexchange.com/a/179907}.
895 %
896 % \begin{syntax}
897 % \cs{zcheck}\meta{*}\oarg{checks/options}\marg{labels}\marg{text}
898 % \end{syntax}
899 %
900 % \begin{macrocode}
901 \NewDocumentCommand \zcheck { s O { } m m }
902 { \zref@wrapper@babel \@@_zcheck:nnnn {#3} {#1} {#2} {#4} }
903 % \end{macrocode}
904 % \end{macro}
905 %
906 %
907 % \begin{variable}
908 % {
909 % \l_@@_zcheck_labels_seq ,
910 % \g_@@_id_int ,
911 % \l_@@_checkbeg_tl ,
912 % \l_@@_link_label_tl ,
913 % \l_@@_link_anchor_tl ,
914 % \l_@@_link_star_bool
915 % }
916 % \begin{macrocode}
917 \seq_new:N \l_@@_zcheck_labels_seq
918 \int_new:N \g_@@_id_int
919 \tl_new:N \l_@@_checkbeg_tl
920 \tl_new:N \l_@@_link_label_tl
921 \tl_new:N \l_@@_link_anchor_tl
922 \bool_new:N \l_@@_link_star_bool
923 % \end{macrocode}
924 % \end{variable}
925 %
926 % \begin{macro}{\@@_zcheck:nnnn}
927 % An intermediate internal function, which does the actual heavy lifting,
928 % and places \Arg{labels} as first argument, so that it can be protected by
929 % \cs{zref@wrapper@babel} in \cs{zcheck}. This is the same procedure as the
930 % one used in the definition of \cs{zref} in \file{zref-user.sty} for
931 % protection of \pkg{babel} active characters.
932 %
933 % \begin{syntax}
934 % \cs{@@_zcheck:nnnn} \Arg{labels} \Arg{*} \Arg{checks/options} \Arg{text}
935 % \end{syntax}
936 %
937 % \begin{macrocode}
938 \cs_new_protected:Npn \@@_zcheck:nnnn #1#2#3#4
939 {
940 \group_begin:
941 % \end{macrocode}
942 % Process local options and checks. We use \cs{seq_set_split:Nnn} to set
943 % \cs{l_@@_zcheck_labels_seq} -- instead of \cs{seq_set_from_clist:Nn} -- to
944 % support empty labels.
945 % \begin{macrocode}
946 \keys_set:nn { zref-check/zcheck } {#3}
947 \seq_set_split:Nnn \l_@@_zcheck_labels_seq { , } {#1}
948 % \end{macrocode}
949 % Names of the labels for this zcheck call.
950 % \begin{macrocode}
951 \int_gincr:N \g_@@_id_int
952 \tl_set:Ne \l_@@_checkbeg_tl
953 { \@@_check_lblfmt:n { \g_@@_id_int } }
954 % \end{macrocode}
955 % Set checkbeg label.
956 % \begin{macrocode}
957 \zref@labelbylist { \l_@@_checkbeg_tl } { zrefcheck-check }
958 % \end{macrocode}
959 % Typeset \marg{text}, with hyperlink when appropriate. Even though the first
960 % argument can receive a list of labels, there is no meaningful way to set
961 % links to multiple targets. Hence, only the first one is considered for
962 % hyperlinking.
963 % \begin{macrocode}
964 \seq_get:NN \l_@@_zcheck_labels_seq \l_@@_link_label_tl
965 \bool_set:Nn \l_@@_link_star_bool {#2}
966 \zref@ifrefundefined { \l_@@_link_label_tl }
967 % \end{macrocode}
968 % If the reference is undefined, just typeset.
969 % \begin{macrocode}
970 {#4}
971 {
972 \bool_if:nTF
973 {
974 \l_@@_use_hyperref_bool &&
975 ! \l_@@_link_star_bool
976 }
977 {
978 \exp_args:Ne \zrefcheck_get_astl:nnn
979 { \l_@@_link_label_tl }
980 { anchor } { \l_@@_link_anchor_tl }
981 \hyperlink { \l_@@_link_anchor_tl } {#4}
982 }
983 {#4}
984 }
985 % \end{macrocode}
986 % Set checkend label.
987 % \begin{macrocode}
988 \bool_if:NT \l_@@_zcheck_end_label_bool
989 {
990 \zref@labelbylist
991 { \@@_end_lblfmt:n { \l_@@_checkbeg_tl } }
992 { zrefcheck-end }
993 }
994 % \end{macrocode}
995 % Check if \meta{labels} are defined.
996 % \begin{macrocode}
997 \seq_map_inline:Nn \l_@@_zcheck_labels_seq
998 { \tl_if_empty:nF {##1} { \zref@refused {##1} } }
999 % \end{macrocode}
1000 % Run the checks.
1001 % \begin{macrocode}
1002 \@@_run_checks:nne { \l_@@_zcheck_checks_seq }
1003 { \l_@@_zcheck_labels_seq } { \l_@@_checkbeg_tl }
1004 \group_end:
1005 }
1006 % \end{macrocode}
1007 % \end{macro}
1008 %
1009 %
1010 % \subsection{Targets}
1011 %
1012 % \begin{macro}[int]{\zctarget}
1013 % \begin{syntax}
1014 % \cs{zctarget}\marg{label}\marg{text}
1015 % \end{syntax}
1016 % \begin{macrocode}
1017 \NewDocumentCommand \zctarget { m +m }
1018 {
1019 % \end{macrocode}
1020 % Group contents of \cs{zctarget} to avoid leaking the effects of
1021 % \cs{refstepcounter} over \cs{@currentlabel}. The same care is not needed
1022 % for \texttt{zcregion}, since the environment is already grouped.
1023 % \begin{macrocode}
1024 \group_begin:
1025 \refstepcounter { zrefcheck }
1026 \zref@wrapper@babel \zref@label {#1}
1027 #2
1028 \tl_if_empty:nF {#2}
1029 {
1030 \zref@wrapper@babel
1031 \zref@labelbylist { \@@_end_lblfmt:n {#1} } { zrefcheck-end }
1032 }
1033 \group_end:
1034 }
1035 % \end{macrocode}
1036 % \end{macro}
1037 %
1038 % \begin{macro}[int]{zcregion}
1039 % \begin{syntax}
1040 % |\begin{zcregion}|\marg{label}
1041 % | ...|
1042 % |\end{zcregion}|
1043 % \end{syntax}
1044 % \begin{macrocode}
1045 \NewDocumentEnvironment {zcregion} { m }
1046 {
1047 \refstepcounter { zrefcheck }
1048 \zref@wrapper@babel \zref@label {#1}
1049 }
1050 {
1051 \zref@wrapper@babel
1052 \zref@labelbylist { \@@_end_lblfmt:n {#1} } { zrefcheck-end }
1053 }
1054 % \end{macrocode}
1055 % \end{macro}
1056 %
1057 %
1058 %
1059 % \section{Checks}
1060 %
1061 % What is needed define a \pkg{zref-check} check?
1062 %
1063 % First, a conditional function defined with:
1064 %
1065 % \cs{prg_new_protected_conditional:Npnn} \cs{@@_check_\meta{check}:nn} |#1#2 { F }|
1066 %
1067 % \noindent where \meta{check} is the name of the check, the first argument is
1068 % the \Arg{label} and the second the \Arg{reference}. The existence of the
1069 % check is verified by the existence of the function with this name-scheme
1070 % (and signatures). As usual, this function must return either
1071 % \cs{prg_return_true:} or \cs{prg_return_false:}. Of course, you can define
1072 % other variants if you need them internally, it is just that what the package
1073 % does expect and verifies is the existence of the \texttt{:nnF} variant.
1074 %
1075 % Note that the naming convention of the checks adopts the perspective of the
1076 % \meta{reference}. That is, the ``before'' check should return true if the
1077 % \meta{label} occurs before the ``reference''.
1078 %
1079 % The check conditionals are expected to retrieve \pkg{zref}'s label
1080 % information with \cs{zrefcheck_get_astl:nnn} or
1081 % \cs{zrefcheck_get_asint:nnn}. Also, technically speaking, the
1082 % \meta{reference} argument is also a label, actually a pair of them, as set
1083 % by \cs{zcheck}. For the ``labels'', any \pkg{zref} property in \pkg{zref}'s
1084 % main list is available, the ``references'' store the properties in the
1085 % \texttt{zrefcheck} list. Besides those, there is also the \texttt{lblseq}
1086 % (fake) property (for either ``labels'' or ``references''), stored in
1087 % \cs{g_@@_auxfile_lblseq_prop}.
1088 %
1089 % Second, the required properties of labels and references must be duly
1090 % registered for \pkg{zref}. This can be done with \cs{zref@newprop},
1091 % \cs{zref@addprop} and friends, as usual.
1092 %
1093 % Third, the check must be registered as a key which gets setup in
1094 % \cs{zcheck} by the \texttt{ zref-check / zcheck } key set.
1095 %
1096 % Fourth, if the check requires only a single label to work, it should be
1097 % registered in \cs{c_@@_single_label_checks_seq}.
1098 %
1099 %
1100 % \subsection{Single label checks}
1101 %
1102 %
1103 % Some checks do not require an ``end label'' in \cs{zcheck}, notably the
1104 % sectioning ones, which don't rely on page boundaries. Hence, in case
1105 % \cs{zcheck} only calls checks in this set, we can spare the setting of the
1106 % end label.
1107 %
1108 % \begin{variable}{\c_@@_single_label_checks_seq}
1109 % \begin{macrocode}
1110 \seq_const_from_clist:Nn \c_@@_single_label_checks_seq
1111 {
1112 thischap ,
1113 prevchap ,
1114 nextchap ,
1115 chapsbefore ,
1116 chapsafter ,
1117 thissec ,
1118 prevsec ,
1119 nextsec ,
1120 secsbefore ,
1121 secsafter ,
1122 manual ,
1123 }
1124 % \end{macrocode}
1125 % \end{variable}
1126 %
1127 %
1128 %
1129 % \subsection{Setup}
1130 %
1131 % \begin{variable}{\l_@@_zcheck_checks_seq,\l_@@_end_label_required_bool}
1132 % \begin{macrocode}
1133 \seq_new:N \l_@@_zcheck_checks_seq
1134 \bool_new:N \l_@@_zcheck_end_label_bool
1135 % \end{macrocode}
1136 % \end{variable}
1137 %
1138 %
1139 % First, we inherit all the main options into the keys of \texttt{zref-check /
1140 % zcheck}. See \url{https://github.com/latex3/latex3/issues/1254}.
1141 % ^^A zref-check/zcheck
1142 % \begin{macrocode}
1143 \keys_define:nn { zref-check } { zcheck .inherit:n = zref-check/setup }
1144 % \end{macrocode}
1145 %
1146 % Then we add the checks to it.
1147 % \begin{macrocode}
1148 \clist_map_inline:nn
1149 {
1150 thispage ,
1151 prevpage ,
1152 nextpage ,
1153 facing ,
1154 otherpage ,
1155 pagegap ,
1156 above ,
1157 below ,
1158 pagesbefore ,
1159 ppbefore ,
1160 pagesafter ,
1161 ppafter ,
1162 before ,
1163 after ,
1164 thischap ,
1165 prevchap ,
1166 nextchap ,
1167 chapsbefore ,
1168 chapsafter ,
1169 thissec ,
1170 prevsec ,
1171 nextsec ,
1172 secsbefore ,
1173 secsafter ,
1174 close ,
1175 far ,
1176 manual ,
1177 }
1178 {
1179 \keys_define:nn { zref-check/zcheck }
1180 {
1181 #1 .code:n =
1182 {
1183 \seq_put_right:Nn \l_@@_zcheck_checks_seq {#1}
1184 \seq_if_in:NnF \c_@@_single_label_checks_seq {#1}
1185 { \bool_set_true:N \l_@@_zcheck_end_label_bool }
1186 } ,
1187 #1 .value_forbidden:n = true ,
1188 }
1189 }
1190 % \end{macrocode}
1191 %
1192 %
1193 %
1194 % \subsection{Running}
1195 %
1196 % \begin{macro}{\@@_run_checks:nnn}
1197 % \begin{syntax}
1198 % \cs{@@_run_checks:nnn} \Arg{checks} \Arg{labels} \Arg{reference}
1199 % \end{syntax}
1200 % \meta{checks} are expected to be received as a sequence variable.
1201 % \begin{macrocode}
1202 \cs_new_protected:Npn \@@_run_checks:nnn #1#2#3
1203 {
1204 \group_begin:
1205 \seq_map_inline:Nn #2
1206 {
1207 \seq_if_empty:NTF #1
1208 { \@@_message:nnnn { no-checks } { } { } { } }
1209 {
1210 \seq_map_inline:Nn #1
1211 { \@@_do_check:nnn {####1} {##1} {#3} }
1212 }
1213 }
1214 \group_end:
1215 }
1216 \cs_generate_variant:Nn \@@_run_checks:nnn { nne }
1217 % \end{macrocode}
1218 % \end{macro}
1219 %
1220 %
1221 % \begin{variable}
1222 % {
1223 % \l_@@_passedcheck_bool ,
1224 % \l_@@_onpage_bool ,
1225 % \l_@@_empty_label_bool ,
1226 % \c_@@_onpage_checks_seq
1227 % }
1228 % \begin{macrocode}
1229 \bool_new:N \l_@@_passedcheck_bool
1230 \bool_new:N \l_@@_onpage_bool
1231 \bool_new:N \l_@@_empty_label_bool
1232 \seq_const_from_clist:Nn \c_@@_onpage_checks_seq
1233 { above , below , before , after }
1234 % \end{macrocode}
1235 % \end{variable}
1236 %
1237 %
1238 % Variant not provided by \pkg{expl3}.
1239 % \begin{macrocode}
1240 \cs_generate_variant:Nn \exp_args:Nnno { Nnoo }
1241 % \end{macrocode}
1242 %
1243 % \begin{macro}{\@@_do_check:nnn}
1244 % \begin{syntax}
1245 % \cs{@@_do_check:nnn} \Arg{check} \Arg{label beg} \Arg{reference beg}
1246 % \end{syntax}
1247 % \begin{macrocode}
1248 \cs_new_protected:Npn \@@_do_check:nnn #1#2#3
1249 {
1250 \group_begin:
1251 \bool_set_true:N \l_@@_passedcheck_bool
1252 \bool_set_false:N \l_@@_onpage_bool
1253 \bool_set_false:N \l_@@_empty_label_bool
1254 \cs_if_exist:cTF { @@_check_ #1 :nnF }
1255 {
1256 % \end{macrocode}
1257 % \meta{label beg} may be defined or not, it is arbitrary user input. Whether
1258 % this is the case is checked in \cs{@@_zcheck:nnnnn}, and due warning already
1259 % ensues. So there's no need to do it again here. The only exception is the
1260 % case of empty labels, for which we want to issue a failed check warning.
1261 % \begin{macrocode}
1262 \zref@ifrefundefined {#2}
1263 {
1264 \tl_if_empty:nT {#2}
1265 {
1266 \bool_set_false:N \l_@@_passedcheck_bool
1267 \bool_set_true:N \l_@@_empty_label_bool
1268 }
1269 }
1270 {
1271 % ``label beg'' vs ``reference beg''.
1272 \use:c { @@_check_ #1 :nnF }
1273 {#2} {#3}
1274 { \bool_set_false:N \l_@@_passedcheck_bool }
1275 % ``reference end'' \emph{may} exist or not depending on the
1276 % checks.
1277 \zref@ifrefundefined { \@@_end_lblfmt:n {#3} }
1278 {
1279 % ``label end'' \emph{may} have been created by the
1280 % target commands.
1281 \zref@ifrefundefined { \@@_end_lblfmt:n {#2} }
1282 {}
1283 {
1284 % ``label end'' vs ``reference beg''.
1285 \exp_args:Nno \use:c { @@_check_ #1 :nnF }
1286 { \@@_end_lblfmt:n {#2} } {#3}
1287 { \bool_set_false:N \l_@@_passedcheck_bool }
1288 }
1289 }
1290 {
1291 % ``label beg'' vs ``reference end''.
1292 \exp_args:Nnno \use:c { @@_check_ #1 :nnF }
1293 {#2} { \@@_end_lblfmt:n {#3} }
1294 { \bool_set_false:N \l_@@_passedcheck_bool }
1295 % ``label end'' \emph{may} have been created by the
1296 % target commands.
1297 \zref@ifrefundefined { \@@_end_lblfmt:n {#2} }
1298 {}
1299 {
1300 % ``label end'' vs ``reference beg''.
1301 \exp_args:Nno \use:c { @@_check_ #1 :nnF }
1302 { \@@_end_lblfmt:n {#2} } {#3}
1303 { \bool_set_false:N \l_@@_passedcheck_bool }
1304 % ``label end'' vs ``reference end''.
1305 \exp_args:Nnoo \use:c { @@_check_ #1 :nnF }
1306 { \@@_end_lblfmt:n {#2} }
1307 { \@@_end_lblfmt:n {#3} }
1308 { \bool_set_false:N \l_@@_passedcheck_bool }
1309 }
1310 }
1311 % \end{macrocode}
1312 % Handle option \opt{onpage=msg}. This is only granted for tests which
1313 % perform ``within this page'' checks (\opt{above}, \opt{below}, \opt{before},
1314 % \opt{after}) \emph{and} if any of the two by two checks uses a ``within this
1315 % page'' comparison. If both conditions are met, signal.
1316 % \begin{macrocode}
1317 \seq_if_in:NnT \c_@@_onpage_checks_seq {#1}
1318 {
1319 \@@_check_thispage:nnT
1320 {#2} {#3}
1321 { \bool_set_true:N \l_@@_onpage_bool }
1322 \zref@ifrefundefined { \@@_end_lblfmt:n {#3} }
1323 {
1324 \zref@ifrefundefined { \@@_end_lblfmt:n {#2} }
1325 {}
1326 {
1327 \@@_check_thispage:nnT
1328 { \@@_end_lblfmt:n {#2} } {#3}
1329 { \bool_set_true:N \l_@@_onpage_bool }
1330 }
1331 }
1332 {
1333 \@@_check_thispage:nnT
1334 {#2} { \@@_end_lblfmt:n {#3} }
1335 { \bool_set_true:N \l_@@_onpage_bool }
1336 \zref@ifrefundefined { \@@_end_lblfmt:n {#2} }
1337 {}
1338 {
1339 \@@_check_thispage:nnT
1340 { \@@_end_lblfmt:n {#2} } {#3}
1341 { \bool_set_true:N \l_@@_onpage_bool }
1342 \@@_check_thispage:nnT
1343 { \@@_end_lblfmt:n {#2} }
1344 { \@@_end_lblfmt:n {#3} }
1345 { \bool_set_true:N \l_@@_onpage_bool }
1346 }
1347 }
1348 }
1349 }
1350 }
1351 { \msg_warning:nnn { zref-check } { check-missing } {#1} }
1352 \bool_if:NTF \l_@@_passedcheck_bool
1353 {
1354 \bool_if:nT
1355 {
1356 \l_@@_msgonpage_bool &&
1357 \l_@@_onpage_bool
1358 }
1359 {
1360 \@@_message:nnne { double-check } {#1} {#2}
1361 { \zref@extractdefault {#3} {page} {'unknown'} }
1362 }
1363 }
1364 {
1365 \bool_if:NTF \l_@@_empty_label_bool
1366 { \@@_message:nnnn { empty-label } {#1} { } { } }
1367 {
1368 \@@_message:nnne { check-failed } {#1} {#2}
1369 { \zref@extractdefault {#3} {page} {'unknown'} }
1370 }
1371 }
1372 \group_end:
1373 }
1374 \cs_generate_variant:Nn \@@_do_check:nnn { nnV }
1375 % \end{macrocode}
1376 % \end{macro}
1377 %
1378 %
1379 % \subsection{Conditionals}
1380 %
1381 % \begin{variable}
1382 % {
1383 % \l_@@_lbl_int ,
1384 % \l_@@_ref_int ,
1385 % \l_@@_lbl_b_int ,
1386 % \l_@@_ref_b_int
1387 % }
1388 % More readable scratch variables for the tests.
1389 % \begin{macrocode}
1390 \int_new:N \l_@@_lbl_int
1391 \int_new:N \l_@@_ref_int
1392 \int_new:N \l_@@_lbl_b_int
1393 \int_new:N \l_@@_ref_b_int
1394 % \end{macrocode}
1395 % \end{variable}
1396 %
1397 %
1398 % \subsubsection{This page}
1399 %
1400 % \begin{macro}{\@@_check_thispage:nn, \@@_check_otherpage:nn}
1401 % \begin{macrocode}
1402 \prg_new_protected_conditional:Npnn \@@_check_thispage:nn #1#2 { T , F , TF }
1403 {
1404 \group_begin:
1405 \bool_set_true:N \l_@@_integer_bool
1406 \zrefcheck_get_asint:nnn {#1} { abspage } { \l_@@_lbl_int }
1407 \zrefcheck_get_asint:nnn {#2} { abspage } { \l_@@_ref_int }
1408 \bool_lazy_and:nnTF
1409 { \l_@@_integer_bool }
1410 {
1411 \int_compare_p:nNn
1412 { \l_@@_lbl_int } = { \l_@@_ref_int } &&
1413 % \end{macrocode}
1414 % `0' is the default value of \texttt{abspage}, but this value should not
1415 % happen normally for this property, since even the first page, after it gets
1416 % shipped out, will receive value `1'. So, if we do find `0' here, better
1417 % signal something is wrong. This comment extends to all page number checks.
1418 % \begin{macrocode}
1419 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1420 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1421 }
1422 { \group_insert_after:N \prg_return_true: }
1423 { \group_insert_after:N \prg_return_false: }
1424 \group_end:
1425 }
1426 \prg_new_protected_conditional:Npnn \@@_check_otherpage:nn #1#2 { T , F , TF }
1427 {
1428 \@@_check_thispage:nnTF {#1} {#2}
1429 { \prg_return_false: }
1430 { \prg_return_true: }
1431 }
1432 % \end{macrocode}
1433 % \end{macro}
1434 %
1435 %
1436 % \subsubsection{On page}
1437 %
1438 % \begin{macro}{\@@_check_above:nn, \@@_check_below:nn}
1439 % \begin{macrocode}
1440 \prg_new_protected_conditional:Npnn \@@_check_above:nn #1#2 { F , TF }
1441 {
1442 \group_begin:
1443 \@@_check_thispage:nnTF {#1} {#2}
1444 {
1445 \bool_set_true:N \l_@@_integer_bool
1446 \zrefcheck_get_asint:nnn {#1} { lblseq } { \l_@@_lbl_int }
1447 \zrefcheck_get_asint:nnn {#2} { lblseq } { \l_@@_ref_int }
1448 \bool_lazy_and:nnTF
1449 { \l_@@_integer_bool }
1450 {
1451 \int_compare_p:nNn
1452 { \l_@@_lbl_int } < { \l_@@_ref_int } &&
1453 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1454 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1455 }
1456 { \group_insert_after:N \prg_return_true: }
1457 { \group_insert_after:N \prg_return_false: }
1458 }
1459 { \group_insert_after:N \prg_return_false: }
1460 \group_end:
1461 }
1462 \prg_new_protected_conditional:Npnn \@@_check_below:nn #1#2 { F , TF }
1463 {
1464 \@@_check_thispage:nnTF {#1} {#2}
1465 {
1466 \@@_check_above:nnTF {#1} {#2}
1467 { \prg_return_false: }
1468 { \prg_return_true: }
1469 }
1470 { \prg_return_false: }
1471 }
1472 % \end{macrocode}
1473 % \end{macro}
1474 %
1475 %
1476 % \subsubsection{Before / After}
1477 %
1478 % \begin{macro}{\@@_check_before:nn, \@@_check_after:nn}
1479 % \begin{macrocode}
1480 \prg_new_protected_conditional:Npnn \@@_check_before:nn #1#2 { F }
1481 {
1482 \@@_check_pagesbefore:nnTF {#1} {#2}
1483 { \prg_return_true: }
1484 {
1485 \@@_check_above:nnTF {#1} {#2}
1486 { \prg_return_true: }
1487 { \prg_return_false: }
1488 }
1489 }
1490 \prg_new_protected_conditional:Npnn \@@_check_after:nn #1#2 { F }
1491 {
1492 \@@_check_pagesafter:nnTF {#1} {#2}
1493 { \prg_return_true: }
1494 {
1495 \@@_check_below:nnTF {#1} {#2}
1496 { \prg_return_true: }
1497 { \prg_return_false: }
1498 }
1499 }
1500 % \end{macrocode}
1501 % \end{macro}
1502 %
1503 %
1504 % \subsubsection{Pages}
1505 %
1506 % \begin{macro}
1507 % {
1508 % \@@_check_nextpage:nn ,
1509 % \@@_check_prevpage:nn ,
1510 % \@@_check_pagesbefore:nn ,
1511 % \@@_check_ppbefore:nn ,
1512 % \@@_check_pagesafter:nn ,
1513 % \@@_check_ppafter:nn ,
1514 % \@@_check_pagegap:nn ,
1515 % \@@_check_facing:nn
1516 % }
1517 % \begin{macrocode}
1518 \prg_new_protected_conditional:Npnn \@@_check_nextpage:nn #1#2 { F }
1519 {
1520 \group_begin:
1521 \bool_set_true:N \l_@@_integer_bool
1522 \zrefcheck_get_asint:nnn {#1} { abspage } { \l_@@_lbl_int }
1523 \zrefcheck_get_asint:nnn {#2} { abspage } { \l_@@_ref_int }
1524 \bool_lazy_and:nnTF
1525 { \l_@@_integer_bool }
1526 {
1527 \int_compare_p:nNn
1528 { \l_@@_lbl_int } = { \l_@@_ref_int + 1 } &&
1529 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1530 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1531 }
1532 { \group_insert_after:N \prg_return_true: }
1533 { \group_insert_after:N \prg_return_false: }
1534 \group_end:
1535 }
1536 \prg_new_protected_conditional:Npnn \@@_check_prevpage:nn #1#2 { F }
1537 {
1538 \group_begin:
1539 \bool_set_true:N \l_@@_integer_bool
1540 \zrefcheck_get_asint:nnn {#1} { abspage } { \l_@@_lbl_int }
1541 \zrefcheck_get_asint:nnn {#2} { abspage } { \l_@@_ref_int }
1542 \bool_lazy_and:nnTF
1543 { \l_@@_integer_bool }
1544 {
1545 \int_compare_p:nNn
1546 { \l_@@_lbl_int } = { \l_@@_ref_int - 1 } &&
1547 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1548 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1549 }
1550 { \group_insert_after:N \prg_return_true: }
1551 { \group_insert_after:N \prg_return_false: }
1552 \group_end:
1553 }
1554 \prg_new_protected_conditional:Npnn \@@_check_pagesbefore:nn #1#2 { F , TF }
1555 {
1556 \group_begin:
1557 \bool_set_true:N \l_@@_integer_bool
1558 \zrefcheck_get_asint:nnn {#1} { abspage } { \l_@@_lbl_int }
1559 \zrefcheck_get_asint:nnn {#2} { abspage } { \l_@@_ref_int }
1560 \bool_lazy_and:nnTF
1561 { \l_@@_integer_bool }
1562 {
1563 \int_compare_p:nNn
1564 { \l_@@_lbl_int } < { \l_@@_ref_int } &&
1565 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1566 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1567 }
1568 { \group_insert_after:N \prg_return_true: }
1569 { \group_insert_after:N \prg_return_false: }
1570 \group_end:
1571 }
1572 \cs_new_eq:NN \@@_check_ppbefore:nnF \@@_check_pagesbefore:nnF
1573 \prg_new_protected_conditional:Npnn \@@_check_pagesafter:nn #1#2 { F , TF }
1574 {
1575 \group_begin:
1576 \bool_set_true:N \l_@@_integer_bool
1577 \zrefcheck_get_asint:nnn {#1} { abspage } { \l_@@_lbl_int }
1578 \zrefcheck_get_asint:nnn {#2} { abspage } { \l_@@_ref_int }
1579 \bool_lazy_and:nnTF
1580 { \l_@@_integer_bool }
1581 {
1582 \int_compare_p:nNn
1583 { \l_@@_lbl_int } > { \l_@@_ref_int } &&
1584 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1585 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1586 }
1587 { \group_insert_after:N \prg_return_true: }
1588 { \group_insert_after:N \prg_return_false: }
1589 \group_end:
1590 }
1591 \cs_new_eq:NN \@@_check_ppafter:nnF \@@_check_pagesafter:nnF
1592 \prg_new_protected_conditional:Npnn \@@_check_pagegap:nn #1#2 { F }
1593 {
1594 \group_begin:
1595 \bool_set_true:N \l_@@_integer_bool
1596 \zrefcheck_get_asint:nnn {#1} { abspage } { \l_@@_lbl_int }
1597 \zrefcheck_get_asint:nnn {#2} { abspage } { \l_@@_ref_int }
1598 \bool_lazy_and:nnTF
1599 { \l_@@_integer_bool }
1600 {
1601 \int_compare_p:nNn
1602 { \int_abs:n { \l_@@_lbl_int - \l_@@_ref_int } } > { 1 } &&
1603 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1604 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1605 }
1606 { \group_insert_after:N \prg_return_true: }
1607 { \group_insert_after:N \prg_return_false: }
1608 \group_end:
1609 }
1610 \prg_new_protected_conditional:Npnn \@@_check_facing:nn #1#2 { F }
1611 {
1612 \group_begin:
1613 \bool_set_true:N \l_@@_integer_bool
1614 \zrefcheck_get_asint:nnn {#1} { abspage } { \l_@@_lbl_int }
1615 \zrefcheck_get_asint:nnn {#2} { abspage } { \l_@@_ref_int }
1616 \bool_lazy_and:nnTF
1617 { \l_@@_integer_bool }
1618 {
1619 % \end{macrocode}
1620 % There exists no ``facing'' page if the document is not twoside.
1621 % \begin{macrocode}
1622 \legacy_if_p:n { @twoside } &&
1623 % \end{macrocode}
1624 % Now we test ``facing''.
1625 % \begin{macrocode}
1626 (
1627 (
1628 \int_if_odd_p:n { \l_@@_ref_int } &&
1629 \int_compare_p:nNn
1630 { \l_@@_lbl_int } = { \l_@@_ref_int - 1 }
1631 ) ||
1632 (
1633 \int_if_even_p:n { \l_@@_ref_int } &&
1634 \int_compare_p:nNn
1635 { \l_@@_lbl_int } = { \l_@@_ref_int + 1 }
1636 )
1637 ) &&
1638 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1639 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1640 }
1641 { \group_insert_after:N \prg_return_true: }
1642 { \group_insert_after:N \prg_return_false: }
1643 \group_end:
1644 }
1645 % \end{macrocode}
1646 % \end{macro}
1647 %
1648 %
1649 % \subsubsection{Close / Far}
1650 %
1651 % \begin{macro}{\@@_check_close:nn, \@@_check_far:nn}
1652 % \begin{macrocode}
1653 \prg_new_protected_conditional:Npnn \@@_check_close:nn #1#2 { F , TF }
1654 {
1655 \group_begin:
1656 \bool_set_true:N \l_@@_integer_bool
1657 \zrefcheck_get_asint:nnn {#1} { abspage } { \l_@@_lbl_int }
1658 \zrefcheck_get_asint:nnn {#2} { abspage } { \l_@@_ref_int }
1659 \bool_lazy_and:nnTF
1660 { \l_@@_integer_bool }
1661 {
1662 \int_compare_p:nNn
1663 { \int_abs:n { \l_@@_lbl_int - \l_@@_ref_int } }
1664 <
1665 { \l_@@_close_range_int + 1 } &&
1666 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1667 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1668 }
1669 { \group_insert_after:N \prg_return_true: }
1670 { \group_insert_after:N \prg_return_false: }
1671 \group_end:
1672 }
1673 \prg_new_protected_conditional:Npnn \@@_check_far:nn #1#2 { F }
1674 {
1675 \@@_check_close:nnTF {#1} {#2}
1676 { \prg_return_false: }
1677 { \prg_return_true: }
1678 }
1679 % \end{macrocode}
1680 % \end{macro}
1681 %
1682 %
1683 % \subsubsection{Chapter}
1684 %
1685 % \begin{macro}
1686 % {
1687 % \@@_check_thischap:nn ,
1688 % \@@_check_nextchap:nn ,
1689 % \@@_check_prevchap:nn ,
1690 % \@@_check_chapsafter:nn ,
1691 % \@@_check_chapsbefore:nn
1692 % }
1693 % \begin{macrocode}
1694 \prg_new_protected_conditional:Npnn \@@_check_thischap:nn #1#2 { F }
1695 {
1696 \group_begin:
1697 \bool_set_true:N \l_@@_integer_bool
1698 \zrefcheck_get_asint:nnn {#1} { zc@abschap } { \l_@@_lbl_int }
1699 \zrefcheck_get_asint:nnn {#2} { zc@abschap } { \l_@@_ref_int }
1700 \bool_lazy_and:nnTF
1701 { \l_@@_integer_bool }
1702 {
1703 \int_compare_p:nNn
1704 { \l_@@_lbl_int } = { \l_@@_ref_int } &&
1705 % \end{macrocode}
1706 % `0' is the default value of \texttt{zc@abschap} property, and means here no
1707 % \cs{chapter} has yet been issued, therefore it cannot be ``this chapter'',
1708 % nor ``the next chapter'', nor ``the previous chapter'', it is just ``no
1709 % chapter''. Note, however, that a statement about a ``future'' chapter does
1710 % not require the ``current'' one to exist. This comment extends to all
1711 % chapter checks.
1712 % \begin{macrocode}
1713 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1714 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1715 }
1716 { \group_insert_after:N \prg_return_true: }
1717 { \group_insert_after:N \prg_return_false: }
1718 \group_end:
1719 }
1720 \prg_new_protected_conditional:Npnn \@@_check_nextchap:nn #1#2 { F }
1721 {
1722 \group_begin:
1723 \bool_set_true:N \l_@@_integer_bool
1724 \zrefcheck_get_asint:nnn {#1} { zc@abschap } { \l_@@_lbl_int }
1725 \zrefcheck_get_asint:nnn {#2} { zc@abschap } { \l_@@_ref_int }
1726 \bool_lazy_and:nnTF
1727 { \l_@@_integer_bool }
1728 {
1729 \int_compare_p:nNn
1730 { \l_@@_lbl_int } = { \l_@@_ref_int + 1 } &&
1731 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 }
1732 }
1733 { \group_insert_after:N \prg_return_true: }
1734 { \group_insert_after:N \prg_return_false: }
1735 \group_end:
1736 }
1737 \prg_new_protected_conditional:Npnn \@@_check_prevchap:nn #1#2 { F }
1738 {
1739 \group_begin:
1740 \bool_set_true:N \l_@@_integer_bool
1741 \zrefcheck_get_asint:nnn {#1} { zc@abschap } { \l_@@_lbl_int }
1742 \zrefcheck_get_asint:nnn {#2} { zc@abschap } { \l_@@_ref_int }
1743 \bool_lazy_and:nnTF
1744 { \l_@@_integer_bool }
1745 {
1746 \int_compare_p:nNn
1747 { \l_@@_lbl_int } = { \l_@@_ref_int - 1 } &&
1748 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1749 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1750 }
1751 { \group_insert_after:N \prg_return_true: }
1752 { \group_insert_after:N \prg_return_false: }
1753 \group_end:
1754 }
1755 \prg_new_protected_conditional:Npnn \@@_check_chapsafter:nn #1#2 { F }
1756 {
1757 \group_begin:
1758 \bool_set_true:N \l_@@_integer_bool
1759 \zrefcheck_get_asint:nnn {#1} { zc@abschap } { \l_@@_lbl_int }
1760 \zrefcheck_get_asint:nnn {#2} { zc@abschap } { \l_@@_ref_int }
1761 \bool_lazy_and:nnTF
1762 { \l_@@_integer_bool }
1763 {
1764 \int_compare_p:nNn
1765 { \l_@@_lbl_int } > { \l_@@_ref_int } &&
1766 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 }
1767 }
1768 { \group_insert_after:N \prg_return_true: }
1769 { \group_insert_after:N \prg_return_false: }
1770 \group_end:
1771 }
1772 \prg_new_protected_conditional:Npnn \@@_check_chapsbefore:nn #1#2 { F }
1773 {
1774 \group_begin:
1775 \bool_set_true:N \l_@@_integer_bool
1776 \zrefcheck_get_asint:nnn {#1} { zc@abschap } { \l_@@_lbl_int }
1777 \zrefcheck_get_asint:nnn {#2} { zc@abschap } { \l_@@_ref_int }
1778 \bool_lazy_and:nnTF
1779 { \l_@@_integer_bool }
1780 {
1781 \int_compare_p:nNn
1782 { \l_@@_lbl_int } < { \l_@@_ref_int } &&
1783 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1784 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1785 }
1786 { \group_insert_after:N \prg_return_true: }
1787 { \group_insert_after:N \prg_return_false: }
1788 \group_end:
1789 }
1790 % \end{macrocode}
1791 % \end{macro}
1792 %
1793 %
1794 % \subsubsection{Section}
1795 %
1796 % \begin{macro}
1797 % {
1798 % \@@_check_thissec:nn ,
1799 % \@@_check_nextsec:nn ,
1800 % \@@_check_prevsec:nn ,
1801 % \@@_check_secsafter:nn ,
1802 % \@@_check_secsbefore:nn
1803 % }
1804 % \begin{macrocode}
1805 \prg_new_protected_conditional:Npnn \@@_check_thissec:nn #1#2 { F }
1806 {
1807 \group_begin:
1808 \bool_set_true:N \l_@@_integer_bool
1809 \zrefcheck_get_asint:nnn {#1} { zc@abssec } { \l_@@_lbl_int }
1810 \zrefcheck_get_asint:nnn {#2} { zc@abssec } { \l_@@_ref_int }
1811 \zrefcheck_get_asint:nnn {#1} { zc@abschap } { \l_@@_lbl_b_int }
1812 \zrefcheck_get_asint:nnn {#2} { zc@abschap } { \l_@@_ref_b_int }
1813 \bool_lazy_and:nnTF
1814 { \l_@@_integer_bool }
1815 {
1816 \int_compare_p:nNn
1817 { \l_@@_lbl_b_int } = { \l_@@_ref_b_int } &&
1818 \int_compare_p:nNn
1819 { \l_@@_lbl_int } = { \l_@@_ref_int } &&
1820 % \end{macrocode}
1821 % `0' is the default value of \texttt{zc@abssec} property, and means here no
1822 % \cs{section} has yet been issued since its counter has been reset, which
1823 % occurs at the beginning of the document and at every chapter. Hence, as is
1824 % the case for chapters, `0' is just ``not a section''. The same observation
1825 % about the need of the ``current'' section to exist to be able to refer to a
1826 % ``future'' one also holds. This comment extends to all section checks.
1827 % \begin{macrocode}
1828 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1829 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1830 }
1831 { \group_insert_after:N \prg_return_true: }
1832 { \group_insert_after:N \prg_return_false: }
1833 \group_end:
1834 }
1835 \prg_new_protected_conditional:Npnn \@@_check_nextsec:nn #1#2 { F }
1836 {
1837 \group_begin:
1838 \bool_set_true:N \l_@@_integer_bool
1839 \zrefcheck_get_asint:nnn {#1} { zc@abssec } { \l_@@_lbl_int }
1840 \zrefcheck_get_asint:nnn {#2} { zc@abssec } { \l_@@_ref_int }
1841 \zrefcheck_get_asint:nnn {#1} { zc@abschap } { \l_@@_lbl_b_int }
1842 \zrefcheck_get_asint:nnn {#2} { zc@abschap } { \l_@@_ref_b_int }
1843 \bool_lazy_and:nnTF
1844 { \l_@@_integer_bool }
1845 {
1846 \int_compare_p:nNn
1847 { \l_@@_lbl_b_int } = { \l_@@_ref_b_int } &&
1848 \int_compare_p:nNn
1849 { \l_@@_lbl_int } = { \l_@@_ref_int + 1 } &&
1850 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 }
1851 }
1852 { \group_insert_after:N \prg_return_true: }
1853 { \group_insert_after:N \prg_return_false: }
1854 \group_end:
1855 }
1856 \prg_new_protected_conditional:Npnn \@@_check_prevsec:nn #1#2 { F }
1857 {
1858 \group_begin:
1859 \bool_set_true:N \l_@@_integer_bool
1860 \zrefcheck_get_asint:nnn {#1} { zc@abssec } { \l_@@_lbl_int }
1861 \zrefcheck_get_asint:nnn {#2} { zc@abssec } { \l_@@_ref_int }
1862 \zrefcheck_get_asint:nnn {#1} { zc@abschap } { \l_@@_lbl_b_int }
1863 \zrefcheck_get_asint:nnn {#2} { zc@abschap } { \l_@@_ref_b_int }
1864 \bool_lazy_and:nnTF
1865 { \l_@@_integer_bool }
1866 {
1867 \int_compare_p:nNn
1868 { \l_@@_lbl_b_int } = { \l_@@_ref_b_int } &&
1869 \int_compare_p:nNn
1870 { \l_@@_lbl_int } = { \l_@@_ref_int - 1 } &&
1871 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1872 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1873 }
1874 { \group_insert_after:N \prg_return_true: }
1875 { \group_insert_after:N \prg_return_false: }
1876 \group_end:
1877 }
1878 \prg_new_protected_conditional:Npnn \@@_check_secsafter:nn #1#2 { F }
1879 {
1880 \group_begin:
1881 \bool_set_true:N \l_@@_integer_bool
1882 \zrefcheck_get_asint:nnn {#1} { zc@abssec } { \l_@@_lbl_int }
1883 \zrefcheck_get_asint:nnn {#2} { zc@abssec } { \l_@@_ref_int }
1884 \zrefcheck_get_asint:nnn {#1} { zc@abschap } { \l_@@_lbl_b_int }
1885 \zrefcheck_get_asint:nnn {#2} { zc@abschap } { \l_@@_ref_b_int }
1886 \bool_lazy_and:nnTF
1887 { \l_@@_integer_bool }
1888 {
1889 \int_compare_p:nNn
1890 { \l_@@_lbl_b_int } = { \l_@@_ref_b_int } &&
1891 \int_compare_p:nNn
1892 { \l_@@_lbl_int } > { \l_@@_ref_int } &&
1893 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 }
1894 }
1895 { \group_insert_after:N \prg_return_true: }
1896 { \group_insert_after:N \prg_return_false: }
1897 \group_end:
1898 }
1899 \prg_new_protected_conditional:Npnn \@@_check_secsbefore:nn #1#2 { F }
1900 {
1901 \group_begin:
1902 \bool_set_true:N \l_@@_integer_bool
1903 \zrefcheck_get_asint:nnn {#1} { zc@abssec } { \l_@@_lbl_int }
1904 \zrefcheck_get_asint:nnn {#2} { zc@abssec } { \l_@@_ref_int }
1905 \zrefcheck_get_asint:nnn {#1} { zc@abschap } { \l_@@_lbl_b_int }
1906 \zrefcheck_get_asint:nnn {#2} { zc@abschap } { \l_@@_ref_b_int }
1907 \bool_lazy_and:nnTF
1908 { \l_@@_integer_bool }
1909 {
1910 \int_compare_p:nNn
1911 { \l_@@_lbl_b_int } = { \l_@@_ref_b_int } &&
1912 \int_compare_p:nNn
1913 { \l_@@_lbl_int } < { \l_@@_ref_int } &&
1914 ! \int_compare_p:nNn { \l_@@_lbl_int } = { 0 } &&
1915 ! \int_compare_p:nNn { \l_@@_ref_int } = { 0 }
1916 }
1917 { \group_insert_after:N \prg_return_true: }
1918 { \group_insert_after:N \prg_return_false: }
1919 \group_end:
1920 }
1921 % \end{macrocode}
1922 % \end{macro}
1923 %
1924 %
1925 %
1926 % \subsubsection{Manual}
1927 %
1928 % \begin{macro}{ \@@_check_manual:nn }
1929 % \begin{macrocode}
1930 \prg_new_protected_conditional:Npnn \@@_check_manual:nn #1#2 { F }
1931 { \prg_return_false: }
1932 % \end{macrocode}
1933 % \end{macro}
1934 %
1935 %
1936 %
1937 % \section{\pkg{zref-clever} integration}
1938 %
1939 %
1940 % There are four tasks \pkg{zref-clever} needs to do, in order to offer
1941 % integration with \pkg{zref-check} from the options of \cs{zcref}: i) set the
1942 % ``beg label''; ii) set the checks options; iii) run the checks; iv)
1943 % (possibly) set the ``end label''. Since `ii)' can be done directly by
1944 % running |\keys_set:nn { zref-check/zcheck }| on the options received, we
1945 % provide convenience functions for the other three tasks.
1946 %
1947 %
1948 % \begin{macro}
1949 % {
1950 % \zrefcheck_zcref_beg_label: ,
1951 % \zrefcheck_zcref_end_label_maybe: ,
1952 % \zrefcheck_zcref_run_checks_on_labels:n
1953 % }
1954 % \begin{macrocode}
1955 \cs_new_protected:Npn \zrefcheck_zcref_beg_label:
1956 {
1957 \int_gincr:N \g_@@_id_int
1958 \tl_set:Ne \l_@@_checkbeg_tl
1959 { \@@_check_lblfmt:n { \g_@@_id_int } }
1960 \zref@labelbylist { \l_@@_checkbeg_tl } { zrefcheck-check }
1961 }
1962 \cs_new_protected:Npn \zrefcheck_zcref_end_label_maybe:
1963 {
1964 \bool_if:NT \l_@@_zcheck_end_label_bool
1965 {
1966 \zref@labelbylist
1967 { \@@_end_lblfmt:n { \l_@@_checkbeg_tl } }
1968 { zrefcheck-end }
1969 }
1970 }
1971 \cs_new_protected:Npn \zrefcheck_zcref_run_checks_on_labels:n #1
1972 {
1973 \@@_run_checks:nne
1974 { \l_@@_zcheck_checks_seq } {#1} { \l_@@_checkbeg_tl }
1975 }
1976 % \end{macrocode}
1977 % \end{macro}
1978 %
1979 %
1980 %
1981 % \section{\pkg{zref-vario} integration}
1982 %
1983 %
1984 % \begin{macro}
1985 % {
1986 % \zrefcheck_zrefvario_label: ,
1987 % \zrefcheck_zrefvario_run_check_on_label:n
1988 % }
1989 % \begin{macrocode}
1990 \cs_new_protected:Npn \zrefcheck_zrefvario_label:
1991 {
1992 \int_gincr:N \g_@@_id_int
1993 \tl_set:Ne \l_@@_checkbeg_tl
1994 { \@@_check_lblfmt:n { \g_@@_id_int } }
1995 \zref@labelbylist { \l_@@_checkbeg_tl } { zrefcheck-zrefvario }
1996 }
1997 \cs_new_protected:Npn \zrefcheck_zrefvario_run_check_on_label:nn #1#2
1998 { \@@_do_check:nnV {#1} {#2} \l_@@_checkbeg_tl }
1999 \cs_generate_variant:Nn \zrefcheck_zrefvario_run_check_on_label:nn { Vn }
2000 % \end{macrocode}
2001 % \end{macro}
2002 %
2003 %
2004 % \begin{macrocode}
2005 %</package>
2006 % \end{macrocode}
2007 %
2008 % \PrintIndex
2009 %