Debian Codegraph @

texmf-dist/source/latex/postnotes/postnotes.dtx

raw
1 % \iffalse meta-comment
2 %
3 % File: postnotes.dtx
4 %
5 % This file is part of the LaTeX package "postnotes".
6 %
7 % Copyright (C) 2022-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 postnotes.dtx,
23 % postnotes.ins,
24 % postnotes-doc.tex,
25 % postnotes-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/postnotes
35 %
36 % for those people who are interested.
37 %
38 % -----------------------------------------------------------------------
39 %
40 % \fi
41 %
42 % \iffalse
43 %<*driver>
44 \documentclass{l3doc}
45
46 % Have \GetFileInfo pick up date and version data and used in the
47 % documentation.
48 \usepackage{postnotes}
49
50 \begin{document}
51
52 \DocInput{postnotes.dtx}
53
54 \end{document}
55 %</driver>
56 %
57 % \fi
58 %
59 % \DoNotIndex{\\}
60 %
61 % \NewDocumentCommand\githubissue{m}{^^A
62 % issue~\href{https://github.com/gusbrs/postnotes/issues/#1}{\##1}}
63 %
64 % \NewDocumentCommand\githubPR{m}{^^A
65 % PR~\href{https://github.com/gusbrs/postnotes/pull/#1}{\##1}}
66 %
67 % \NewDocumentCommand\contributor{m}{#1}
68 % \NewDocumentCommand\username{m}{`\texttt{#1}'}
69 %
70 % \NewDocumentCommand\opt{m}{\texttt{#1}}
71 %
72 % \pdfstringdefDisableCommands{^^A
73 % \def\opt#1{#1}
74 % }
75 %
76 % \AddToHook{env/macro/after}{\medskip{}}
77 % \AddToHook{env/variable/after}{\medskip{}}
78 % \AddToHook{env/function/after}{\medskip{}}
79 %
80 %
81 % ^^A Have the Index at 'section' level rather than 'part'. Otherwise it is
82 % ^^A just the same definition from 'l3doc.cls'.
83 % \IndexPrologue{^^A
84 % \section*{Index}
85 % \markboth{Index}{Index}
86 % \addcontentsline{toc}{section}{Index}
87 % The italic numbers denote the pages where the corresponding entry is
88 % described, numbers underlined point to the definition, all others indicate
89 % the places where it is used.^^A
90 % }
91 %
92 %
93 % \GetFileInfo{postnotes.sty}
94 %
95 % \title{^^A
96 % The \pkg{postnotes} package^^A
97 % \texorpdfstring{\\{}\medskip{}}{ - }^^A
98 % Code documentation^^A
99 % \texorpdfstring{\medskip{}}{}^^A
100 % }
101 %
102 % \author{^^A
103 % \texorpdfstring{\texttt{gusbrs}\\[0.8em]
104 % \url{https://github.com/gusbrs/postnotes}\\
105 % \url{https://www.ctan.org/pkg/postnotes}}{gusbrs}}
106 %
107 % \date{Version \fileversion\ -- \filedate}
108 %
109 % \maketitle
110 %
111 %
112 % \tableofcontents
113 %
114 %
115 % \clearpage{}
116 %
117 % \section{Initial setup}
118 % Start the \pkg{DocStrip} guards.
119 % \begin{macrocode}
120 %<*package>
121 % \end{macrocode}
122 %
123 % Identify the internal prefix (\LaTeX3 \pkg{DocStrip} convention).
124 % \begin{macrocode}
125 %<@@=postnotes>
126 % \end{macrocode}
127 %
128 %
129 % The new syntax for file/package hooks, which the package assumes, requires
130 % kernel 2021-11-15 (\texttt{ltnews34}, \texttt{ltfilehook}). Furthermore,
131 % the kernel of 2022-06-01 introduced a couple of very nice features which
132 % simplifies the relation with \pkg{hyperref} (\texttt{ltnews35},
133 % \texttt{hyperref-linktarget}): the provision of \cs{MakeLinkTarget} and the
134 % definition by the kernel of the starred version of \cs{ref}, which we can
135 % use regardless of \pkg{hyperref} being loaded. Also, since we followed the
136 % move to \texttt{e}-type expansion, to play safe we require the 2023-11-01
137 % kernel or newer. Finally, the tagging sockets and block code required for
138 % tagging support need the 2024-06-01 kernel.
139 %
140 % \begin{macrocode}
141 \def\postnotes@required@kernel{2024-06-01}
142 \NeedsTeXFormat{LaTeX2e}[\postnotes@required@kernel]
143 \providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
144 \IfFormatAtLeastTF{\postnotes@required@kernel}
145 {}
146 {%
147 \PackageError{postnotes}{LaTeX kernel too old}
148 {%
149 'postnotes' requires a LaTeX kernel \postnotes@required@kernel\space or newer.%
150 }%
151 }%
152 % \end{macrocode}
153 %
154 %
155 % \begin{macrocode}
156 \ProvidesExplPackage {postnotes} {2024-12-05} {0.5.1}
157 {Endnotes for LaTeX}
158 % \end{macrocode}
159 %
160 %
161 % \begin{macro}
162 % {
163 % \l_@@_tmpa_tl ,
164 % \l_@@_tmpb_tl ,
165 % \l_@@_tmpa_seq ,
166 % \l_@@_tmpb_seq ,
167 % \l_@@_tmpa_box ,
168 % }
169 % Temporary scratch variables.
170 % \begin{macrocode}
171 \tl_new:N \l_@@_tmpa_tl
172 \tl_new:N \l_@@_tmpb_tl
173 \seq_new:N \l_@@_tmpa_seq
174 \seq_new:N \l_@@_tmpb_seq
175 \box_new:N \l_@@_tmpa_box
176 % \end{macrocode}
177 % \end{macro}
178 %
179 %
180 % \section{Data}
181 %
182 %
183 % \begin{macro}[EXP]{\@@_data_name:n}
184 % Returns the name of the property list variable which stores the data of
185 % the \cs{postnote} with \meta{note id} number.
186 % \begin{syntax}
187 % \cs{@@_data_name:n} \Arg{note id}
188 % \end{syntax}
189 % \begin{macrocode}
190 \cs_new:Npn \@@_data_name:n #1
191 { g_@@_ #1 _data_prop }
192 \cs_generate_variant:Nn \@@_data_name:n { e }
193 % \end{macrocode}
194 % \end{macro}
195 %
196 %
197 % \pkg{postnotes} provides a number of hooks from the new hook system to grant
198 % some points of access in key places of the package. Note that hooks created
199 % with \cs{NewHook} are meant to be public interfaces (see
200 % \url{https://chat.stackexchange.com/transcript/message/62955941#62955941},
201 % and following discussion).
202 %
203 %
204 % \begin{macro}{\@@_store:nn}
205 % Stores the metadata and \meta{note content} of \cs{postnote} with ID
206 % \meta{note id}, from where it is called. The
207 % \texttt{postnotes/note/store} hook is intended to add further data to the
208 % note, when required to support packages with specific needs.
209 % \begin{syntax}
210 % \cs{@@_store:nn} \Arg{note id} \Arg{note content}
211 % \end{syntax}
212 % \begin{macrocode}
213 \NewHook { postnotes/note/store }
214 \cs_new_protected:Npn \@@_store:nn #1#2
215 {
216 \prop_new:c { \@@_data_name:e {#1} }
217 \prop_gput:cnn { \@@_data_name:e {#1} } { type } { note }
218 \prop_gput:cnV { \@@_data_name:e {#1} } { mark }
219 \l_@@_mark_tl
220 \prop_gput:cne { \@@_data_name:e {#1} } { counter }
221 { \int_use:N \c@postnote }
222 \prop_gput:cne { \@@_data_name:e {#1} } { sortnum }
223 {
224 \bool_if:NTF \l_@@_manual_sortnum_bool
225 { \fp_use:N \l_@@_sort_num_fp }
226 { \int_use:N \c@postnote }
227 }
228 \cs_if_exist:cT { chapter }
229 {
230 \protected@edef \l_@@_tmpa_tl { \thechapter }
231 \prop_gput:cnV { \@@_data_name:e {#1} }
232 { thechapter } \l_@@_tmpa_tl
233 }
234 \protected@edef \l_@@_tmpa_tl { \thesection }
235 \prop_gput:cnV { \@@_data_name:e {#1} } { thesection }
236 \l_@@_tmpa_tl
237 \prop_gput:cnV { \@@_data_name:e {#1} } { pnsectname }
238 \g_@@_section_name_tl
239 \prop_gput:cne { \@@_data_name:e {#1} } { pnsectid }
240 { \int_use:N \g_@@_sectid_int }
241 \prop_gput:cne { \@@_data_name:e {#1} } { multibool }
242 { \bool_to_str:N \l_@@_maybe_multi_bool }
243 \prop_gput:cnn { \@@_data_name:e {#1} } { content } {#2}
244 \tl_clear:N \l_@@_tmpa_tl
245 \UseHook { postnotes/note/store }
246 }
247 % \end{macrocode}
248 % \end{macro}
249 %
250 %
251 % \begin{macro}{\@@_store_section:nn}
252 % Stores the metadata and \meta{note content} of \cs{postnotesection} with
253 % ID \meta{note id}, from where it is called.
254 % \begin{syntax}
255 % \cs{@@_store_section:nn} \Arg{note id} \Arg{note content}
256 % \end{syntax}
257 % \begin{macrocode}
258 \cs_new_protected:Npn \@@_store_section:nn #1#2
259 {
260 \prop_new:c { \@@_data_name:e {#1} }
261 \prop_gput:cnn { \@@_data_name:e {#1} } { type } { section }
262 \cs_if_exist:cT { chapter }
263 {
264 \protected@edef \l_@@_tmpa_tl { \thechapter }
265 \prop_gput:cnV { \@@_data_name:e {#1} }
266 { thechapter } \l_@@_tmpa_tl
267 }
268 \protected@edef \l_@@_tmpa_tl { \thesection }
269 \prop_gput:cnV { \@@_data_name:e {#1} } { thesection }
270 \l_@@_tmpa_tl
271 \prop_gput:cnn { \@@_data_name:e {#1} } { content } {#2}
272 \tl_clear:N \l_@@_tmpa_tl
273 }
274 \cs_generate_variant:Nn \@@_store_section:nn { nV }
275 % \end{macrocode}
276 % \end{macro}
277 %
278 %
279 % \begin{macro}
280 % {
281 % \@@_prop_get:nnN ,
282 % \@@_prop_item:nn ,
283 % \@@_prop_gclear:n ,
284 % }
285 % Convenience functions to retrieve and clear data from a note based on the
286 % ID number.
287 % \begin{syntax}
288 % \cs{@@_prop_get:nnN} \Arg{note id} \Arg{property} \Arg{tl var to set}
289 % \cs{@@_prop_item:nn} \Arg{note id} \Arg{property}
290 % \cs{@@_prop_gclear:n} \Arg{note id}
291 % \end{syntax}
292 % \begin{macrocode}
293 \cs_new_protected:Npn \@@_prop_get:nnN #1#2#3
294 {
295 \prop_get:cnNF { \@@_data_name:e {#1} } {#2} #3
296 { \tl_clear:N #3 }
297 }
298 \cs_new:Npn \@@_prop_item:nn #1#2
299 { \prop_item:cn { \@@_data_name:e {#1} } {#2} }
300 \cs_new_protected:Npn \@@_prop_gclear:n #1
301 { \prop_gclear:c { \@@_data_name:e {#1} } }
302 % \end{macrocode}
303 % \end{macro}
304 %
305 %
306 % \begin{macro}[int]
307 % {
308 % \post@note ,
309 % \@@_store_labelseq:nn ,
310 % \@@_step_counteraux:nnn ,
311 % }
312 % \cs{post@note} is the \cs{newlabel} equivalent for \pkg{postnotes}.
313 % Based on the kernel's \cs{@newl@bel} so that we get \LaTeX{} checks for
314 % multiple and changed references for free (procedure learnt from
315 % \pkg{zref}). \cs{post@note}, when the \file{.aux} file is read, defines
316 % macros named \texttt{\textbackslash{}postnote@r@\meta{label
317 % type}@\meta{id}}, according to the prefix set by \cs{c_@@_ref_prefix_tl}.
318 % \cs{@@_store_labelseq:nn} is an auxiliary function to store the sequence
319 % of the labels in the \file{.aux} file, used to check for possible sorting
320 % problems due to floats. \cs{@@_step_counteraux:nnn} handles counter
321 % stepping and storing for the \opt{counteraux} option.
322 % \begin{syntax}
323 % \cs{post@note} \Arg{label type} \Arg{id} \Arg{label content (page)}
324 % ~~\Arg{counteraux step}
325 % \cs{@@_store_labelseq:nn} \Arg{label type} \Arg{id}
326 % \cs{@@_step_counteraux:nnn} \Arg{label type} \Arg{id}
327 % ~~\Arg{counteraux step}
328 % \end{syntax}
329 % \begin{macrocode}
330 \tl_const:Nn \c_@@_ref_prefix_tl { postnote@r }
331 \seq_new:N \g_@@_labelseq_seq
332 \int_new:N \g_@@_postnote_counteraux_int
333 \prop_new:N \g_@@_counteraux_prop
334 \bool_new:N \g_@@_firstrun_bool
335 \bool_gset_true:N \g_@@_firstrun_bool
336 \cs_new_protected:Npn \@@_store_labelseq:nn #1#2
337 { \seq_gput_right:Nn \g_@@_labelseq_seq { {#1} {#2} } }
338 \cs_new_protected:Npn \@@_step_counteraux:nnn #1#2#3
339 {
340 \bool_lazy_and:nnT
341 { \g_@@_counteraux_bool }
342 { \str_if_eq_p:nn {#1} { mark } }
343 {
344 \int_gadd:Nn \g_@@_postnote_counteraux_int { #3 }
345 \prop_gput:Nne \g_@@_counteraux_prop { #2 }
346 { \int_use:N \g_@@_postnote_counteraux_int }
347 }
348 }
349 \cs_new_protected:Npe \post@note #1#2#3#4
350 {
351 \exp_not:N \bool_gset_false:N \exp_not:N \g_@@_firstrun_bool
352 \exp_not:N \@@_store_labelseq:nn { #1 } { #2 }
353 \exp_not:N \@@_step_counteraux:nnn { #1 } { #2 } { #4 }
354 \exp_not:N \@newl@bel { \c_@@_ref_prefix_tl } { #1 @ #2 } { #3 }
355 }
356 % \end{macrocode}
357 % \end{macro}
358 %
359 % And ensure \cs{post@note}, \cs{postnote@setcounteraux}, and
360 % \cs{postnote@addtocounteraux} are defined in the \file{.aux} file. The
361 % hooks are the same used by \pkg{hyperref} for similar purpose.
362 %
363 % \begin{macrocode}
364 \AddToHook { begindocument }
365 {
366 \legacy_if:nT { @filesw }
367 {
368 \iow_now:Ne \@mainaux
369 {
370 \token_to_str:N \providecommand
371 \token_to_str:N \post@note [4] { }
372 }
373 \iow_now:Ne \@mainaux
374 {
375 \token_to_str:N \providecommand
376 \token_to_str:N \postnote@setcounteraux [1] { }
377 }
378 \iow_now:Ne \@mainaux
379 {
380 \token_to_str:N \providecommand
381 \token_to_str:N \postnote@addtocounteraux [1] { }
382 }
383 }
384 }
385 \AddToHook { include/before }
386 {
387 \legacy_if:nT { @filesw }
388 {
389 \iow_now:Ne \@mainaux
390 {
391 \token_to_str:N \providecommand
392 \token_to_str:N \post@note [4] { }
393 }
394 \iow_now:Ne \@mainaux
395 {
396 \token_to_str:N \providecommand
397 \token_to_str:N \postnote@setcounteraux [1] { }
398 }
399 \iow_now:Ne \@mainaux
400 {
401 \token_to_str:N \providecommand
402 \token_to_str:N \postnote@addtocounteraux [1] { }
403 }
404 }
405 }
406 % \end{macrocode}
407 %
408 %
409 % \begin{macro}
410 % {
411 % \@@_set_label:nnnn ,
412 % \@@_set_mark_page_label:nn ,
413 % \@@_set_section_page_label:n ,
414 % \@@_set_print_label:n ,
415 % }
416 % Label setting functions for each pertinent context. They must use
417 % \cs{iow_shipout_e:Nn}, since the main information we are interested in is
418 % the \texttt{page}.
419 % \begin{syntax}
420 % \cs{@@_set_label:nnnn} \Arg{label type} \Arg{note id} \Arg{value}
421 % ~~\Arg{counteraux step}
422 % \cs{@@_set_mark_page_label:nn} \Arg{note id} \Arg{counteraux step}
423 % \cs{@@_set_section_page_label:n} \Arg{note id}
424 % \cs{@@_set_print_label:n} \Arg{note id}
425 % \end{syntax}
426 % \begin{macrocode}
427 \cs_new_protected:Npn \@@_set_label:nnnn #1#2#3#4
428 {
429 \legacy_if:nT { @filesw }
430 {
431 \protected@write \@auxout { }
432 { \token_to_str:N \post@note { #1 } { #2 } { #3 } { #4 } }
433 }
434 }
435 \cs_new_protected:Npn \@@_set_mark_page_label:nn #1#2
436 { \@@_set_label:nnnn { mark } { #1 } { \thepage } { #2 } }
437 \cs_generate_variant:Nn \@@_set_mark_page_label:nn { ee }
438 \cs_new_protected:Npn \@@_set_section_page_label:n #1
439 { \@@_set_label:nnnn { section } { #1 } { \thepage } { } }
440 \cs_generate_variant:Nn \@@_set_section_page_label:n { e }
441 \cs_new_protected:Npn \@@_set_print_label:n #1
442 { \@@_set_label:nnnn { print } { #1 } { } { } }
443 \cs_generate_variant:Nn \@@_set_print_label:n { e }
444 % \end{macrocode}
445 % \end{macro}
446 %
447 %
448 % \begin{macro}
449 % {
450 % \@@_get_pageref:Nn ,
451 % \@@_extract_pageref:n ,
452 % }
453 % Reference data extraction functions.
454 % \begin{syntax}
455 % \cs{@@_get_pageref:Nn} \Arg{tl var to set} \Arg{label name}
456 % \cs{@@_extract_pageref:n} \Arg{label name}
457 % \end{syntax}
458 % \begin{macrocode}
459 \cs_new_protected:Npn \@@_get_pageref:Nn #1#2
460 {
461 \cs_if_exist:cTF { \c_@@_ref_prefix_tl @ #2 }
462 { \tl_set:Nv #1 { \c_@@_ref_prefix_tl @ #2 } }
463 { \tl_clear:N #1 }
464 }
465 \cs_generate_variant:Nn \@@_get_pageref:Nn { Ne }
466 \cs_new:Npn \@@_extract_pageref:n #1
467 {
468 \cs_if_exist:cTF { \c_@@_ref_prefix_tl @ #1 }
469 { \exp_not:v { \c_@@_ref_prefix_tl @ #1 } }
470 { \c_empty_tl }
471 }
472 \cs_generate_variant:Nn \@@_extract_pageref:n { e }
473 % \end{macrocode}
474 % \end{macro}
475 %
476 %
477 % \section{Options}
478 %
479 % \subsection*{\opt{heading} option}
480 %
481 % \begin{macrocode}
482 \keys_define:nn { postnotes/setup }
483 {
484 heading .cs_set_protected:Np = \pnheading ,
485 heading .value_required:n = true ,
486 }
487 % \end{macrocode}
488 %
489 % \begin{macro}[int]{\pnheading}
490 % Provide default value for \cs{pnheading}.
491 % \begin{macrocode}
492 \cs_if_exist:cTF { chapter }
493 {
494 \cs_new_protected:Npn \pnheading
495 {
496 \chapter*{\pntitle}
497 \@mkboth{\pnheaderdefault}{\pnheaderdefault}
498 }
499 }
500 {
501 \cs_new_protected:Npn \pnheading
502 {
503 \section*{\pntitle}
504 \@mkboth{\pnheaderdefault}{\pnheaderdefault}
505 }
506 }
507 % \end{macrocode}
508 % \end{macro}
509 %
510 % \begin{macro}[int]{\pnheaderdefault}
511 % A basic header function to be used as default in the \opt{heading} option.
512 % It produces a header in the form ``Notes to pages N--M'', with a text
513 % which can be localized (see Section~\ref{sec:languages}).
514 % \begin{syntax}
515 % \cs{pnheaderdefault}
516 % \end{syntax}
517 % \begin{macrocode}
518 \NewDocumentCommand \pnheaderdefault {}
519 {
520 \group_begin:
521 \protected@edef \l_@@_tmpa_tl { \FirstMark{postnotes/page} }
522 \protected@edef \l_@@_tmpb_tl { \LastMark{postnotes/page} }
523 \tl_if_eq:NNTF \l_@@_tmpa_tl \l_@@_tmpb_tl
524 { \pnhdnotes{}~\pnhdtopage{}~ \FirstMark{postnotes/page} }
525 {
526 \pnhdnotes{}~\pnhdtopages{}~
527 \FirstMark{postnotes/page}--\LastMark{postnotes/page}
528 }
529 \group_end:
530 }
531 % \end{macrocode}
532 % \end{macro}
533 %
534 %
535 % \subsection*{\opt{format} option}
536 %
537 % \begin{macrocode}
538 \tl_new:N \l_@@_print_format_tl
539 \keys_define:nn { postnotes/setup }
540 {
541 format .tl_set:N = \l_@@_print_format_tl ,
542 format .initial:n = { \small } ,
543 format .value_required:n = true ,
544 }
545 % \end{macrocode}
546 %
547 %
548 % \subsection*{\opt{listenv} option}
549 %
550 % \begin{macrocode}
551 \tl_new:N \l_@@_print_env_tl
552 \bool_new:N \l_@@_print_as_list_bool
553 \keys_define:nn { postnotes/setup }
554 {
555 listenv .code:n =
556 {
557 \tl_if_eq:nnTF {#1} { none }
558 {
559 \bool_set_false:N \l_@@_print_as_list_bool
560 \tl_set:Nn \l_@@_post_printnote_tl { \par }
561 % \end{macrocode}
562 % A sensible default just in case. It should not get to be used though.
563 % \begin{macrocode}
564 \tl_set:Nn \l_@@_print_env_tl { itemize }
565 }
566 {
567 \bool_set_true:N \l_@@_print_as_list_bool
568 \tl_set:Nn \l_@@_print_env_tl {#1}
569 }
570 } ,
571 listenv .initial:n = { postnoteslist } ,
572 listenv .value_required:n = true ,
573 }
574 % \end{macrocode}
575 %
576 %
577 % A couple of built-in list environments provided for convenience, and
578 % \texttt{postnoteslist} as default. The horizontal setup of the label in
579 % these lists is based on the \texttt{description} environment of the standard
580 % classes (see the \emph{The \LaTeX{} Companion}).
581 %
582 % \begin{macrocode}
583 \NewDocumentEnvironment { postnoteslist } { }
584 {
585 \list { }
586 {
587 \setlength { \leftmargin } { 0pt }
588 \setlength { \labelwidth } { 0pt }
589 \setlength { \itemindent } { .5\parindent }
590 \cs_set_eq:NN \makelabel \@@_list_makelabel:n
591 \setlength { \rightmargin } { 0pt }
592 \setlength { \listparindent } { \parindent }
593 \setlength { \parsep } { \parskip }
594 \setlength { \itemsep } { 0pt }
595 \setlength { \topsep } { .5\topsep }
596 \setlength { \partopsep } { .5\partopsep }
597 }
598 }
599 { \endlist }
600 \NewDocumentEnvironment { postnoteslisthang } { }
601 {
602 \list { }
603 {
604 \setlength { \leftmargin } { 1em }
605 \setlength { \labelwidth } { -\leftmargin }
606 \setlength { \itemindent } { -2\leftmargin }
607 \cs_set_eq:NN \makelabel \@@_list_makelabel:n
608 \setlength { \rightmargin } { 0pt }
609 \setlength { \listparindent } { \parindent }
610 \setlength { \parsep } { \parskip }
611 \setlength { \itemsep } { 0pt }
612 \setlength { \topsep } { .5\topsep }
613 \setlength { \partopsep } { .5\partopsep }
614 }
615 }
616 { \endlist }
617 \cs_new:Npn \@@_list_makelabel:n #1
618 { \hspace { \labelsep } \normalfont ~ #1 }
619 % \end{macrocode}
620 %
621 %
622 % \subsection*{\opt{makemark} and \opt{maketextmark} options}
623 %
624 % The arguments are: \texttt{\#1} is the mark, \texttt{\#2} and \texttt{\#3}
625 % are, respectively, the start and the end of the backlink.
626 %
627 % \begin{macrocode}
628 \keys_define:nn { postnotes/setup }
629 {
630 makemark .cs_set:Np = \@@_make_mark:nnn #1#2#3 ,
631 makemark .value_required:n = true ,
632 % \end{macrocode}
633 % From the default kernel definition of \cs{@makefnmark}.
634 % \begin{macrocode}
635 makemark .initial:n =
636 { #2 \hbox { \@textsuperscript { \normalfont #1 } } #3 } ,
637 maketextmark .cs_set:Np = \@@_make_text_mark:nnn #1#2#3 ,
638 maketextmark .value_required:n = true ,
639 maketextmark .initial:n = { #2 #1 . #3 } ,
640 }
641 \cs_generate_variant:Nn \@@_make_mark:nnn { Vnn }
642 % \end{macrocode}
643 %
644 %
645 % \subsection*{\opt{pretextmark}, \opt{posttextmark}, \opt{postprintnote} options}
646 %
647 % \begin{macrocode}
648 \tl_new:N \l_@@_pre_textmark_tl
649 \tl_new:N \l_@@_post_textmark_tl
650 \tl_new:N \l_@@_post_printnote_tl
651 \keys_define:nn { postnotes/setup }
652 {
653 pretextmark .tl_set:N = \l_@@_pre_textmark_tl ,
654 pretextmark .value_required:n = true ,
655 posttextmark .tl_set:N = \l_@@_post_textmark_tl ,
656 posttextmark .value_required:n = true ,
657 postprintnote .tl_set:N = \l_@@_post_printnote_tl ,
658 postprintnote .value_required:n = true ,
659 }
660 % \end{macrocode}
661 %
662 %
663 % \subsection*{\opt{style} option}
664 %
665 % \begin{macrocode}
666 \keys_define:nn { postnotes/setup }
667 {
668 style .choice: ,
669 style / endnotes .meta:n =
670 {
671 listenv = none ,
672 format =
673 {
674 \footnotesize
675 \setlength { \rightskip } { 0pt }
676 \setlength { \leftskip } { 0pt }
677 \setlength { \parindent } { 1.8em }
678 } ,
679 % \end{macrocode}
680 % \pkg{endnotes} uses a zero width box to get the desired alignment to the
681 % right, but that does not play well with the backlinks, so we have a little
682 % more work to do to get this right.
683 % \begin{macrocode}
684 maketextmark =
685 {
686 \hbox_set:Nn \l_@@_tmpa_box
687 { \@textsuperscript { \normalfont ##1 } }
688 \skip_horizontal:n { - \box_wd:N \l_@@_tmpa_box }
689 ##2 \box_use:N \l_@@_tmpa_box ##3
690 } ,
691 } ,
692 style / pagenote .meta:n =
693 {
694 listenv = none ,
695 format = { } ,
696 pretextmark = { \noindent } ,
697 maketextmark = { { \normalfont ##2 ##1 . ##3 } } ,
698 posttextmark = { ~ } ,
699 } ,
700 }
701 % \end{macrocode}
702 %
703 %
704 % \subsection*{\opt{hyperref} and \opt{backlink} options}
705 %
706 % \begin{macrocode}
707 \bool_new:N \l_@@_hyperlink_bool
708 \bool_new:N \l_@@_hyperref_warn_bool
709 \bool_new:N \l_@@_backlink_bool
710 \keys_define:nn { postnotes/setup }
711 {
712 hyperref .choice: ,
713 hyperref / auto .code:n =
714 {
715 \bool_set_true:N \l_@@_hyperlink_bool
716 \bool_set_false:N \l_@@_hyperref_warn_bool
717 } ,
718 hyperref / true .code:n =
719 {
720 \bool_set_true:N \l_@@_hyperlink_bool
721 \bool_set_true:N \l_@@_hyperref_warn_bool
722 } ,
723 hyperref / false .code:n =
724 {
725 \bool_set_false:N \l_@@_hyperlink_bool
726 \bool_set_false:N \l_@@_hyperref_warn_bool
727 } ,
728 hyperref .initial:n = auto ,
729 hyperref .default:n = true ,
730 backlink .bool_set:N = \l_@@_backlink_bool ,
731 backlink .initial:n = true ,
732 backlink .default:n = true ,
733 }
734 % \end{macrocode}
735 %
736 % \begin{macrocode}
737 \AddToHook { begindocument }
738 {
739 \IfPackageLoadedTF { hyperref }
740 { }
741 {
742 \bool_if:NT \l_@@_hyperref_warn_bool
743 { \msg_warning:nn { postnotes } { missing-hyperref } }
744 \bool_set_false:N \l_@@_hyperlink_bool
745 }
746 \keys_define:nn { postnotes/setup }
747 {
748 hyperref .code:n =
749 {
750 \msg_warning:nnn { postnotes }
751 { option-preamble-only } { hyperref }
752 } ,
753 backlink .code:n =
754 {
755 \msg_warning:nnn { postnotes }
756 { option-preamble-only } { backlink }
757 } ,
758 }
759 }
760 \msg_new:nnn { postnotes } { option-preamble-only }
761 { Option~'#1'~only~available~in~the~preamble~\msg_line_context:. }
762 \msg_new:nnn { postnotes } { missing-hyperref }
763 { Missing~'hyperref'~package.~Setting~'hyperref=false'. }
764 % \end{macrocode}
765 %
766 %
767 % \subsection*{\opt{multiple}, \opt{multisep} options}
768 %
769 % As far as I can tell, the \opt{multiple} option has its origins in the
770 % \pkg{footmisc} package, which offers this feature for footnotes. About this
771 % option, \file{footmisc.dtx} observes:
772 %
773 % \begin{quote}
774 % This (revised) code derives from a suggestion by Alexander Rozhenko (the
775 % author of the \pkg{manyfoot} package): the intention is that
776 % \pkg{footmisc} and \pkg{manyfoot} should be able to `interwork', in the
777 % sense that each would recognize the other's footnote marks and behave
778 % appropriately. The trick is that both \cs{footnote} and \cs{footnotemark}
779 % insert a marker (a cancelling pair of kerns of \cs{multiplefootnotemarker}
780 % (of opposite signs), which is detected in following \cs{footnote} or
781 % \cs{footnotemark} commands.
782 % \end{quote}
783 %
784 % About the same option, \file{manyfoot.dtx} notes:
785 %
786 % \begin{quote}
787 % To support \opt{multiple} option from \pkg{footmisc} we add the
788 % \cs{FN@mf@prepare} command from \pkg{footmisc} (suggested by Frank
789 % Mittelbach).
790 % \end{quote}
791 %
792 % Whatever the exact origin of this feature, the fact is that it has spread
793 % throughout the ecosystem, using not only the same basic mechanism but,
794 % typically, using \emph{the same variables}: \cs{multiplefootnotemarker} and
795 % \cs{multfootsep}. With the intention, naturally, that different classes and
796 % packages can ``interwork'' with regard to this feature. And this became a
797 % sort of ``shared feature'' in the ecosystem (the list includes
798 % \pkg{footmisc}, \texttt{KOMA-Script}, \pkg{eledmac}, \pkg{reledmac},
799 % \cls{tufte}, \cls{memoir}, \pkg{parnotes}, \pkg{sidenotes}, and now also
800 % \pkg{postnotes}, see discussion at
801 % \url{https://chat.stackexchange.com/transcript/message/66421777#66421777}).
802 % What is crucial for this interplay, however, is not quite the variables
803 % themselves, but \emph{the value of the canceling pair of kerns}, stored in
804 % \cs{multiplefootnotemarker}. The fact that the same variables are used by
805 % most of the classes and packages which provide the feature speaks for
806 % convenience, in that a change in one of them reflects in all participating
807 % in the ``pool''.
808 %
809 % Convenient as it is, this shared use of the same variables can only work as
810 % long as the community agrees in what these variables contain to some degree.
811 % As far as \cs{multiplefootnotemarker} goes, I see no divergence, and
812 % everybody uses the value of \texttt{3sp} for the canceling kerns from
813 % \cs{FN@mf@prepare}. \file{latex-lab-footnotes.dtx} even documents this
814 % value for this purpose in its list of ``use of kerns to mark h-mode
815 % positions'' (see
816 % \url{https://chat.stackexchange.com/transcript/message/66421893#66421893}).
817 % Things are not as smooth with regard to \cs{multfootsep} though.
818 % \pkg{footmisc} stores a plain comma in \cs{multfootsep} and applies
819 % formatting around it in \cs{FN@mf@check} (hard-coded as
820 % \cs{textsuperscript}). \texttt{KOMA-Script} also stores plain content in
821 % \cs{multfootsep} and applies the formatting in the check function.
822 % \cls{memoir}, however, stores the formatting directly \cs{multfootsep} and
823 % applies no formatting later. Also, \file{latex-lab-footmisc.ltx}, in adding
824 % PDF tagging support for \pkg{footmisc} stores the tagging code directly in
825 % \cs{multfootsep}. I don't know if there are others, but these cases are
826 % already relevant enough to spoil things. The problem is not that they
827 % disagree on the value of \cs{multfootsep}, but on the function(s) this macro
828 % is supposed to perform. That given, any other parties trying to partake in
829 % this feature have to handle things differently depending on the value of
830 % \cs{multfootsep}. All in all, \pkg{postnotes} takes the cautious stance of
831 % using internal variables, instead of the shared ones, to implement the
832 % \opt{multiple} option. The only thing that really needs to be common is the
833 % value of the canceling kerns of \texttt{3sp} in \cs{@@_multiple_prepare:}.
834 %
835 % \begin{macrocode}
836 \tl_new:N \l_@@_multisep_tl
837 \tl_const:Nn \c_postnotes_multi_notemarker_tl { 3sp }
838 \bool_new:N \l_@@_multiple_bool
839 \tl_new:N \l_@@_saved_spacefactor_multi_tl
840 \keys_define:nn { postnotes/setup }
841 {
842 multiple .bool_set:N = \l_@@_multiple_bool ,
843 multiple .default:n = true ,
844 multiple .initial:n = false ,
845 multisep .tl_set:N = \l_@@_multisep_tl ,
846 multisep .value_required:n = true ,
847 multisep .initial:n = {,} ,
848 }
849 % \end{macrocode}
850 %
851 % I'm using the definitions in \pkg{latex-lab-footmisc.ltx} as base, see
852 % \texttt{texdoc latex-lab-footnotes}. For the formatting of the separator,
853 % though, I take inspiration from \texttt{KOMA-Script} and use
854 % \cs{@@_make_mark:nnn}, instead of hard-coding \cs{textsuperscript}.
855 % \begin{macrocode}
856 \cs_new_protected:Npn \@@_multiple_prepare:
857 {
858 \bool_if:NT \l_@@_multiple_bool
859 {
860 \kern -\c_postnotes_multi_notemarker_tl
861 \kern \c_postnotes_multi_notemarker_tl
862 \scan_stop:
863 }
864 }
865 % \end{macrocode}
866 % Note that \cs{@@_multiple_check:} has to be called before any whatsits
867 % (labels, anchors, etc.) are placed, since they destroy \cs{lastkern} (see
868 % \url{https://chat.stackexchange.com/transcript/message/66554870#66554870},
869 % thanks \contributor{Ulrike Fischer}).
870 % \begin{macrocode}
871 \cs_new_protected:Npn \@@_multiple_check:
872 {
873 \bool_if:NT \l_@@_multiple_bool
874 {
875 \dim_compare:nNnT
876 { \c_postnotes_multi_notemarker_tl } = { \lastkern }
877 {
878 \tl_set:Ne \l_@@_saved_spacefactor_multi_tl
879 { \int_use:N \spacefactor }
880 \unkern
881 \unkern
882 \tag_socket_use:n { postnotes/multisep/begin }
883 \@@_make_mark:Vnn \l_@@_multisep_tl { } { }
884 \tag_socket_use:n { postnotes/multisep/end }
885 \spacefactor \l_@@_saved_spacefactor_multi_tl
886 \scan_stop:
887 }
888 }
889 }
890 % \end{macrocode}
891 %
892 %
893 % \subsection*{\opt{sort} option}
894 %
895 % \begin{macrocode}
896 \bool_new:N \l_@@_sort_bool
897 \keys_define:nn { postnotes/setup }
898 {
899 sort .bool_set:N = \l_@@_sort_bool ,
900 sort .initial:n = true ,
901 sort .default:n = true ,
902 }
903 % \end{macrocode}
904 %
905 %
906 % \subsection*{\opt{checkduplicates} and \opt{checkfloats} options}
907 %
908 % \begin{macrocode}
909 \bool_new:N \l_@@_check_dupli_bool
910 \bool_new:N \l_@@_check_floats_bool
911 \keys_define:nn { postnotes/setup }
912 {
913 checkduplicates .bool_set:N = \l_@@_check_dupli_bool ,
914 checkduplicates .default:n = true ,
915 checkduplicates .initial:n = true ,
916 checkfloats .bool_set:N = \l_@@_check_floats_bool ,
917 checkfloats .default:n = true ,
918 checkfloats .initial:n = false ,
919 }
920 % \end{macrocode}
921 %
922 %
923 % \subsection*{\opt{maybemulti} option}
924 %
925 % \begin{macrocode}
926 \bool_new:N \l_@@_maybe_multi_bool
927 \keys_define:nn { postnotes/setup }
928 {
929 maybemulti .bool_set:N = \l_@@_maybe_multi_bool ,
930 maybemulti .default:n = true ,
931 maybemulti .initial:n = false ,
932 }
933 % \end{macrocode}
934 %
935 %
936 % \subsection*{\opt{counteraux} option}
937 %
938 % \begin{macrocode}
939 \bool_new:N \g_@@_counteraux_bool
940 \keys_define:nn { postnotes/setup }
941 {
942 counteraux .bool_gset:N = \g_@@_counteraux_bool ,
943 counteraux .default:n = true ,
944 counteraux .initial:n = false ,
945 }
946 % \end{macrocode}
947 %
948 %
949 % \begin{macrocode}
950 \AddToHook { begindocument/before }
951 {
952 \bool_if:NT \g_@@_counteraux_bool
953 { \postnotesetup { sort=false } }
954 \keys_define:nn { postnotes/setup }
955 {
956 counteraux .code:n =
957 {
958 \msg_warning:nnn { postnotes }
959 { option-preamble-only } { counteraux }
960 } ,
961 }
962 }
963 % \end{macrocode}
964 %
965 %
966 % \begin{macro}[int]
967 % {
968 % \pnsetcounteraux ,
969 % \pnaddtocounteraux ,
970 % \postnote@setcounteraux ,
971 % \postnote@addtocounteraux ,
972 % }
973 % \begin{syntax}
974 % \cs{pnsetcounteraux}\marg{int}
975 % \cs{pnaddtocounteraux}\marg{int}
976 % \cs{postnote@setcounteraux}\marg{int}
977 % \cs{postnote@addtocounteraux}\marg{int}
978 % \end{syntax}
979 % \begin{macrocode}
980 \cs_new_protected:Npn \postnote@setcounteraux #1
981 { \int_gset:Nn \g_@@_postnote_counteraux_int { #1 } }
982 \cs_new_protected:Npn \postnote@addtocounteraux #1
983 { \int_gadd:Nn \g_@@_postnote_counteraux_int { #1 } }
984 \NewDocumentCommand \pnsetcounteraux { m }
985 {
986 \@bsphack
987 \legacy_if:nT { @filesw }
988 {
989 \protected@write \@auxout { }
990 { \token_to_str:N \postnote@setcounteraux { #1 } }
991 }
992 \@esphack
993 }
994 \NewDocumentCommand \pnaddtocounteraux { m }
995 {
996 \@bsphack
997 \legacy_if:nT { @filesw }
998 {
999 \protected@write \@auxout { }
1000 { \token_to_str:N \postnote@addtocounteraux { #1 } }
1001 }
1002 \@esphack
1003 }
1004 % \end{macrocode}
1005 % \end{macro}
1006 %
1007 %
1008 %
1009 % \subsection*{\cs{postnotesetup}}
1010 %
1011 %
1012 % \begin{macro}[int]{\postnotesetup}
1013 % Provide \cs{postnotesetup}.
1014 % \begin{syntax}
1015 % \cs{postnotesetup}\marg{options}
1016 % \end{syntax}
1017 % \begin{macrocode}
1018 \NewDocumentCommand \postnotesetup { m }
1019 { \keys_set:nn { postnotes/setup } {#1} }
1020 % \end{macrocode}
1021 % \end{macro}
1022 %
1023 %
1024 % \section{\cs{postnote}}
1025 %
1026 % Different from the traditional \cs{footnotemark} / \cs{footnotetext} system,
1027 % in the context of end notes, the functionality which corresponds to
1028 % \cs{footnotetext} is simply to store the data to be typeset later. Hence,
1029 % some of the problems that afflict footnotes do not apply to end notes.
1030 % Namely, and as far as I can tell, they can be used in ``inner horizontal
1031 % mode'' (\cs{mbox} etc.), and in math mode, and if the ``text'' will be
1032 % typeset in the same page as the ``mark'' is of little concern.
1033 %
1034 % However, the separation between ``mark'' and ``text'' is still useful in
1035 % other contexts: floats and contexts where multiple typesetting passes are
1036 % performed. \contributor{David Carlisle} and \contributor{Ulrike Fischer}
1037 % shared some thoughts on the matter at the TeX.SX chat:
1038 % \url{https://chat.stackexchange.com/transcript/message/60754383#60754383}.
1039 %
1040 % The interesting questions here are: if they are replaceable in their roles
1041 % in these contexts and how much would we lose by providing them. In
1042 % analyzing this, we have to distinguish two situations: when
1043 % \cs{footnotemark} is called with no argument (and thus steps the counter),
1044 % and when it is called with the optional argument (and thus refrains from
1045 % stepping the counter).
1046 %
1047 % For floats, the problem they pose is that they may disturb the
1048 % \emph{ordering} of the notes. This particular issue can be solved by using
1049 % \cs{footnotemark} without argument, and manually adjusting the counter on
1050 % subsequent calls to \cs{footnotetext}. A good example of the technique is
1051 % \url{https://tex.stackexchange.com/a/43694}. True, a user may wish to
1052 % specify the mark explicitly, but doesn't necessarily need to do it to solve
1053 % the ordering issue.
1054 %
1055 % Multiple typesetting passes of content are much harder. And they abound:
1056 % the standard classes' \cs{caption} typesets the caption once, if it is
1057 % short, but twice if it is longer than a line; \pkg{amsmath}'s math
1058 % environments perform a measuring pass before actually typesetting the
1059 % equations; \pkg{amsmath}'s \cs{text} macro runs the contents through
1060 % \cs{mathchoice} (which typesets the contents four times) when in math mode;
1061 % \pkg{tabularx} and \pkg{tabularray} also perform measuring passes of their
1062 % tables; so does \pkg{csquotes}' blockquotes; and certainly more that I'm
1063 % unaware. A number of these places offer some one or another way to mitigate
1064 % the issue: \pkg{amsmath}, \pkg{tabularx}, \pkg{csquotes} and (optionally)
1065 % \pkg{tabularray} restore counter values after measuring steps; \pkg{amsmath}
1066 % offers a boolean to indicate when it is a measuring pass; \pkg{csquotes}
1067 % offers further handles. But the standard \cs{caption} offers none, and
1068 % neither does \pkg{amsmath}'s \cs{text} macro. Well, the pkg{caption}
1069 % package can disable the multiple passes for \cs{caption} with the option
1070 % \opt{singlelinecheck}, but it is not reasonable to require it for our
1071 % purposes, so we must assume the worst case.
1072 %
1073 % Enrico Gregorio is categorical in stating that \cs{endnotemark} and
1074 % \cs{endnotetext} are required for \pkg{enotez} to handle \cs{caption}, which
1075 % apparently it didn't offer originally: ``The package should implement
1076 % \cs{endnotemark} and \cs{endnotetext} for this case. According to the
1077 % documentation, the author deems them to not be needed: he's wrong.''
1078 % (\url{https://tex.stackexchange.com/a/314937}). See also
1079 % \url{https://tex.stackexchange.com/a/43794} and
1080 % \url{https://tex.stackexchange.com/a/358207}.
1081 %
1082 % In this scenario, when there's no way around the multiple passes,
1083 % \cs{footnotemark} can only handle the general case if used with an argument,
1084 % precisely because it inhibits the stepping of the counter. Otherwise the
1085 % counter is stepped multiple times, and we'd get the wrong number (and mark).
1086 % In some circumstances, if we know the number of passes is deterministic, we
1087 % might get away by adjusting the counter manually (\cs{caption} may be dealt
1088 % with this way: if we know it to be two lines, we can decrement the counter
1089 % before it and get correct results, even hyperlinked). But in cases which
1090 % adjusting the counter is sufficient, end notes can be dealt with in the same
1091 % way, and doesn't need the separation between ``mark'' and ``text''. So,
1092 % what is distinctive of the kernel's footnote apparatus, which allows it as
1093 % much flexibility as one would like, is receiving an arbitrary number as
1094 % argument and not stepping the counter. And as far as \cs{footnotemark} and
1095 % \cs{footnotetext} are concerned, the main point of the optional argument is
1096 % really to ``manually establish the relation'' between the two of them. So,
1097 % if \emph{not stepping the counter} is what is needed to handle the general
1098 % case, is it viable to do so? What would we loose in so doing?
1099 %
1100 % When receiving an arbitrary number as argument, as the kernel functionality
1101 % for footnotes and other endnotes packages do, this value is expected to the
1102 % printed as such, hence it must correspond to the \texttt{postnote} counter
1103 % (in our case). But this counter is in the hands of the user, and can be
1104 % reset along the document, thus its uniqueness cannot be ensured. But not
1105 % stepping \texttt{postnote} is perfectly viable, as it just aims at storing
1106 % how the mark is to be typeset. However, not stepping the ID counter would
1107 % complicate things considerably. Not doing so implies we'd lose the
1108 % connection we have between the ``mark'' and the corresponding ``text''. We
1109 % might add the ``text'' to the queue, but all the metadata would be lost,
1110 % including the \pkg{hyperref} anchor, but really the set of data without
1111 % which the kind of functionality offered would be nonviable, or severely
1112 % hampered. Not stepping \texttt{postnote} but stepping the ID counter also
1113 % is not sufficient, because we'd get a note in duplicity. We could naively
1114 % think that a gap in the ID is not a problem, and just not add the duplicate
1115 % to the queue. But how could we tell the difference between a legitimate and
1116 % an illegitimate step of the ID counter?
1117 %
1118 % I have not been able to devise a way to ``reconnect'' ``text'' and ``mark''
1119 % in the absence of the unique ID counter. The most promising idea was to
1120 % have mandatory arguments to \cs{postnotemark} and \cs{postnotetext}
1121 % receiving a \meta{label} which we could use to identify their counterparts,
1122 % but I was not able to go through with this, and the attempts all increased
1123 % complexity considerably. It is not just a label/ref system, there's got to
1124 % be a one-to-one correspondence between the sets, uniqueness has to be
1125 % ensured on both sides, and there cannot be ``lone'' marks or texts (a
1126 % bijection). Besides, this label based system of identification would have
1127 % to live side-by-side with the one based on the counter. So, even if we'd
1128 % have unique IDs, we wouldn't know beforehand in what form it comes.
1129 % Considering the ID is used to build the variable name in which we store the
1130 % note's information, this would also complicate things.
1131 %
1132 % Besides, there are ways to get things working with multiple passes without
1133 % the ``mark''/``text'' partition. As mentioned, there are a number of cases
1134 % which offer some kind of ``handle'' or way to identify the multiple passes.
1135 % \pkg{csquotes} has a dedicated hook that can be used. \pkg{amsmath} sets
1136 % the \texttt{measuring@} boolean (which \pkg{hyperref} also defines). So,
1137 % not all cases are as tricky as \cs{caption} or \cs{text}, and even that can
1138 % be decently dealt with without a separation between ``mark'' and ``text''.
1139 % Besides, in difficult cases, the package offers a \opt{nomark} option to
1140 % \cs{postnote} to place a note, but typeset no mark. Then we can typeset a
1141 % mark with \cs{postnoteref} referring to a \cs{label} in the note of
1142 % interest. This would result in a correct mark without duplicity, and in a
1143 % correct link from there to the note's text at \cs{printpostnotes}. The
1144 % drawback is that the placement of \cs{postnote} would be important, and
1145 % results sensitive to it. All the metadata is collected at the point of
1146 % \cs{postnote}, anchor included, not at the point of \cs{postnoteref}. So
1147 % the consequences are a slightly off backlink, possibly imprecise metadata,
1148 % etc. Considering \pkg{hyperref} itself shies away completely from linking
1149 % \cs{footnotemark} with an argument, I'd say there's some gain.
1150 %
1151 % The truth is there are some trade-offs, there's no ``ideal'' solution.
1152 % Still, all in all, my judgment is that the unique ID counter is worth more
1153 % than the inconveniences of an ocasional \texttt{\cs{postnote}[nomark]}
1154 % referenced with \cs{postnoteref}, and even that should not be needed much.
1155 % So, for the time being, until something else shakes this balance, I won't be
1156 % offering \cs{postnotemark} and \cs{postnotetext}.
1157 %
1158 % \bigskip{}
1159 %
1160 % For the \pkg{hyperref} support for cross-references in \cs{postnote}, I've
1161 % moved back and forth quite a lot. One of the ideas I fancied was using
1162 % \cs{refstepcounter} and let \pkg{hyperref} do its job. But, since I want to
1163 % have control of the anchor/destination name on both ``sides'', I'd have to
1164 % set \cs{theHpostnote} locally before calling \cs{refstepcounter}, otherwise
1165 % results might sensitive to user calls to \cs{counterwithin} (see
1166 % \url{https://github.com/latex3/hyperref/issues/230}, thanks
1167 % \contributor{Ulrike Fischer}). However, even if that worked well for the
1168 % default case, we still had to setup things manually, in case of a manually
1169 % supplied mark. All in all, I'm just calling \cs{stepcounter}, setting the
1170 % relevant cross-reference variables once and setting the anchor manually.
1171 %
1172 %
1173 % \bigskip{}
1174 %
1175 % \texttt{postnote} is the public, user facing, counter for \cs{postnote}. It
1176 % determines how the note's mark gets to be typeset. It can be reset, set,
1177 % and have its printed representation changed. Of course, whether those are
1178 % meaningful is up to the user.
1179 %
1180 % \begin{macrocode}
1181 \newcounter { postnote }
1182 % \end{macrocode}
1183 %
1184 % \begin{macro}[int]
1185 % {
1186 % \g_@@_note_id_int ,
1187 % \l_postnotes_note_id_tl ,
1188 % \g_@@_queue_seq ,
1189 % \l_@@_counteraux_step_int ,
1190 % \l_@@_mark_typeset_tl ,
1191 % \l_@@_note_set_labels_tl ,
1192 % }
1193 % \cs{g_@@_note_id_int} is the internal, unique counter which provides the
1194 % ID number of each note. It ties ``mark'' and ``text'' together, is also
1195 % the connection between each note and its data, including the content,
1196 % which is stored in a property list named according to \cs{@@_data_name:n}
1197 % and the ID number. \cs{l_postnotes_note_id_tl} is a convenience variable
1198 % storing the counter's value. \cs{g_@@_queue_seq} stores the sequence of
1199 % notes' IDs to be processed by the next call of \cs{printpostnotes}.
1200 % \begin{macrocode}
1201 \int_new:N \g_@@_note_id_int
1202 \tl_new:N \l_postnotes_note_id_tl
1203 \tl_set:Nn \l_postnotes_note_id_tl { \int_use:N \g_@@_note_id_int }
1204 \seq_new:N \g_@@_queue_seq
1205 \int_new:N \l_@@_counteraux_step_int
1206 \tl_new:N \l_@@_mark_typeset_tl
1207 \tl_new:N \l_@@_note_set_labels_tl
1208 % \end{macrocode}
1209 % \end{macro}
1210 %
1211 %
1212 % \begin{macro}[int]{\postnote}
1213 % Provide \cs{postnote}.
1214 % \begin{syntax}
1215 % \cs{postnote}\oarg{options}\marg{note text}
1216 % \end{syntax}
1217 % \begin{macrocode}
1218 \NewDocumentCommand \postnote { O { } +m }
1219 { \@@_note:nn {#1} {#2} }
1220 % \end{macrocode}
1221 % \end{macro}
1222 %
1223 %
1224 % \begin{macro}{\@@_note:nn}
1225 % The internal version of \cs{postnote}. The \texttt{postnotes/note/begin}
1226 % hook is meant to provide a place from where some additional setup for the
1227 % note can be performed. This is being used for adding support for some
1228 % features/packages, but can also be used, for example, to add an extra
1229 % local property for \pkg{zref}.
1230 % \begin{syntax}
1231 % \cs{@@_note:nn} \oarg{options} \marg{note content}
1232 % \end{syntax}
1233 % \begin{macrocode}
1234 \NewHook { postnotes/note/begin }
1235 \NewHook { postnotes/note/setlabels }
1236 \cs_new_protected:Npn \@@_note:nn #1#2
1237 {
1238 \group_begin:
1239 \keys_set:nn { postnotes/note } {#1}
1240 \bool_if:NT \l_@@_nomark_bool { \@bsphack }
1241 \@@_inhibit_note:F
1242 {
1243 \int_gincr:N \g_@@_note_id_int
1244 \tl_if_empty:NTF \l_@@_mark_tl
1245 {
1246 \stepcounter { postnote }
1247 \int_set:Nn \l_@@_counteraux_step_int { 1 }
1248 \bool_if:NT \g_@@_counteraux_bool
1249 {
1250 \exp_args:NNe \prop_gpop:NnNT \g_@@_counteraux_prop
1251 { \l_postnotes_note_id_tl } \l_@@_tmpa_tl
1252 { \int_set:Nn \c@postnote { \l_@@_tmpa_tl } }
1253 \tl_clear:N \l_@@_tmpa_tl
1254 }
1255 \protected@edef \l_@@_mark_tl { \thepostnote }
1256 }
1257 { \int_set:Nn \l_@@_counteraux_step_int { 0 } }
1258 \UseHook { postnotes/note/begin }
1259 \seq_gput_right:Ne \g_@@_queue_seq
1260 { \l_postnotes_note_id_tl }
1261 \tl_set:Nn \@currentcounter { postnote }
1262 \protected@edef \@currentlabel { \p@postnote \l_@@_mark_tl }
1263 \tl_gset:Ne \@currentHref
1264 { postnote. \l_postnotes_note_id_tl .mark }
1265 \@@_store:nn { \l_postnotes_note_id_tl } {#2}
1266 \tl_set_eq:NN \l_@@_mark_typeset_tl \l_@@_mark_tl
1267 % \end{macrocode}
1268 % Prefer \opt{label} for typesetting measuring passes, if available, see
1269 % comments at \cs{@@_inhibit_note:F}.
1270 % \begin{macrocode}
1271 \bool_lazy_or:nnT
1272 { \g_@@_counteraux_bool }
1273 { \l_@@_maybe_multi_bool }
1274 {
1275 \bool_lazy_and:nnT
1276 { ! \g_@@_firstrun_bool }
1277 {
1278 ! \cs_if_exist_p:c
1279 { \c_@@_ref_prefix_tl @ mark @ \l_postnotes_note_id_tl }
1280 }
1281 { \@@_get_label_if_exist:N \l_@@_mark_typeset_tl }
1282 }
1283 \tl_set:Nn \l_@@_note_set_labels_tl
1284 {
1285 \UseHook { postnotes/note/setlabels }
1286 \MakeLinkTarget* { postnote. \l_postnotes_note_id_tl .mark }
1287 \@@_set_mark_page_label:ee { \l_postnotes_note_id_tl }
1288 { \int_use:N \l_@@_counteraux_step_int }
1289 \@@_set_user_labels:
1290 }
1291 \bool_if:NTF \l_@@_nomark_bool
1292 {
1293 \tag_socket_use:n { postnotes/nomark/begin }
1294 \l_@@_note_set_labels_tl
1295 \tag_socket_use:n { postnotes/nomark/end }
1296 }
1297 {
1298 \@@_typeset_mark:eVN
1299 { \l_postnotes_note_id_tl } \l_@@_mark_typeset_tl
1300 \l_@@_note_set_labels_tl
1301 }
1302 }
1303 \bool_if:NT \l_@@_nomark_bool { \@esphack }
1304 \group_end:
1305 }
1306 % \end{macrocode}
1307 % \end{macro}
1308 %
1309 %
1310 % Options for \cs{postnote}.
1311 %
1312 % \begin{macrocode}
1313 \tl_new:N \l_@@_mark_tl
1314 \bool_new:N \l_@@_nomark_bool
1315 \fp_new:N \l_@@_sort_num_fp
1316 \str_new:N \l_@@_note_label_str
1317 \bool_new:N \l_@@_manual_sortnum_bool
1318 \keys_define:nn { postnotes/note }
1319 {
1320 markstr .tl_set:N = \l_@@_mark_tl ,
1321 markstr .value_required:n = true ,
1322 sortnum .code:n =
1323 {
1324 \fp_set:Nn \l_@@_sort_num_fp {#1}
1325 \bool_set_true:N \l_@@_manual_sortnum_bool
1326 } ,
1327 sortnum .value_required:n = true ,
1328 mark .meta:n =
1329 {
1330 markstr = {#1} ,
1331 sortnum = {#1} ,
1332 } ,
1333 mark .value_required:n = true ,
1334 nomark .bool_set:N = \l_@@_nomark_bool ,
1335 nomark .default:n = true ,
1336 label .str_set:N = \l_@@_note_label_str ,
1337 label .value_required:n = true ,
1338 maybemulti .bool_set:N = \l_@@_maybe_multi_bool ,
1339 maybemulti .default:n = true ,
1340 }
1341 % \end{macrocode}
1342 %
1343 %
1344 % \begin{macro}{\@@_inhibit_note:TF}
1345 % In contexts of multiple passes of content, it may be needed, or preferred,
1346 % to inhibit the note altogether to avoid side effects and duplicity. This
1347 % conditional, obviously, will always return the true branch unless
1348 % something is done in the \texttt{postnotes/note/inhibit} hook. This hook
1349 % is meant to handle support for packages or features which may justify note
1350 % inhibition, and the code there should set \cs{l_@@_inhibit_note_bool},
1351 % \cs{l_@@_print_plain_mark_bool} and
1352 % \cs{l_@@_print_plain_mark_stepcounter_bool} as appropriate to the case.
1353 % \begin{macrocode}
1354 \bool_new:N \l_@@_inhibit_note_bool
1355 \bool_new:N \l_@@_print_plain_mark_bool
1356 \bool_new:N \l_@@_print_plain_mark_stepcounter_bool
1357 \NewHook { postnotes/note/inhibit }
1358 \prg_new_protected_conditional:Npnn \@@_inhibit_note: { F }
1359 {
1360 \bool_set_false:N \l_@@_inhibit_note_bool
1361 \bool_set_false:N \l_@@_print_plain_mark_bool
1362 \bool_set_false:N \l_@@_print_plain_mark_stepcounter_bool
1363 \UseHook { postnotes/note/inhibit }
1364 % \end{macrocode}
1365 % Printing a plain mark here may be needed because, if we are inhibiting the
1366 % note in a ``measuring context'' and omit it completely, the measuring being
1367 % performed will be off by the size of the mark. So, to ensure the measuring
1368 % can be done correctly, we place the mark. What to do with the counter
1369 % itself, depends on the situation. In places that are known to restore the
1370 % counter values after the measuring pass, we can let the counter be stepped.
1371 % And, actually we should do so, for example, in a \env{tabularx} with
1372 % multiple postnotes, if we don't step the counter, all the measuring will be
1373 % done with the number of the first note. Otherwise, we don't actually step
1374 % the counter but, to typeset correctly the mark that would be printed if the
1375 % counter had been stepped, we increment \cs{c@postnote} locally and grouped,
1376 % and smuggle \cs{thepostnote} out of the group.
1377 % \begin{macrocode}
1378 \bool_lazy_all:nT
1379 {
1380 { \l_@@_inhibit_note_bool }
1381 { \l_@@_print_plain_mark_bool }
1382 { ! \l_@@_nomark_bool }
1383 }
1384 {
1385 \tl_if_empty:NTF \l_@@_mark_tl
1386 {
1387 \bool_if:NTF \l_@@_print_plain_mark_stepcounter_bool
1388 {
1389 \stepcounter { postnote }
1390 \protected@edef \l_@@_mark_typeset_tl { \thepostnote }
1391 }
1392 {
1393 \group_begin:
1394 \int_incr:N \c@postnote
1395 \protected@edef \l_@@_tmpa_tl { \thepostnote }
1396 \exp_args:NNNV
1397 \group_end:
1398 \tl_set:Nn \l_@@_mark_typeset_tl \l_@@_tmpa_tl
1399 }
1400 % \end{macrocode}
1401 % If the note has a \opt{label}, use a cross-reference to that as the mark
1402 % instead. In principle, the procedure above is expected to work reasonably
1403 % well for cases where we know whether we are in a measuring pass or not, and
1404 % how it handles the counters (if it restores counters or not). This is true
1405 % though, only if we are going in the expansion order of the document. If we
1406 % are using the \opt{counteraux} option, the mere sequence of the notes is no
1407 % longer an indicator of who is a measuring pass of who, indeed the measuring
1408 % pass does not even get to the \file{.aux} file. If the label exists,
1409 % though, it is \emph{known to be right} regardless of the case, since it
1410 % belongs to the pass which actually gets typeset. Hence, if we have a label,
1411 % it is more general and more reliable: use it.
1412 % \begin{macrocode}
1413 \@@_get_label_if_exist:N \l_@@_mark_typeset_tl
1414 }
1415 { \tl_set_eq:NN \l_@@_mark_typeset_tl \l_@@_mark_tl }
1416 \group_begin:
1417 \socket_assign_plug:nn { tagsupport/postnotes/multisep/begin } { noop }
1418 \socket_assign_plug:nn { tagsupport/postnotes/multisep/end } { noop }
1419 \@@_typeset_mark_wrapper:nnn
1420 { \@@_make_mark:Vnn \l_@@_mark_typeset_tl { } { } }
1421 { } { }
1422 \group_end:
1423 }
1424 \bool_if:NTF \l_@@_inhibit_note_bool
1425 { \prg_return_true: }
1426 { \prg_return_false: }
1427 }
1428 % \end{macrocode}
1429 % \end{macro}
1430 %
1431 % \begin{macro}{\@@_get_label_if_exist:N}
1432 % \begin{syntax}
1433 % \cs{@@_get_label_if_exist:N} \meta{\cs{l_@@_mark_tl}}
1434 % \end{syntax}
1435 % \begin{macrocode}
1436 \cs_new_protected:Npn \@@_get_label_if_exist:N #1
1437 {
1438 \str_if_empty:NTF \l_@@_note_label_str
1439 {
1440 \str_if_empty:NF \l_@@_note_zlabel_str
1441 {
1442 \exp_args:NV \zref@ifrefundefined \l_@@_note_zlabel_str
1443 { }
1444 {
1445 \exp_args:NV \zref@ifrefcontainsprop
1446 \l_@@_note_zlabel_str
1447 { postnote@mark }
1448 {
1449 \exp_args:NNNo \exp_args:NNo \tl_set:Nn #1
1450 {
1451 \zref@extract
1452 { \l_@@_note_zlabel_str } { postnote@mark }
1453 }
1454 }
1455 { }
1456 }
1457 }
1458 }
1459 {
1460 \exp_args:Ne \property_if_recorded:nnT
1461 { postnotes@ \l_@@_note_label_str }
1462 { postnotes/mark }
1463 {
1464 \protected@edef #1
1465 {
1466 \property_ref:ee
1467 { __postnotes_ \l_@@_note_label_str } { postnotes/mark }
1468 }
1469 }
1470 }
1471 }
1472 % \end{macrocode}
1473 % \end{macro}
1474 %
1475 %
1476 % \begin{macro}
1477 % {
1478 % \@@_typeset_mark:nnN ,
1479 % \@@_typeset_mark_wrapper:nnn ,
1480 % }
1481 % Auxiliary functions for mark typesetting in \cs{@@_note:nn}.
1482 % \cs{@@_typeset_mark_wrapper:nnn} is based on the definition of
1483 % \cs{@footnotemark} in the kernel.
1484 % \begin{syntax}
1485 % \cs{@@_typeset_mark:nnN} \Arg{note id} \Arg{mark} \Arg{labels}
1486 % \cs{@@_typeset_mark_wrapper:nnn} \Arg{mark}
1487 % ~~\Arg{begin tagging} \Arg{end tagging}
1488 % \end{syntax}
1489 % \begin{macrocode}
1490 \cs_new_protected:Npn \@@_typeset_mark:nnN #1#2#3
1491 {
1492 \@@_typeset_mark_wrapper:nnn
1493 {
1494 #3
1495 \bool_if:NTF \l_@@_hyperlink_bool
1496 {
1497 \@@_make_mark:nnn {#2}
1498 { \hyper@linkstart { link } { postnote. #1 .text } }
1499 { \hyper@linkend }
1500 }
1501 { \@@_make_mark:nnn {#2} { } { } }
1502 }
1503 { \tag_socket_use:n { postnotes/mark/begin } }
1504 { \tag_socket_use:n { postnotes/mark/end } }
1505 }
1506 \cs_generate_variant:Nn \@@_typeset_mark:nnN { eVN }
1507 \tl_new:N \l_@@_saved_spacefactor_tl
1508 \cs_new_protected:Npn \@@_typeset_mark_wrapper:nnn #1#2#3
1509 {
1510 \mode_leave_vertical:
1511 \mode_if_horizontal:T
1512 {
1513 \tl_set:Ne \l_@@_saved_spacefactor_tl
1514 { \int_use:N \spacefactor }
1515 \@@_multiple_check:
1516 \nobreak
1517 }
1518 #2 % begin tagging socket
1519 #1 % mark
1520 #3 % end tagging socket
1521 \@@_multiple_prepare:
1522 \mode_if_horizontal:T
1523 { \spacefactor \l_@@_saved_spacefactor_tl }
1524 \scan_stop:
1525 }
1526 % \end{macrocode}
1527 % \end{macro}
1528 %
1529 %
1530 % \begin{macro}{\@@_set_user_labels:}
1531 % Auxiliary function for user label setting in \cs{@@_note:nn}. Supports
1532 % the \opt{label} and \opt{zlabel} options of \cs{postnote}.
1533 % \begin{macrocode}
1534 \cs_new_protected:Npn \@@_set_user_labels:
1535 {
1536 \str_if_empty:NF \l_@@_note_label_str
1537 {
1538 \exp_args:NV \label \l_@@_note_label_str
1539 \property_record:ee { __postnotes_ \l_@@_note_label_str }
1540 { postnotes/mark }
1541 }
1542 \str_if_empty:NF \l_@@_note_zlabel_str
1543 { \exp_args:NV \zlabel \l_@@_note_zlabel_str }
1544 }
1545 \property_new:nnnn { postnotes/mark } { now } { } { \l_@@_mark_tl }
1546 % \end{macrocode}
1547 % \end{macro}
1548 %
1549 %
1550 % \section{\cs{postnoteref}}
1551 %
1552 % \begin{macro}[int]{\postnoteref}
1553 % Provide \cs{postnoteref}.
1554 % \begin{syntax}
1555 % \cs{postnoteref}\meta{*}\marg{label}
1556 % \end{syntax}
1557 % \begin{macrocode}
1558 \NewDocumentCommand \postnoteref { s m }
1559 { \@@_note_ref:nn {#1} {#2} }
1560 % \end{macrocode}
1561 % \end{macro}
1562 %
1563 % \begin{macro}{\@@_note_ref:nn}
1564 % The internal version of \cs{postnoteref}.
1565 % \begin{syntax}
1566 % \cs{@@_note_ref:nn} \Arg{star bool} \Arg{label}
1567 % \end{syntax}
1568 % \begin{macrocode}
1569 \str_new:N \l_@@_note_ref_label_str
1570 \cs_new_protected:Npn \@@_note_ref:nn #1#2
1571 {
1572 \group_begin:
1573 \str_set:Nn \l_@@_note_ref_label_str {#2}
1574 \@@_typeset_mark_wrapper:nnn
1575 {
1576 \bool_lazy_and:nnTF
1577 { ! #1 }
1578 { \l_@@_hyperlink_bool }
1579 {
1580 \hyperref [#2]
1581 { \@@_make_mark:nnn { \ref*{#2} } { } { } }
1582 }
1583 { \@@_make_mark:nnn { \ref*{#2} } { } { } }
1584 }
1585 { \tag_socket_use:n { postnotes/postnoteref/begin } }
1586 { \tag_socket_use:n { postnotes/postnoteref/end } }
1587 \group_end:
1588 }
1589 % \end{macrocode}
1590 % \end{macro}
1591 %
1592 %
1593 % \section{\cs{postnotesection}}
1594 %
1595 % \begin{macro}[int]{\postnotesection}
1596 % Provide \cs{postnotesection}.
1597 % \begin{syntax}
1598 % \cs{postnotesection}\oarg{options}\marg{section content}
1599 % \end{syntax}
1600 % \begin{macrocode}
1601 \NewDocumentCommand \postnotesection { O { } +m }
1602 {
1603 \@bsphack
1604 \@@_section:nn {#1} {#2}
1605 \@esphack
1606 }
1607 % \end{macrocode}
1608 % \end{macro}
1609 %
1610 % \begin{macro}{\@@_section:nn}
1611 % The internal version of \cs{postnotesection}.
1612 % \begin{syntax}
1613 % \cs{@@_section:nn} \Arg{options} \Arg{content}
1614 % \end{syntax}
1615 % \begin{macrocode}
1616 \int_new:N \g_@@_sectid_int
1617 \cs_new_protected:Npn \@@_section:nn #1#2
1618 {
1619 \group_begin:
1620 \int_gincr:N \g_@@_sectid_int
1621 \int_gincr:N \g_@@_note_id_int
1622 \seq_gput_right:Ne \g_@@_queue_seq { \l_postnotes_note_id_tl }
1623 \tl_gclear:N \g_@@_section_name_tl
1624 \keys_set:nn { postnotes/section } {#1}
1625 \@@_set_section_page_label:e { \l_postnotes_note_id_tl }
1626 \bool_if:NTF \l_@@_section_exp_bool
1627 {
1628 \protected@edef \l_@@_tmpa_tl {#2}
1629 \@@_store_section:nV { \l_postnotes_note_id_tl }
1630 \l_@@_tmpa_tl
1631 }
1632 { \@@_store_section:nn { \l_postnotes_note_id_tl } {#2} }
1633 \group_end:
1634 }
1635 % \end{macrocode}
1636 % \end{macro}
1637 %
1638 %
1639 % Options for \cs{postnotesection}. Actually, I would have preferred to use
1640 % ``label'' for the \opt{name} option, but I feared I might need it further
1641 % down the road for the traditional meaning.
1642 %
1643 % \begin{macrocode}
1644 \tl_new:N \g_@@_section_name_tl
1645 \bool_new:N \l_@@_section_exp_bool
1646 \keys_define:nn { postnotes/section }
1647 {
1648 name .tl_gset:N = \g_@@_section_name_tl ,
1649 name .value_required:n = true ,
1650 exp .bool_set:N = \l_@@_section_exp_bool ,
1651 exp .initial:n = false ,
1652 exp .default:n = true ,
1653 }
1654 % \end{macrocode}
1655 %
1656 %
1657 % \section{\cs{printpostnotes}}
1658 %
1659 % \begin{macro}[int]{\printpostnotes}
1660 % Provide \cs{printpostnotes}.
1661 % \begin{syntax}
1662 % \cs{printpostnotes}
1663 % \end{syntax}
1664 % \begin{macrocode}
1665 \NewDocumentCommand \printpostnotes { }
1666 { \@@_print_notes: }
1667 % \end{macrocode}
1668 % \end{macro}
1669 %
1670 %
1671 % \begin{macro}[int]
1672 % {
1673 % \pnthechapter ,
1674 % \pnthesection ,
1675 % \pnthechapternextnote ,
1676 % \pnthesectionnextnote ,
1677 % \pnthepage ,
1678 % \pnidnextnote ,
1679 % }
1680 % User facing variables, aimed at making available some of the notes' and
1681 % sections' metadata for the user at specific contexts.
1682 % \begin{macrocode}
1683 \tl_new:N \pnthechapter
1684 \tl_new:N \pnthesection
1685 \tl_new:N \pnidnextnote
1686 \tl_new:N \pnthechapternextnote
1687 \tl_new:N \pnthesectionnextnote
1688 \tl_new:N \pnthepage
1689 % \end{macrocode}
1690 % \end{macro}
1691 %
1692 % \begin{macro}[int]
1693 % {
1694 % \g_@@_print_postnotes_int ,
1695 % \g_@@_print_queue_seq ,
1696 % \l_postnotes_print_note_id_tl ,
1697 % \l_@@_print_note_id_next_tl ,
1698 % \l_@@_print_counter_tl ,
1699 % \l_@@_print_mark_tl ,
1700 % \l_@@_print_typeset_mark_tl ,
1701 % \l_@@_print_type_curr_tl ,
1702 % \l_@@_print_type_next_tl ,
1703 % \l_@@_print_type_prev_tl ,
1704 % \l_@@_print_content_tl ,
1705 % \l_@@_print_page_tl ,
1706 % \l_@@_print_chapter_tl ,
1707 % \l_@@_print_section_tl ,
1708 % \l_@@_print_sectname_tl ,
1709 % \l_@@_clear_queue_seq ,
1710 % }
1711 % Auxiliary variables for \cs{@@_print_notes:}.
1712 % \begin{macrocode}
1713 \int_new:N \g_@@_print_postnotes_int
1714 \seq_new:N \g_@@_print_queue_seq
1715 \tl_new:N \l_postnotes_print_note_id_tl
1716 \tl_new:N \l_@@_print_note_id_next_tl
1717 \tl_new:N \l_@@_print_counter_tl
1718 \tl_new:N \l_@@_print_mark_tl
1719 \tl_new:N \l_@@_print_typeset_mark_tl
1720 \tl_new:N \l_@@_print_type_curr_tl
1721 \tl_new:N \l_@@_print_type_next_tl
1722 \tl_new:N \l_@@_print_type_prev_tl
1723 \tl_new:N \l_@@_print_content_tl
1724 \tl_new:N \l_@@_print_page_tl
1725 \tl_new:N \l_@@_print_chapter_tl
1726 \tl_new:N \l_@@_print_section_tl
1727 \tl_new:N \l_@@_print_sectname_tl
1728 \seq_new:N \l_@@_clear_queue_seq
1729 % \end{macrocode}
1730 % \end{macro}
1731 %
1732 %
1733 % \pkg{ltmarks} mark classes for running header support data.
1734 %
1735 % \begin{macrocode}
1736 \mark_new_class:n { postnotes/page }
1737 \mark_new_class:n { postnotes/chapter }
1738 \mark_new_class:n { postnotes/section }
1739 \mark_new_class:n { postnotes/sectname }
1740 % \end{macrocode}
1741 %
1742 %
1743 % \cs{@@_print_notes:}' hooks. Meant to provide points of entry for
1744 % additional setup, specially to add support to packages and features which
1745 % require it. The \texttt{postnotes/print/begin} hook is run early in
1746 % \cs{@@_print_notes:} and only once per call, after the user options have
1747 % been processed. The \texttt{postnotes/print/note/begin} hook is run once
1748 % for each note, at the point where environment variables are being set or
1749 % restored, before the typesetting of either the mark or the text, but within
1750 % a group of its own of each note.
1751 %
1752 % \begin{macrocode}
1753 \NewHook { postnotes/print/begin }
1754 \NewHook { postnotes/print/note/begin }
1755 \NewHook { postnotes/print/note/typesetmark }
1756 \NewHook { postnotes/print/note/ltmarks }
1757 % \end{macrocode}
1758 %
1759 %
1760 % The \texttt{postnotetext} is a counter used to restore the original value of
1761 % \texttt{postnote} at the time of printing, for the purposes of
1762 % cross-referencing, it should be different from \texttt{postnote} if a note
1763 % may occur inside \cs{printpostnotes}. The \texttt{postnotesection} is a
1764 % counter which is stepped for every postnote section which gets to be
1765 % actually typeset. It's aim is to provide a valid ``enclosing counter'' to
1766 % \texttt{postnote} in the context of \cs{printpostnotes}. Since we don't
1767 % know where \texttt{postnote} may have been reset along the document, in the
1768 % general case, we can't rely on any other preexisting counter. This means
1769 % that the particular value of \texttt{postnotesection} is of little practical
1770 % meaning, it really is just meant to provide recognizable ``bounds'' for
1771 % \texttt{postnote} along the printing of the notes. Indeed, it is
1772 % initialized to a very high value (larger than the conceivable number of
1773 % postnote sections in a document), so that ``marks'' and ``texts'' don't mix
1774 % in the same reference list, which would occur if the enclosing counters of
1775 % both belonged to the same range, and with somewhat arbitrary results, since
1776 % we cannot ensure the step of the enclosing counter along the document
1777 % matches \texttt{postnotesection}. This is actually a tricky problem from
1778 % the cross-referencing standpoint: two different things, which should be of
1779 % the same type, are reset along the document, but shouldn't really be mixed
1780 % together. They are both \LaTeXe{} counters, since they may be required
1781 % externally. Their main intended use case is to support \pkg{zref-clever},
1782 % but in principle they can be of general use.
1783 %
1784 % \begin{macrocode}
1785 \newcounter { postnotetext }
1786 \newcounter { postnotesection }
1787 \setcounter { postnotesection } { 10000 }
1788 % \end{macrocode}
1789 %
1790 %
1791 % \begin{macro}{\@@_print_notes:}
1792 % The internal version of \cs{printpostnotes}.
1793 % \begin{syntax}
1794 % \cs{@@_print_notes:}
1795 % \end{syntax}
1796 % \begin{macrocode}
1797 \cs_new_protected:Npn \@@_print_notes:
1798 {
1799 \group_begin:
1800 \int_gincr:N \g_@@_print_postnotes_int
1801 \@@_split_labelseq:
1802 % \end{macrocode}
1803 % We make the cut at this point. \cs{g_@@_print_queue_seq} is stored won't
1804 % receive any more notes for the duration of this call of \cs{printpostnotes},
1805 % any notes added to the queue from this point on belong to the next call of
1806 % \cs{printpostnotes}.
1807 % \begin{macrocode}
1808 \bool_lazy_and:nnTF
1809 { \g_@@_counteraux_bool }
1810 { ! \g_@@_firstrun_bool }
1811 {
1812 \seq_gset_eq:NN \g_@@_print_queue_seq
1813 \g_@@_print_labelseq_queue_seq
1814 }
1815 {
1816 \seq_gset_eq:NN \g_@@_print_queue_seq
1817 \g_@@_queue_seq
1818 }
1819 \seq_set_eq:NN \l_@@_clear_queue_seq \g_@@_print_queue_seq
1820 \seq_gclear:N \g_@@_queue_seq
1821 % \end{macrocode}
1822 % The purpose of this label is to provide a point for splitting the labelseq
1823 % with the \opt{counteraux} option. It only needs to exist, it doesn't even
1824 % store the page value.
1825 % \begin{macrocode}
1826 \@@_set_print_label:e
1827 { \int_use:N \g_@@_print_postnotes_int }
1828 \seq_if_empty:NTF \g_@@_print_queue_seq
1829 { \msg_warning:nn { postnotes } { empty-printpostnotes } }
1830 {
1831 \pnheading
1832 \UseHook { postnotes/print/begin }
1833 \tl_set:Nn \l_@@_print_type_prev_tl { open }
1834 \@@_check_duplicates:N \g_@@_print_queue_seq
1835 \@@_sort_queue:N \g_@@_print_queue_seq
1836 \@@_check_floats:N \g_@@_print_queue_seq
1837 \@@_set_header_vars_first:
1838 % \end{macrocode}
1839 % Ensure the first note after a heading has paragraph indentation when
1840 % \opt{listenv} is \texttt{none}. \pkg{endnotes} uses a workaroundish
1841 % solution in \cs{enoteheading}, setting a box and then skipping back a line.
1842 % Enrico Gregorio is correct, though, in criticizing it at
1843 % \url{https://tex.stackexchange.com/q/575905#comment1450213_575915}, and
1844 % suggests the use of \cs{@afterindenttrue}, which is what \pkg{indentfirst}
1845 % does (we do the same, just locally).
1846 % \begin{macrocode}
1847 \bool_if:NF \l_@@_print_as_list_bool
1848 {
1849 \cs_set_eq:NN \@afterindentfalse \@afterindenttrue
1850 \@afterindenttrue
1851 }
1852 \bool_until_do:nn { \seq_if_empty_p:N \g_@@_print_queue_seq }
1853 {
1854 \seq_gpop_left:NN \g_@@_print_queue_seq
1855 \l_postnotes_print_note_id_tl
1856 \@@_prop_get:nnN { \l_postnotes_print_note_id_tl }
1857 { type } \l_@@_print_type_curr_tl
1858 \tl_if_eq:NnTF \l_@@_print_type_curr_tl { section }
1859 { % type_curr = `section'
1860 \seq_if_empty:NTF \g_@@_print_queue_seq
1861 {
1862 \tl_set:Nn \l_@@_print_note_id_next_tl { noid }
1863 \tl_set:Nn \l_@@_print_type_next_tl { close }
1864 }
1865 {
1866 \seq_get_left:NN \g_@@_print_queue_seq
1867 \l_@@_print_note_id_next_tl
1868 \@@_prop_get:nnN
1869 { \l_@@_print_note_id_next_tl }
1870 { type } \l_@@_print_type_next_tl
1871 }
1872 % \end{macrocode}
1873 % We only process the entry if \texttt{type_next} is \texttt{note}: here are
1874 % skipped empty sections.
1875 % \begin{macrocode}
1876 \tl_if_eq:NnT \l_@@_print_type_next_tl { note }
1877 {
1878 \stepcounter { postnotesection }
1879 \group_begin:
1880 \@@_prop_get:nnN
1881 { \l_postnotes_print_note_id_tl }
1882 { thechapter } \pnthechapter
1883 \@@_prop_get:nnN
1884 { \l_postnotes_print_note_id_tl }
1885 { thesection } \pnthesection
1886 \tl_set:NV \pnidnextnote
1887 \l_@@_print_note_id_next_tl
1888 \@@_prop_get:nnN
1889 { \l_@@_print_note_id_next_tl }
1890 { thechapter } \pnthechapternextnote
1891 \@@_prop_get:nnN
1892 { \l_@@_print_note_id_next_tl }
1893 { thesection } \pnthesectionnextnote
1894 \@@_prop_get:nnN
1895 { \l_postnotes_print_note_id_tl }
1896 { content } \l_@@_print_content_tl
1897 \l_@@_print_content_tl
1898 \group_end:
1899 % \end{macrocode}
1900 % Set \texttt{type_prev} for the next iteration.
1901 % \begin{macrocode}
1902 \tl_set:NV \l_@@_print_type_prev_tl
1903 \l_@@_print_type_curr_tl
1904 }
1905 }
1906 { % type_curr = `note'
1907 \seq_if_empty:NTF \g_@@_print_queue_seq
1908 {
1909 \tl_set:Nn \l_@@_print_note_id_next_tl { noid }
1910 \tl_set:Nn \l_@@_print_type_next_tl { close }
1911 }
1912 {
1913 \seq_get_left:NN \g_@@_print_queue_seq
1914 \l_@@_print_note_id_next_tl
1915 \@@_prop_get:nnN
1916 { \l_@@_print_note_id_next_tl }
1917 { type } \l_@@_print_type_next_tl
1918 }
1919 \tl_if_eq:NnF \l_@@_print_type_prev_tl { note }
1920 {
1921 \bool_if:NTF \l_@@_print_as_list_bool
1922 { \exp_args:NV \begin \l_@@_print_env_tl }
1923 { \group_begin: }
1924 \tag_socket_use:n { postnotes/printlist/begin }
1925 \l_@@_print_format_tl
1926 }
1927 \group_begin:
1928 \UseHook { postnotes/print/note/begin }
1929 \@@_get_pageref:Ne \l_@@_print_page_tl
1930 { mark@ \l_postnotes_print_note_id_tl }
1931 \@@_prop_get:nnN { \l_postnotes_print_note_id_tl }
1932 { thechapter } \l_@@_print_chapter_tl
1933 \@@_prop_get:nnN { \l_postnotes_print_note_id_tl }
1934 { thesection } \l_@@_print_section_tl
1935 \@@_prop_get:nnN { \l_postnotes_print_note_id_tl }
1936 { pnsectname } \l_@@_print_sectname_tl
1937 \tl_set_eq:NN \pnthepage \l_@@_print_page_tl
1938 \@@_prop_get:nnN
1939 { \l_postnotes_print_note_id_tl }
1940 { mark } \l_@@_print_mark_tl
1941 \@@_prop_get:nnN
1942 { \l_postnotes_print_note_id_tl }
1943 { counter } \l_@@_print_counter_tl
1944 \@@_prop_get:nnN
1945 { \l_postnotes_print_note_id_tl }
1946 { content } \l_@@_print_content_tl
1947 \tl_set:Nn \@currentcounter { postnotetext }
1948 \int_set:Nn \c@postnotetext
1949 { \l_@@_print_counter_tl }
1950 \protected@edef \@currentlabel
1951 { \p@postnote \l_@@_print_mark_tl }
1952 \tl_set:Nn \l_@@_print_typeset_mark_tl
1953 {
1954 \tag_socket_use:n { postnotes/printmark/begin }
1955 \UseHook { postnotes/print/note/typesetmark }
1956 \MakeLinkTarget*
1957 { postnote. \l_postnotes_print_note_id_tl .text }
1958 \l_@@_pre_textmark_tl
1959 \@@_typeset_text_mark:eV
1960 { \l_postnotes_print_note_id_tl }
1961 \l_@@_print_mark_tl
1962 \l_@@_post_textmark_tl
1963 \tag_socket_use:n { postnotes/printmark/end }
1964 }
1965 % \end{macrocode}
1966 % Note that the placement of the tagging socket for the list case may depend
1967 % on the tagging structure, in other words, on the content of the socket. It
1968 % currently does nothing for the list case, so I've placed it in the
1969 % ``potentially most useful place''. Review this if the content changes.
1970 % Leave vertical mode after \cs{item} for the list case to avoid ``perhaps a
1971 % missing \cs{item}'' error for empty notes (see
1972 % \file{pn-bug-empty-postnote01.lvt}). And leave vertical mode before the
1973 % note (and the tagging socket) for \opt{listenv=none} (see
1974 % \url{https://github.com/gusbrs/postnotes/issues/8#issuecomment-2429501962},
1975 % thanks \contributor{Ulrike Fischer}).
1976 % \begin{macrocode}
1977 \bool_if:NTF \l_@@_print_as_list_bool
1978 {
1979 \item
1980 [
1981 \tag_socket_use:n { postnotes/printnote/begin }
1982 \l_@@_print_typeset_mark_tl
1983 ]
1984 \mode_leave_vertical:
1985 }
1986 {
1987 \mode_leave_vertical:
1988 \tag_socket_use:n { postnotes/printnote/begin }
1989 \l_@@_print_typeset_mark_tl
1990 }
1991 % \end{macrocode}
1992 % In principle, inserting the \pkg{ltmarks} marks would be best done at
1993 % \cs{l_@@_print_typeset_mark_tl}, immediately \emph{before} the mark,
1994 % alongside the anchor. However, \cs{mark_insert:nn} is documented not to
1995 % work inside a box (see \url{https://tex.stackexchange.com/a/732007}) and the
1996 % \cs{item}'s label is typeset as a box, so that's not an option. Before the
1997 % \cs{item} is also not a good idea. As long as the mark is no longer than a
1998 % line, which is arguably to be expected, there shouldn't be any difference
1999 % though. Either way, I don't see any other placement options.
2000 % \begin{macrocode}
2001 \UseHook { postnotes/print/note/ltmarks }
2002 \mark_insert:nn { postnotes/page }
2003 { \l_@@_print_page_tl }
2004 \mark_insert:nn { postnotes/chapter }
2005 { \l_@@_print_chapter_tl }
2006 \mark_insert:nn { postnotes/section }
2007 { \l_@@_print_section_tl }
2008 \mark_insert:nn { postnotes/sectname }
2009 { \l_@@_print_sectname_tl }
2010 \tag_socket_use:n { postnotes/printtext/begin }
2011 \l_@@_print_content_tl
2012 \tag_socket_use:n { postnotes/printtext/end }
2013 \tag_socket_use:n { postnotes/printnote/end }
2014 \l_@@_post_printnote_tl
2015 \group_end:
2016 \tl_if_eq:NnF \l_@@_print_type_next_tl { note }
2017 {
2018 \tag_socket_use:n { postnotes/printlist/end }
2019 % \end{macrocode}
2020 % Ensure \cs{par} at the end of \cs{printpostnotes} (see
2021 % \url{https://github.com/u-fischer/tagpdf/issues/68#issuecomment-1587343876},
2022 % thanks \contributor{Ulrike Fischer}).
2023 % \begin{macrocode}
2024 \bool_if:NTF \l_@@_print_as_list_bool
2025 {
2026 \exp_args:NV \end \l_@@_print_env_tl
2027 \par
2028 }
2029 {
2030 \par
2031 \group_end:
2032 }
2033 }
2034 % \end{macrocode}
2035 % Set \texttt{type_prev} for the next iteration.
2036 % \begin{macrocode}
2037 \tl_set:NV \l_@@_print_type_prev_tl
2038 \l_@@_print_type_curr_tl
2039 }
2040 }
2041 \@@_set_header_vars_bool:
2042 % \end{macrocode}
2043 % We won't use the variables anymore, clear them to reduce memory usage.
2044 % \begin{macrocode}
2045 \seq_map_inline:Nn \l_@@_clear_queue_seq
2046 { \@@_prop_gclear:n { ##1 } }
2047 }
2048 \group_end:
2049 }
2050 % \end{macrocode}
2051 % \end{macro}
2052 %
2053 % \begin{macrocode}
2054 \msg_new:nnn { postnotes } { empty-printpostnotes }
2055 { Empty~'\iow_char:N\\printpostnotes'~\msg_line_context:. }
2056 % \end{macrocode}
2057 %
2058 %
2059 % \begin{macro}{\@@_typeset_text_mark:nn}
2060 % Auxiliary function for mark typesetting in \cs{@@_print_notes:}.
2061 % \begin{syntax}
2062 % \cs{@@_typeset_text_mark:nn} \Arg{note id} \Arg{mark}
2063 % \end{syntax}
2064 % \begin{macrocode}
2065 \cs_new_protected:Npn \@@_typeset_text_mark:nn #1#2
2066 {
2067 \bool_lazy_and:nnTF
2068 { \l_@@_hyperlink_bool }
2069 { \l_@@_backlink_bool }
2070 {
2071 \@@_make_text_mark:nnn {#2}
2072 { \hyper@linkstart { link } { postnote. #1 .mark } }
2073 { \hyper@linkend }
2074 }
2075 { \@@_make_text_mark:nnn {#2} { } { } }
2076 }
2077 \cs_generate_variant:Nn \@@_typeset_text_mark:nn { eV }
2078 % \end{macrocode}
2079 % \end{macro}
2080 %
2081 %
2082 % \subsection*{Print auxiliary}
2083 %
2084 % The conditions used to split \cs{g_@@_labelseq_seq} are subtly different
2085 % depending on whether we are using \cs{g_@@_counteraux_bool} or not. In the
2086 % standard case, the numbering of the floats are set at ``expansion time'', so
2087 % they belong where they are set. With \opt{counteraux}, the numbering of
2088 % floats are set at ``shipout time'', so they belong where they are typeset.
2089 % In other words, with \opt{counteraux} notes on floats can cross the
2090 % boundaries of \cs{printpostnotes}, while without it, they must not.
2091 % Furthermore, the purpose of \cs{g_@@_labelseq_seq} is different in each
2092 % case. With \opt{counteraux} it is used to build the actual print queue,
2093 % while in the standard case it is only used in \cs{@@_check_floats:N}.
2094 % Therefore, with \opt{counteraux} the cut is made at the place the
2095 % \texttt{print} label for the current \cs{printpostnotes} is found, while in
2096 % the standard case, \cs{g_@@_note_id_int} is used directly to distribute the
2097 % elements between the current \cs{printpostnotes} and future ones.
2098 %
2099 %
2100 % \begin{macro}{\@@_split_labelseq:}
2101 % \begin{macrocode}
2102 \seq_new:N \g_@@_print_labelseq_queue_seq
2103 \cs_new_protected:Npn \@@_split_labelseq:
2104 {
2105 \group_begin:
2106 \seq_clear:N \l_@@_tmpa_seq
2107 \seq_clear:N \l_@@_tmpb_seq
2108 \bool_if:NTF \g_@@_counteraux_bool
2109 {
2110 \tl_set:Ne \l_@@_tmpa_tl
2111 { { print } { \int_use:N \g_@@_print_postnotes_int } }
2112 % \end{macrocode}
2113 % The \texttt{print} label of a \cs{printpostnotes} at the end of the document
2114 % may not have been written: if it's empty, it may not be shipped out at all.
2115 % But, since it's a counter, stepped sequentially and not floating, even if it
2116 % is transitorily missing, it will be at the end. In other words, if this one
2117 % is not found, there will be no subsequent \texttt{print}s in the sequence.
2118 % \begin{macrocode}
2119 \seq_if_in:NVF \g_@@_labelseq_seq \l_@@_tmpa_tl
2120 { \seq_gput_right:NV \g_@@_labelseq_seq \l_@@_tmpa_tl }
2121 \bool_do_until:nn
2122 { \tl_if_eq_p:NN \l_@@_tmpb_tl \l_@@_tmpa_tl }
2123 {
2124 \seq_gpop_left:NN \g_@@_labelseq_seq \l_@@_tmpb_tl
2125 \str_case:enT
2126 { \tl_item:Nn \l_@@_tmpb_tl { 1 } }
2127 {
2128 { mark } { }
2129 { section } { }
2130 }
2131 {
2132 % \end{macrocode}
2133 % If the id of the labelseq item is larger than the current note id, we don't
2134 % have data for the note at this point, and cannot print it. Period. Now,
2135 % usually this will occur due to transitory effects. But it is theoretically
2136 % possible that a float is sent to the top of the page and gets typeset before
2137 % a ``future \cs{printpostnotes}''. So what we cannot print, we give back to
2138 % the label sequence of the next \cs{printpostnotes}. If they are transitory,
2139 % they will eventually go away. If they are not, better to keep them with the
2140 % wrong numbering than dropping it altogether. Alas, there's nothing else we
2141 % could do, short of writing the whole data to the \file{.aux} file, which is
2142 % clearly not worth this corner case.
2143 % \begin{macrocode}
2144 \int_compare:nNnTF
2145 { \tl_item:Nn \l_@@_tmpb_tl { 2 } }
2146 >
2147 { \g_@@_note_id_int }
2148 {
2149 \seq_put_right:Ne \l_@@_tmpb_seq
2150 \l_@@_tmpb_tl
2151 }
2152 {
2153 \seq_put_right:Ne \l_@@_tmpa_seq
2154 { \tl_item:Nn \l_@@_tmpb_tl { 2 } }
2155 }
2156 }
2157 % \end{macrocode}
2158 % No need for the \texttt{F} branch of \cs{str_case:enT}, at this point the
2159 % \texttt{print} label of past \cs{printpostnotes} can no longer be here, and
2160 % we don't go further than the current one. In theory, we could even go
2161 % without \cs{str_case:enT}, but let's play safe and keep the function robust
2162 % against future changes of the code.
2163 % \begin{macrocode}
2164 }
2165 \seq_gset_eq:NN \g_@@_print_labelseq_queue_seq
2166 \l_@@_tmpa_seq
2167 \seq_concat:NNN \l_@@_tmpa_seq \l_@@_tmpb_seq
2168 \g_@@_labelseq_seq
2169 \seq_gset_eq:NN \g_@@_labelseq_seq \l_@@_tmpa_seq
2170 }
2171 {
2172 \seq_map_inline:Nn \g_@@_labelseq_seq
2173 {
2174 \str_case:enT
2175 { \tl_item:nn { ##1 } { 1 } }
2176 {
2177 { mark } { }
2178 { section } { }
2179 }
2180 {
2181 \int_compare:nNnTF
2182 { \tl_item:nn { ##1 } { 2 } }
2183 >
2184 { \g_@@_note_id_int }
2185 { \seq_put_right:Nn \l_@@_tmpb_seq { ##1 } }
2186 {
2187 \seq_put_right:Ne \l_@@_tmpa_seq
2188 { \tl_item:nn { ##1 } { 2 } }
2189 }
2190 }
2191 % \end{macrocode}
2192 % Also no need for the \texttt{F} branch here, but for a different reason.
2193 % The \texttt{print} label plays no role whatsoever if \opt{couteraux=false},
2194 % so we just drop them altogether if found.
2195 % \begin{macrocode}
2196 }
2197 \seq_gset_eq:NN \g_@@_print_labelseq_queue_seq
2198 \l_@@_tmpa_seq
2199 \seq_gset_eq:NN \g_@@_labelseq_seq \l_@@_tmpb_seq
2200 }
2201 \group_end:
2202 }
2203 % \end{macrocode}
2204 % \end{macro}
2205 %
2206 %
2207 % \cs{@@_check_duplicates:N} provides a general procedure for handling cases
2208 % of multiple passes of content. Ideally, the job should be done at
2209 % \cs{@@_inhibit_note:F}, if at all possible. But, failing that, we can rely
2210 % on the fact that the labels of \cs{postnote}s of measuring/trial passes,
2211 % being delayed \cs{write}s (whatsits), don't end up being written to the
2212 % \file{.aux} file. However, despite this being a general test, and a
2213 % reasonable one, I'd like to restrain it's use to the minimum possible.
2214 % Using this criterion across the board could result in large swings on the
2215 % content of \cs{printpostnotes} and spurious warnings. Hence, we only apply
2216 % this check for ``eligible'' items. For signaling this eligibility, the note
2217 % must have been stored with the \cs{l_@@_maybe_multi_bool} set to
2218 % \texttt{true}, which is then saved in the \texttt{multibool} property. One
2219 % implication of this procedure is that, if there are any new notes marked as
2220 % \texttt{multibool}, three rounds of compilation will be needed, since the
2221 % labels of the printed notes will be written only on the second run and the
2222 % document will thus require a third one to stabilize.
2223 %
2224 % \begin{macro}{\@@_check_duplicates:N}
2225 % \begin{syntax}
2226 % \cs{@@_check_duplicates:N} \meta{\cs{g_@@_print_queue_seq}}
2227 % \end{syntax}
2228 % \begin{macrocode}
2229 \cs_new_protected:Npn \@@_check_duplicates:N #1
2230 {
2231 % \end{macrocode}
2232 % On a first run, don't even try to check for duplicates. Better
2233 % \texttt{transitorily} let some duplicates pass than to drop every legitimate
2234 % note.
2235 % \begin{macrocode}
2236 \bool_lazy_and:nnT
2237 { ! \g_@@_firstrun_bool }
2238 { ! \g_@@_counteraux_bool }
2239 {
2240 \group_begin:
2241 \seq_clear:N \l_@@_tmpa_seq
2242 \seq_map_inline:Nn #1
2243 {
2244 \bool_lazy_or:nnTF
2245 { \cs_if_exist_p:c { \c_@@_ref_prefix_tl @ mark @ ##1 } }
2246 % \end{macrocode}
2247 % Always keep sections. Empty sections are discarded anyway, and they are
2248 % unlikely to occur in places performing multiple passes.
2249 % \begin{macrocode}
2250 {
2251 \str_if_eq_p:ee
2252 { \@@_prop_item:nn {##1} { type } } { section }
2253 }
2254 { \seq_put_right:Nn \l_@@_tmpa_seq {##1} }
2255 {
2256 % \end{macrocode}
2257 % If \texttt{multibool} is true for the note, we drop it silently, otherwise
2258 % we include it, but warn of possible duplicate.
2259 % \begin{macrocode}
2260 \str_if_eq:eeF
2261 { \@@_prop_item:nn {##1} { multibool } }
2262 { true }
2263 {
2264 \seq_put_right:Nn \l_@@_tmpa_seq {##1}
2265 \bool_if:NT \l_@@_check_dupli_bool
2266 {
2267 \msg_warning:nne { postnotes } { possible-duplicate }
2268 { \@@_prop_item:nn {##1} { mark } }
2269 }
2270 }
2271 }
2272 }
2273 \seq_gset_eq:NN #1 \l_@@_tmpa_seq
2274 \group_end:
2275 }
2276 }
2277 % \end{macrocode}
2278 % \end{macro}
2279 %
2280 % \begin{macrocode}
2281 \msg_new:nnn { postnotes } { possible-duplicate }
2282 { Possible~duplicate~*around*~note~'#1'~\msg_line_context:. }
2283 % \end{macrocode}
2284 %
2285 %
2286 % \begin{macro}{\@@_check_floats:N}
2287 % \begin{syntax}
2288 % \cs{@@_check_floats:N} \meta{\cs{g_@@_print_queue_seq}}
2289 % \end{syntax}
2290 % \begin{macrocode}
2291 \cs_new_protected:Npn \@@_check_floats:N #1
2292 {
2293 \bool_lazy_and:nnT
2294 { \l_@@_check_floats_bool }
2295 % \end{macrocode}
2296 % Ditto. In this case, the queue is not touched, but it would still be a
2297 % spurious warning.
2298 % \begin{macrocode}
2299 { ! \g_@@_firstrun_bool }
2300 {
2301 \group_begin:
2302 % \end{macrocode}
2303 % Only compare sequence net of non-existing labels.
2304 % \begin{macrocode}
2305 \seq_set_filter:NNn \l_@@_tmpa_seq #1
2306 {
2307 \bool_lazy_or_p:nn
2308 { \cs_if_exist_p:c { \c_@@_ref_prefix_tl @ mark @ ##1 } }
2309 { \cs_if_exist_p:c { \c_@@_ref_prefix_tl @ section @ ##1 } }
2310 }
2311 % \end{macrocode}
2312 % Not very \texttt{expl3}-y, I know. But I don't see a \cs{seq_if_eq:NNTF}
2313 % available and, technically, sequences are just structured token lists.
2314 % \begin{macrocode}
2315 \tl_if_eq:NNF
2316 \g_@@_print_labelseq_queue_seq \l_@@_tmpa_seq
2317 { \msg_warning:nn { postnotes } { possible-shuffle } }
2318 \group_end:
2319 }
2320 }
2321 % \end{macrocode}
2322 % \end{macro}
2323 %
2324 % \begin{macrocode}
2325 \msg_new:nnn { postnotes } { possible-shuffle }
2326 { Possible~out~of~sequence~notes~due~to~floats~\msg_line_context:. }
2327 % \end{macrocode}
2328 %
2329 %
2330 % \begin{macro}{\@@_sort_queue:N}
2331 % Sorting function for \cs{@@_print_notes:}.
2332 % \begin{syntax}
2333 % \cs{@@_sort_queue:N} \meta{\cs{g_@@_print_queue_seq}}
2334 % \end{syntax}
2335 % \begin{macrocode}
2336 \cs_new_protected:Npn \@@_sort_queue:N #1
2337 {
2338 \bool_if:NT \l_@@_sort_bool
2339 {
2340 \group_begin:
2341 \seq_gsort:Nn #1
2342 {
2343 \@@_prop_get:nnN {##1} { pnsectid } \l_@@_tmpa_tl
2344 \@@_prop_get:nnN {##2} { pnsectid } \l_@@_tmpb_tl
2345 \tl_if_eq:NNTF \l_@@_tmpa_tl \l_@@_tmpb_tl
2346 {
2347 \@@_prop_get:nnN {##1} { type } \l_@@_tmpa_tl
2348 \@@_prop_get:nnN {##2} { type } \l_@@_tmpb_tl
2349 \bool_lazy_and:nnTF
2350 { \str_if_eq_p:Vn \l_@@_tmpa_tl { note } }
2351 { \str_if_eq_p:Vn \l_@@_tmpb_tl { note } }
2352 {
2353 \@@_prop_get:nnN {##1}
2354 { sortnum } \l_@@_tmpa_tl
2355 \@@_prop_get:nnN {##2}
2356 { sortnum } \l_@@_tmpb_tl
2357 \fp_compare:nNnTF
2358 { \l_@@_tmpa_tl } > { \l_@@_tmpb_tl }
2359 { \sort_return_swapped: }
2360 { \sort_return_same: }
2361 }
2362 { \sort_return_same: }
2363 }
2364 { \sort_return_same: }
2365 }
2366 \group_end:
2367 }
2368 }
2369 % \end{macrocode}
2370 % \end{macro}
2371 %
2372 %
2373 % \begin{macrocode}
2374 \AddToHook { enddocument/afterlastpage }
2375 {
2376 \group_begin:
2377 \bool_if:NTF \g_@@_counteraux_bool
2378 {
2379 \seq_set_filter:NNn \l_@@_tmpa_seq \g_@@_labelseq_seq
2380 { \str_if_eq_p:ee { \tl_item:nn {#1} { 1 } } { mark } }
2381 }
2382 {
2383 \seq_set_filter:NNn \l_@@_tmpa_seq \g_@@_queue_seq
2384 { \str_if_eq_p:ee { \@@_prop_item:nn {#1} { type } } { note } }
2385 }
2386 \seq_if_empty:NF \l_@@_tmpa_seq
2387 {
2388 \msg_warning:nne { postnotes } { stray-notes }
2389 { \seq_count:N \l_@@_tmpa_seq }
2390 }
2391 \group_end:
2392 }
2393 \msg_new:nnn { postnotes } { stray-notes }
2394 {
2395 There~are~'#1'~stray~notes~after~the~last~'\iow_char:N\\printpostnotes'~
2396 \msg_line_context:.~At~this~point,~they~are~lost.
2397 }
2398 % \end{macrocode}
2399 %
2400 %
2401 %
2402 % \section{Headers}
2403 %
2404 % NOTE The use of these variables has been deprecated in 2024-12-03 for v0.5.0.
2405 % The setting of values for them, now based on \pkg{ltmarks} data, is still
2406 % transitionally provided so that users have time to adjust to the new
2407 % mechanism without immediate breakage of existing documents. These variables
2408 % are scheduled to be removed though, and users \emph{must} migrate. Not only
2409 % that, these values have been less intensively tested, and also require one
2410 % compilation run more to converge. So there's also a clear benefit in
2411 % migrating sooner rather than later.
2412 %
2413 % \begin{macrocode}
2414 \bool_new:N \l_@@_deprecated_headervars_bool
2415 \keys_define:nn { postnotes/setup }
2416 {
2417 deprecatedheadervars .bool_set:N = \l_@@_deprecated_headervars_bool ,
2418 deprecatedheadervars .default:n = true ,
2419 deprecatedheadervars .initial:n = false ,
2420 }
2421 \AddToHook { begindocument }
2422 {
2423 \keys_define:nn { postnotes/setup }
2424 {
2425 deprecatedheadervars .code:n =
2426 {
2427 \msg_warning:nnn { postnotes }
2428 { option-preamble-only } { deprecatedheadervars }
2429 } ,
2430 }
2431 }
2432 \tl_new:N \pnhdpagefirst
2433 \tl_new:N \pnhdpagelast
2434 \tl_new:N \pnhdchapfirst
2435 \tl_new:N \pnhdchaplast
2436 \tl_new:N \pnhdsectfirst
2437 \tl_new:N \pnhdsectlast
2438 \tl_new:N \pnhdnamefirst
2439 \tl_new:N \pnhdnamelast
2440 \tl_gset:Nn \pnhdpagefirst
2441 { \msg_error:nnn { postnotes } { deprecatedheadervars } { pnhdpagefirst } }
2442 \tl_gset:Nn \pnhdpagelast
2443 { \msg_error:nnn { postnotes } { deprecatedheadervars } { pnhdpagelast } }
2444 \tl_gset:Nn \pnhdchapfirst
2445 { \msg_error:nnn { postnotes } { deprecatedheadervars } { pnhdchapfirst } }
2446 \tl_gset:Nn \pnhdchaplast
2447 { \msg_error:nnn { postnotes } { deprecatedheadervars } { pnhdchaplast } }
2448 \tl_gset:Nn \pnhdsectfirst
2449 { \msg_error:nnn { postnotes } { deprecatedheadervars } { pnhdsectfirst } }
2450 \tl_gset:Nn \pnhdsectlast
2451 { \msg_error:nnn { postnotes } { deprecatedheadervars } { pnhdsectlast } }
2452 \tl_gset:Nn \pnhdnamefirst
2453 { \msg_error:nnn { postnotes } { deprecatedheadervars } { pnhdnamefirst } }
2454 \tl_gset:Nn \pnhdnamelast
2455 { \msg_error:nnn { postnotes } { deprecatedheadervars } { pnhdnamelast } }
2456 \msg_new:nnn { postnotes } { deprecatedheadervars }
2457 {
2458 '\iow_char:N\\ #1'~is~deprecated~\msg_line_context:.~
2459 You~should~migrate~to~the~new~'ltmarks'~(see~User~manual),~but~for~
2460 a~temporary~quick~fix~you~can~enable~the~'deprecatedheadervars'~option.
2461 }
2462 \cs_set_eq:NN \@@_set_header_vars_first: \prg_do_nothing:
2463 \cs_set_eq:NN \@@_set_header_vars_bool: \prg_do_nothing:
2464 % \end{macrocode}
2465 %
2466 % \begin{macrocode}
2467 \AddToHook { begindocument }
2468 {
2469 \bool_if:NT \l_@@_deprecated_headervars_bool
2470 {
2471 \property_new:nnnn { postnotes/page/first } { shipout } { }
2472 { \FirstMark { postnotes/page } }
2473 \property_new:nnnn { postnotes/page/last } { shipout } { }
2474 { \LastMark { postnotes/page } }
2475 \property_new:nnnn { postnotes/chapter/first } { shipout } { }
2476 { \FirstMark { postnotes/chapter } }
2477 \property_new:nnnn { postnotes/chapter/last } { shipout } { }
2478 { \LastMark { postnotes/chapter } }
2479 \property_new:nnnn { postnotes/section/first } { shipout } { }
2480 { \FirstMark { postnotes/section } }
2481 \property_new:nnnn { postnotes/section/last } { shipout } { }
2482 { \LastMark { postnotes/section } }
2483 \property_new:nnnn { postnotes/sectname/first } { shipout } { }
2484 { \FirstMark { postnotes/sectname } }
2485 \property_new:nnnn { postnotes/sectname/last } { shipout } { }
2486 { \LastMark { postnotes/sectname } }
2487 \clist_const:Nn \c_@@_header_marks_clist
2488 {
2489 postnotes/page/first ,
2490 postnotes/page/last ,
2491 postnotes/chapter/first ,
2492 postnotes/chapter/last ,
2493 postnotes/section/first ,
2494 postnotes/section/last ,
2495 postnotes/sectname/first ,
2496 postnotes/sectname/last ,
2497 }
2498 \cs_new_protected:Npn \@@_set_header_vars:n #1
2499 {
2500 \group_begin:
2501 \protected@xdef \pnhdpagefirst
2502 { \property_ref:nn { #1 } { postnotes/page/first } }
2503 \protected@xdef \pnhdpagelast
2504 { \property_ref:nn { #1 } { postnotes/page/last } }
2505 \protected@xdef \pnhdchapfirst
2506 { \property_ref:nn { #1 } { postnotes/chapter/first } }
2507 \protected@xdef \pnhdchaplast
2508 { \property_ref:nn { #1 } { postnotes/chapter/last } }
2509 \protected@xdef \pnhdsectfirst
2510 { \property_ref:nn { #1 } { postnotes/section/first } }
2511 \protected@xdef \pnhdsectlast
2512 { \property_ref:nn { #1 } { postnotes/section/last } }
2513 \protected@xdef \pnhdnamefirst
2514 { \property_ref:nn { #1 } { postnotes/sectname/first } }
2515 \protected@xdef \pnhdnamelast
2516 { \property_ref:nn { #1 } { postnotes/sectname/last } }
2517 \group_end:
2518 }
2519 \cs_generate_variant:Nn \@@_set_header_vars:n { e }
2520 \bool_new:N \g_@@_header_vars_next_bool
2521 \int_new:N \g_@@_print_header_vars_int
2522 \cs_new_protected:Npn \@@_set_headers_vars_next:
2523 {
2524 \bool_if:NT \g_@@_header_vars_next_bool
2525 {
2526 \int_gincr:N \g_@@_print_header_vars_int
2527 \exp_args:Ne \property_record:nN
2528 {
2529 __postnotes_header_
2530 \int_use:N \g_@@_print_header_vars_int
2531 }
2532 \c_@@_header_marks_clist
2533 \@@_set_header_vars:e
2534 {
2535 __postnotes_header_
2536 \int_use:N \g_@@_print_header_vars_int
2537 }
2538 }
2539 }
2540 \AddToHook { shipout/before } [ ./header ]
2541 { \@@_set_headers_vars_next: }
2542 \cs_set_protected:Npn \@@_set_header_vars_first:
2543 {
2544 \bool_gset_true:N \g_@@_header_vars_next_bool
2545 \tl_gset:Nn \pnhdpagefirst { \FirstMark{postnotes/page} }
2546 \tl_gset:Nn \pnhdpagelast { \LastMark{postnotes/page} }
2547 \tl_gset:Nn \pnhdchapfirst { \FirstMark{postnotes/chapter} }
2548 \tl_gset:Nn \pnhdchaplast { \LastMark{postnotes/chapter} }
2549 \tl_gset:Nn \pnhdsectfirst { \FirstMark{postnotes/section} }
2550 \tl_gset:Nn \pnhdsectlast { \LastMark{postnotes/section} }
2551 \tl_gset:Nn \pnhdnamefirst { \FirstMark{postnotes/sectname} }
2552 \tl_gset:Nn \pnhdnamelast { \LastMark{postnotes/sectname} }
2553 \int_gincr:N \g_@@_print_header_vars_int
2554 \exp_args:Ne \property_record:nN
2555 {
2556 __postnotes_header_
2557 \int_use:N \g_@@_print_header_vars_int
2558 }
2559 \c_@@_header_marks_clist
2560 \@@_set_header_vars:e
2561 {
2562 __postnotes_header_
2563 \int_use:N \g_@@_print_header_vars_int
2564 }
2565 }
2566 \cs_set_protected:Npn \@@_set_header_vars_bool:
2567 {
2568 \AddToHookNext { shipout/after }
2569 { \bool_gset_false:N \g_@@_header_vars_next_bool }
2570 }
2571 }
2572 }
2573 % \end{macrocode}
2574 %
2575 %
2576 % \section{Compatibility}
2577 %
2578 % A dedicated temp variable for restoring data.
2579 %
2580 % \begin{macrocode}
2581 \tl_new:N \l_@@_restore_tmp_tl
2582 % \end{macrocode}
2583 %
2584 % \subsection*{\cs{caption}}
2585 %
2586 % For \cs{caption}'s possible two passes. This catches more than just
2587 % captions, of course, but is not overkill. A hook to \cs{@makecaption} would
2588 % be better, but \pkg{ltcmdhooks} does not allow it, and using lower level
2589 % methods for this is a bad idea.
2590 %
2591 % From the user's perspective, one-line captions will just work. For two-line
2592 % captions, there are two alternatives: i)
2593 % \texttt{\textbackslash{}stepcounter\{postnote\}} before the caption, then
2594 % call \cs{postnote} with \texttt{mark=\textbackslash{}arabic\{postnote\}}; or
2595 % ii) right before the caption, call
2596 % \texttt{\textbackslash{}postnote[nomark]\{\textbackslash{}label\{mynote\}...\}},
2597 % then use \texttt{\textbackslash{}postnoteref\{mynote\}} inside the caption.
2598 %
2599 % \begin{macrocode}
2600 \AddToHook { postnotes/note/begin } [ ./compat/caption ]
2601 { \cs_if_exist:NT \@captype { \postnotesetup { maybemulti } } }
2602 % \end{macrocode}
2603 %
2604 %
2605 % \subsection*{\pkg{biblatex}}
2606 %
2607 % Thanks \contributor{Moritz Wemheuer}:
2608 % \url{https://tex.stackexchange.com/q/597359#comment1594585_597389}.
2609 %
2610 %
2611 % \begin{macrocode}
2612 \AddToHook { package/biblatex/after } [ ./compat/biblatex ]
2613 {
2614 % \end{macrocode}
2615 % Let \pkg{biblatex} know we are in a ``notes'' context. See
2616 % \url{https://tex.stackexchange.com/a/304464}, including comments.
2617 % \begin{macrocode}
2618 \AddToHook { postnotes/print/begin } [ postnotes/compat/biblatex ]
2619 { \toggletrue { blx@footnote } }
2620 % \end{macrocode}
2621 % Make \pkg{biblatex}'s \cs{mkbibendnote} use \cs{postnote}. This is very
2622 % likely desired in most cases, but may occasionally not be, so we add it to
2623 % an individually labeled hook, which can be disabled with
2624 % \texttt{\textbackslash{}RemoveFromHook\{begindocument/before\}[postnotes/mkbibendnote]}
2625 % in the preamble.
2626 % \begin{macrocode}
2627 \AddToHook { begindocument/before } [ postnotes/compat/biblatex ]
2628 {
2629 \cs_set:Npn \blx@theendnote { \postnote }
2630 \cs_set:Npn \blx@theendnotetext { \blx@err@endnote \footnotetext }
2631 }
2632 }
2633 % \end{macrocode}
2634 %
2635 %
2636 % \begin{macrocode}
2637 %<*gobble>
2638 % \end{macrocode}
2639 %
2640 % I had made an initial experimental attempt to support \pkg{biblatex}'s
2641 % \texttt{refsegment}s, \texttt{refcontext}s and \texttt{refsection}s.
2642 % However, this attempt was rash. Even if I could get many example files to
2643 % work for \texttt{refsegment}s and \texttt{refcontext}s, I could not do so
2644 % for \texttt{refsection}s. More importantly, with this partial
2645 % implementation, I could also generate documents which confused
2646 % \pkg{biblatex} more than it helped. Things I couldn't understand well, or
2647 % fix. All in all, I don't think this partial implementation is tenable, and
2648 % I could not take it further. Hence, \pkg{postnotes} support for this
2649 % feature set of \pkg{biblatex} will depend, as it should, on proper upstream
2650 % support for ``saving'' and ``restoring'' citation ``context'' information.
2651 %
2652 % I have made a feature request at \pkg{biblatex} for this
2653 % (\url{https://github.com/plk/biblatex/issues/1226}), which was
2654 % (understandably) classified as ``long term, no promises''.
2655 %
2656 %
2657 % The attempt was the following (currently ``gobbled'' from the package):
2658 %
2659 % \begin{macrocode}
2660 \AddToHook { package/biblatex/after } [ ./compat/biblatex ]
2661 {
2662 % \end{macrocode}
2663 % Store \pkg{biblatex} variables for each note.
2664 % \begin{macrocode}
2665 \AddToHook { postnotes/note/store } [ postnotes/compat/biblatex ]
2666 {
2667 \prop_gput:cne { \@@_data_name:e { \l_postnotes_note_id_tl } }
2668 { biblatex@refsection } { \int_use:N \c@refsection }
2669 \prop_gput:cne { \@@_data_name:e { \l_postnotes_note_id_tl } }
2670 { biblatex@refsegment } { \int_use:N \c@refsegment }
2671 \prop_gput:cne { \@@_data_name:e { \l_postnotes_note_id_tl } }
2672 { biblatex@refcontextbool }
2673 { \iftoggle { blx@refcontext } { true } { false } }
2674 \prop_gput:cnV { \@@_data_name:e { \l_postnotes_note_id_tl } }
2675 { biblatex@refcontext } \blx@refcontext@context
2676 }
2677 % \end{macrocode}
2678 % \pkg{biblatex} setup, once for \cs{printpostnotes} call.
2679 % \begin{macrocode}
2680 \AddToHook { postnotes/print/begin } [ postnotes/compat/biblatex ]
2681 {
2682 \@@_biblatex_endrefcontext_local:
2683 \@@_biblatex_citereset_local:
2684 }
2685 % \end{macrocode}
2686 % Restore \pkg{biblatex} variables for each note.
2687 % \begin{macrocode}
2688 \AddToHook { postnotes/print/note/begin } [ postnotes/compat/biblatex ]
2689 {
2690 \@@_prop_get:nnN { \l_postnotes_print_note_id_tl }
2691 { biblatex@refsection } \l_@@_restore_tmp_tl
2692 \int_set:Nn \c@refsection { \l_@@_restore_tmp_tl }
2693 \@@_prop_get:nnN { \l_postnotes_print_note_id_tl }
2694 { biblatex@refsegment } \l_@@_restore_tmp_tl
2695 \int_set:Nn \c@refsegment { \l_@@_restore_tmp_tl }
2696 \@@_prop_get:nnN { \l_postnotes_print_note_id_tl }
2697 { biblatex@refcontextbool } \l_@@_restore_tmp_tl
2698 \use:c { toggle \l_@@_restore_tmp_tl } { blx@refcontext }
2699 \@@_prop_get:nnN { \l_postnotes_print_note_id_tl }
2700 { biblatex@refcontext } \l_@@_restore_tmp_tl
2701 \blx@edef@refcontext { \l_@@_restore_tmp_tl }
2702 }
2703 % \end{macrocode}
2704 % Auxiliary functions.
2705 %
2706 % \begin{macro}{\@@_biblatex_endrefcontext_local:}
2707 % Replicate the job of \cs{endrefcontext}, but with local effects,
2708 % restrained to the group of \cs{printpostnotes}.
2709 % \begin{macrocode}
2710 \cs_new_protected:Npn \@@_biblatex_endrefcontext_local:
2711 {
2712 \togglefalse { blx@refcontext }
2713 \tl_clear:N \blx@refcontext@labelprefix
2714 \tl_clear:N \blx@refcontext@labelprefix@real
2715 \tl_set:Ne \blx@refcontext@sortingtemplatename { \blx@sorting }
2716 \tl_set:Nn \blx@refcontext@sortingnamekeytemplatename { global }
2717 \tl_set:Nn \blx@refcontext@uniquenametemplatename { global }
2718 \tl_set:Nn \blx@refcontext@labelalphanametemplatename { global }
2719 \blx@edef@refcontext
2720 {
2721 \blx@refcontext@sortingtemplatename /
2722 \blx@refcontext@sortingnamekeytemplatename /
2723 /
2724 \blx@refcontext@uniquenametemplatename /
2725 \blx@refcontext@labelalphanametemplatename
2726 }
2727 }
2728 % \end{macrocode}
2729 % \end{macro}
2730 %
2731 % \begin{macro}{\@@_biblatex_citereset_local:}
2732 % Replicate the job of \cs{citereset}, but with local effects, restrained to
2733 % the group of \cs{printpostnotes}.
2734 % \begin{macrocode}
2735 \cs_new_protected:Npn \@@_biblatex_citereset_local:
2736 {
2737 % \end{macrocode}
2738 % \noindent
2739 % {\em\scriptsize\verb|\global\cslet{blx@bsee@\the\c@refsection}\@empty|} \\
2740 % {\em\scriptsize\verb|\global\cslet{blx@fsee@\the\c@refsection}\@empty|}
2741 % \begin{macrocode}
2742 \tl_clear:c { blx@bsee@ \int_use:N \c@refsection }
2743 \tl_clear:c { blx@fsee@ \int_use:N \c@refsection }
2744 % \end{macrocode}
2745 % {\em\scriptsize\verb|\blx@ibidreset@force|}
2746 % \begin{macrocode}
2747 \undef \blx@lastkey@text
2748 \undef \blx@lastkey@foot
2749 % \end{macrocode}
2750 % {\em\scriptsize\verb|\blx@idemreset@force|}
2751 % \begin{macrocode}
2752 \undef \blx@lasthash@text
2753 \undef \blx@lasthash@foot
2754 % \end{macrocode}
2755 % {\em\scriptsize\verb|\blx@opcitreset@force|}
2756 % \begin{macrocode}
2757 \clist_map_inline:Nn \blx@trackhash@text
2758 { \csundef { blx@lastkey@text@ ##1 } }
2759 \tl_clear:N \blx@trackhash@text
2760 \clist_map_inline:Nn \blx@trackhash@foot
2761 { \csundef { blx@lastkey@foot@ ##1 } }
2762 \tl_clear:N \blx@trackhash@foot
2763 % \end{macrocode}
2764 % {\em\scriptsize\verb|\blx@loccitreset@force|}
2765 % \begin{macrocode}
2766 \clist_map_inline:Nn \blx@trackkeys@text
2767 { \csundef { blx@lastnote@text@ ##1 } }
2768 \tl_clear:N \blx@trackkeys@text
2769 \clist_map_inline:Nn \blx@trackkeys@foot
2770 { \csundef { blx@lastnote@foot@ ##1 } }
2771 \tl_clear:N \blx@trackkeys@foot
2772 % \end{macrocode}
2773 % {\em\scriptsize{}and all of them do:}
2774 % \begin{macrocode}
2775 \cs_set_eq:NN \blx@lastmpfn \z@
2776 }
2777 % \end{macrocode}
2778 % \end{macro}
2779 %
2780 % \begin{macrocode}
2781 }
2782 % \end{macrocode}
2783 %
2784 % \pkg{biblatex}'s \texttt{refsections}, contrary to \texttt{refsegment}s and
2785 % \texttt{refcontext}s which are handled in the \LaTeX{} side of things (as
2786 % far as I can tell), need to go through \texttt{biber}, and must have correct
2787 % corresponding citation data written to the \file{.bcf} file. And the way
2788 % \cs{refsection} is implemented presumes each section is only ever begun once
2789 % (fair\dots{}), thus making it difficult to ``reopen'' it, or append new
2790 % citations to it later on, when the notes are printed. The start of a
2791 % \texttt{refsection} must be registered on the \file{.bcf} file, and this is
2792 % done by \cs{refsection} (and its auxiliary functions). However, a number of
2793 % its characteristics make things particularly difficult for the purpose at
2794 % hand: i) it unconditionally sets a label for the section which, of course,
2795 % cannot be done twice; and, critically, ii) the optional argument of the
2796 % environment (which receives the \meta{resources}) is used to set a local
2797 % assignment to \cs{blx@bibfiles}, based on which the relevant information is
2798 % written to the \file{.bcf} file, and when the group closes the information
2799 % is gone. My best attempt is below but it is not good. It feels a wrong
2800 % approach to ``go around'' the intended use of \cs{refsection} so much, and
2801 % it can't handle at all its optional argument, for the reasons above. It's
2802 % also incomplete, since it does not handle restoring
2803 % \cs{l_@@_biblatex_orig_refsection_tl}.
2804 %
2805 % \begin{macrocode}
2806 \AddToHook { package/biblatex/after } [ ./compat/biblatex ]
2807 {
2808 \tl_new:N \l_@@_biblatex_orig_refsection_tl
2809 \tl_new:N \g_@@_biblatex_prev_refsection_tl
2810 \AddToHook { postnotes/print/begin } [ postnotes/compat/biblatex ]
2811 {
2812 \tl_set:Ne \l_@@_biblatex_orig_refsection_tl
2813 { \int_use:N \c@refsection }
2814 \tl_gset:Ne \g_@@_biblatex_prev_refsection_tl
2815 { \l_@@_biblatex_orig_refsection_tl }
2816 }
2817 \AddToHook { postnotes/print/note/begin } [ postnotes/compat/biblatex ]
2818 {
2819 \@@_prop_get:nnN { \l_postnotes_print_note_id_tl }
2820 { biblatex@refsection } \l_@@_restore_tmp_tl
2821 \tl_if_eq:NNF
2822 \l_@@_restore_tmp_tl
2823 \g_@@_biblatex_prev_refsection_tl
2824 {
2825 \int_set:Nn \c@blx@maxsection
2826 { \l_@@_restore_tmp_tl - 1 }
2827 \tl_gset_eq:NN \g_@@_biblatex_prev_refsection_tl
2828 \l_@@_restore_tmp_tl
2829 \group_begin:
2830 \cs_set_eq:NN \label \use_none:n
2831 \cs_set_eq:NN \blx@info \use_none:n
2832 \blx@endrefsection
2833 \refsection
2834 \group_end:
2835 }
2836 }
2837 }
2838 % \end{macrocode}
2839 %
2840 % \begin{macrocode}
2841 %</gobble>
2842 % \end{macrocode}
2843 %
2844 %
2845 % \subsection*{\pkg{zref-user}}
2846 %
2847 % \begin{macro}{\l_@@_note_zlabel_str}
2848 % Even though the \opt{zlabel} option is provided only when \pkg{zref-user}
2849 % is loaded, \cs{l_@@_note_zlabel_str} must be unconditionally defined,
2850 % since it is presumed to exist by \cs{@@_set_user_labels:} and elsewhere.
2851 % \begin{macrocode}
2852 \str_new:N \l_@@_note_zlabel_str
2853 % \end{macrocode}
2854 % \end{macro}
2855 %
2856 % \begin{macrocode}
2857 \AddToHook { package/zref-user/after } [ ./compat/zref-user ]
2858 {
2859 % \end{macrocode}
2860 % Provide \opt{zlabel} option.
2861 % \begin{macrocode}
2862 \keys_define:nn { postnotes/note }
2863 {
2864 zlabel .str_set:N = \l_@@_note_zlabel_str ,
2865 zlabel .value_required:n = true ,
2866 }
2867 % \end{macrocode}
2868 % Provide property to store the mark for measuring passes.
2869 % \begin{macrocode}
2870 \zref@newprop { postnote@mark } [] { \l_@@_mark_tl }
2871 \AddToHook { postnotes/note/begin } [ postnotes/compat/zref-user ]
2872 { \zref@localaddprop { main } { postnote@mark } }
2873 % \end{macrocode}
2874 %
2875 % \begin{macro}[int]{\postnotezref}
2876 % Provide \cs{postnotezref}.
2877 % \begin{syntax}
2878 % \cs{postnotezref}\meta{*}\marg{label}
2879 % \end{syntax}
2880 % \begin{macrocode}
2881 \NewDocumentCommand \postnotezref { s m }
2882 { \@@_note_zref:nn {#1} {#2} }
2883 % \end{macrocode}
2884 % \end{macro}
2885 %
2886 % \begin{macro}{\@@_note_zref:nn}
2887 % The internal version of \cs{postnotezref}.
2888 % \begin{syntax}
2889 % \cs{@@_note_zref:nn} \Arg{star bool} \Arg{label}
2890 % \end{syntax}
2891 % \begin{macrocode}
2892 \str_new:N \l_@@_note_zref_zlabel_str
2893 \cs_new_protected:Npn \@@_note_zref:nn #1#2
2894 {
2895 \group_begin:
2896 \str_set:Nn \l_@@_note_zref_zlabel_str {#2}
2897 \@@_typeset_mark_wrapper:nnn
2898 {
2899 \bool_lazy_all:nTF
2900 {
2901 { ! #1 }
2902 { \l_@@_hyperlink_bool }
2903 { \l_@@_zrefhyperref_bool }
2904 }
2905 {
2906 \hyperlink
2907 { \zref@extractdefault {#2} { anchor } { } }
2908 { \@@_make_mark:nnn { \zref{#2} } { } { } }
2909 }
2910 { \@@_make_mark:nnn { \zref{#2} } { } { } }
2911 }
2912 { \tag_socket_use:n { postnotes/postnotezref/begin } }
2913 { \tag_socket_use:n { postnotes/postnotezref/end } }
2914 \group_end:
2915 }
2916 % \end{macrocode}
2917 % \end{macro}
2918 %
2919 % \begin{macrocode}
2920 }
2921 % \end{macrocode}
2922 %
2923 % \begin{macrocode}
2924 \bool_new:N \l_@@_zrefhyperref_bool
2925 \AddToHook { package/zref-hyperref/after } [ ./compat/zref-hyperref ]
2926 { \bool_set_true:N \l_@@_zrefhyperref_bool }
2927 % \end{macrocode}
2928 %
2929 %
2930 % \subsection*{\pkg{zref-clever}}
2931 %
2932 % \begin{macrocode}
2933 \AddToHook { package/zref-clever/after } [ ./compat/zref-clever ]
2934 {
2935 \zcsetup
2936 {
2937 countertype = { postnote = endnote } ,
2938 countertype = { postnotetext = endnote } ,
2939 }
2940 \AddToHook { postnotes/print/begin } [ postnotes/compat/zref-clever ]
2941 { \zcsetup { counterresetby = { postnotetext = postnotesection } } }
2942 }
2943 % \end{macrocode}
2944 %
2945 %
2946 % \subsection*{\pkg{zref-check}}
2947 %
2948 % \begin{macrocode}
2949 \AddToHook { package/zref-check/after } [ ./compat/zref-check ]
2950 {
2951 \IfPackageAtLeastTF { zref-check } { 2022-07-05 }
2952 {
2953 \AddToHook { postnotes/note/store } [ postnotes/compat/zref-check ]
2954 {
2955 \prop_gput:cne { \@@_data_name:e { \l_postnotes_note_id_tl } }
2956 { zref-check@abschap } { \int_use:N \c@zc@abschap }
2957 \prop_gput:cne { \@@_data_name:e { \l_postnotes_note_id_tl } }
2958 { zref-check@abssec } { \int_use:N \c@zc@abssec }
2959 }
2960 \AddToHook { postnotes/print/note/begin } [ postnotes/compat/zref-check ]
2961 {
2962 \@@_prop_get:nnN { \l_postnotes_print_note_id_tl }
2963 { zref-check@abschap } \l_@@_restore_tmp_tl
2964 \int_set:Nn \c@zc@abschap { \l_@@_restore_tmp_tl }
2965 \@@_prop_get:nnN { \l_postnotes_print_note_id_tl }
2966 { zref-check@abssec } \l_@@_restore_tmp_tl
2967 \int_set:Nn \c@zc@abssec { \l_@@_restore_tmp_tl }
2968 }
2969 }
2970 { }
2971 }
2972 % \end{macrocode}
2973 %
2974 %
2975 % \subsection*{\pkg{amsmath}}
2976 %
2977 % \begin{macrocode}
2978 \AddToHook { package/amsmath/after } [ ./compat/amsmath ]
2979 {
2980 % \end{macrocode}
2981 % Testing for \cs{ifmeasuring@} is sufficient to get things right for the
2982 % measuring passes in math environments.
2983 % \begin{macrocode}
2984 \AddToHook { postnotes/note/inhibit } [ postnotes/compat/amsmath ]
2985 {
2986 \legacy_if:nT { measuring@ }
2987 {
2988 \bool_set_true:N \l_@@_inhibit_note_bool
2989 \bool_set_true:N \l_@@_print_plain_mark_bool
2990 \bool_set_true:N \l_@@_print_plain_mark_stepcounter_bool
2991 }
2992 }
2993 % \end{macrocode}
2994 % However, the \cs{text} macro, defined by \pkg{amstext} (required by
2995 % \pkg{amsmath}), poses problems if its own. Despite my best efforts, I could
2996 % not salvage things from the use of \cs{mathchoice} and the redefinitions of
2997 % \cs{setcounter} and \cs{addtocounter} performed by \pkg{amstext}. Setting
2998 % \opt{maybemulti} when \texttt{firstchoice@} is \texttt{false} grants us a
2999 % working situation for display style. But the use of \cs{postnote} inside
3000 % \cs{text} (and, if \pkg{amsmath} is loaded, \cs{textnormal}, \cs{textup},
3001 % etc.) in inline math environments is not supported. If a note really needs
3002 % to be there, one can use the \opt{nomark} option and \cs{postnoteref}.
3003 % Things should work in text mode and in display style. For some related
3004 % discussion with regard to footnotes, see
3005 % \url{https://tex.stackexchange.com/a/82820} and, in particular, Barbara
3006 % Beeton's comment: ``This is certainly bravura code. I do hope it doesn't
3007 % result in a request to add \cs{footnote} capabilities to \pkg{amsmath}'s
3008 % multi-line display facilities. (The answer will almost certainly be "no".
3009 % We agree with Kopka \& Daly.)''
3010 % \begin{macrocode}
3011 \AddToHook { postnotes/note/begin } [ postnotes/compat/amsmath ]
3012 { \legacy_if:nF { firstchoice@ } { \postnotesetup { maybemulti } } }
3013 }
3014 % \end{macrocode}
3015 %
3016 %
3017 % \subsection*{\pkg{csquotes}}
3018 %
3019 % \begin{macrocode}
3020 \AddToHook { package/csquotes/after } [ ./compat/csquotes ]
3021 {
3022 \bool_new:N \l_@@_csquotes_measuring_bool
3023 \BlockquoteDisable
3024 { \bool_set_true:N \l_@@_csquotes_measuring_bool }
3025 \AddToHook { postnotes/note/inhibit } [ postnotes/compat/csquotes ]
3026 {
3027 \bool_if:NT \l_@@_csquotes_measuring_bool
3028 {
3029 \bool_set_true:N \l_@@_inhibit_note_bool
3030 \bool_set_true:N \l_@@_print_plain_mark_bool
3031 \bool_set_true:N \l_@@_print_plain_mark_stepcounter_bool
3032 }
3033 }
3034 }
3035 % \end{macrocode}
3036 %
3037 %
3038 % \subsection*{\pkg{tabularx}}
3039 %
3040 % For the identification of the trial passes in \pkg{tabularx}, see
3041 % \url{https://tex.stackexchange.com/a/640035} (including discussion in the
3042 % comments, thanks \contributor{David Carlisle}), and also
3043 % \url{https://tex.stackexchange.com/a/227155} and
3044 % \url{https://tex.stackexchange.com/a/352134}.
3045 %
3046 % \begin{macrocode}
3047 \AddToHook { package/tabularx/after } [ ./compat/tabularx ]
3048 {
3049 \bool_new:N \l_@@_tabularx_inside_env_bool
3050 \AddToHook { env/tabularx/begin } [ postnotes/compat/tabularx ]
3051 {
3052 \bool_set_true:N \l_@@_tabularx_inside_env_bool
3053 \cs_set_eq:NN \@@_tabularx_saved_write:Nn \write
3054 }
3055 \AddToHook { postnotes/note/inhibit } [ postnotes/compat/tabularx ]
3056 {
3057 \bool_lazy_and:nnT
3058 { \l_@@_tabularx_inside_env_bool }
3059 { ! \cs_if_eq_p:NN \write \@@_tabularx_saved_write:Nn }
3060 {
3061 \bool_set_true:N \l_@@_inhibit_note_bool
3062 \bool_set_true:N \l_@@_print_plain_mark_bool
3063 \bool_set_true:N \l_@@_print_plain_mark_stepcounter_bool
3064 }
3065 }
3066 \AddToHook { package/xltabular/after } [ postnotes/compat/xltabular ]
3067 {
3068 \AddToHook { env/xltabular/begin } [ postnotes/compat/xltabular ]
3069 {
3070 \bool_set_true:N \l_@@_tabularx_inside_env_bool
3071 \cs_set_eq:NN \@@_tabularx_saved_write:Nn \write
3072 }
3073 }
3074 }
3075 % \end{macrocode}
3076 %
3077 %
3078 % \subsection*{\pkg{tabularray}}
3079 %
3080 % \begin{macrocode}
3081 \AddToHook { package/tabularray/after } [ ./compat/tabularray ]
3082 {
3083 % \end{macrocode}
3084 % Since version \texttt{2023A}, from 2023-03-01, \pkg{tabularray} offers the
3085 % \cs{lTblrMeasuringBool} which is true when measuring and false otherwise.
3086 % See \url{https://tex.stackexchange.com/q/675818}
3087 % and \url{https://github.com/lvjr/tabularray/issues/179} (thanks
3088 % \contributor{Ulrike Fischer}).
3089 % \begin{macrocode}
3090 \bool_if_exist:NT \lTblrMeasuringBool
3091 {
3092 % \end{macrocode}
3093 % I'd be inclined to restrict the inhibition effect to known \pkg{tabularray}
3094 % environments to ``keep things under control''. However this is a dedicated
3095 % and public boolean, and users can create arbitrary new \pkg{tabularray}
3096 % environments with \cs{NewTblrEnviron}, which we either wouldn't catch or
3097 % have to provide an user interface for. So, for the time being, let's trust
3098 % this boolean won't be misused by third-parties or users. Note that setting
3099 % \cs{l_@@_print_plain_mark_stepcounter_bool} to true presumes
3100 % \pkg{tabularray}'s \texttt{counter} module is enabled. But, since this is
3101 % the only way to get the measuring right in this context if there is more
3102 % than one \cs{postnote} inside a given table, \pkg{postnotes} expects and
3103 % requires the \texttt{counter} module.
3104 % \begin{macrocode}
3105 \AddToHook { postnotes/note/inhibit } [ postnotes/compat/tabularray ]
3106 {
3107 \bool_if:NT \lTblrMeasuringBool
3108 {
3109 \bool_set_true:N \l_@@_inhibit_note_bool
3110 \bool_set_true:N \l_@@_print_plain_mark_bool
3111 \bool_set_true:N \l_@@_print_plain_mark_stepcounter_bool
3112 }
3113 }
3114 }
3115 }
3116 % \end{macrocode}
3117 %
3118 %
3119 % \subsection*{PDF Tagging (experimental)}
3120 %
3121 % Note: All of this mostly presumes
3122 % \texttt{\cs{DocumentMetadata}\{testphase=phase-III\}} and was tested with
3123 % it. For \opt{listenv=none}, I'd expect things to work with
3124 % \texttt{phase-II}, but this is only lightly tested.
3125 %
3126 % A first thing to consider in tagging endnotes is how we want to represent
3127 % them in the PDF structure. My first thought, for lack of another, was:
3128 % emulate footnotes. There's no relevant semantic difference at the structure
3129 % level between the two, and the tagging support for footnotes was done by the
3130 % pros. And one distinctive characteristic the the footnotes tagging is that
3131 % the footnote itself is placed in the structure as a child to the (parent)
3132 % \texttt{text} element which surrounds the footnote mark. However, for
3133 % endnotes this introduces a number of problems and complicates things. While
3134 % footnotes ``float around'' and have no real structure of their own, that is
3135 % not true for endnotes. Endnotes comprise a proper document section, and may
3136 % be printed in a list environment, etc. So when the tagging of footnotes
3137 % places the footnote structure element as a child element of the mark's
3138 % surrounding text, this is arguably for a lack of other options. Where else,
3139 % after all? Indeed, a typical \texttt{html} would render footnotes at the
3140 % end of the page, and not inline. True the normal \texttt{html} page is much
3141 % smaller than our typical PDF, but the point stands. We can have a hover
3142 % over call out for footnotes, but the same could be done for end notes,
3143 % regardless of the parent-child relation (as long as the required
3144 % cross-references are in place). On the other hand, for endnotes this is not
3145 % an issue: they have a natural place to be plugged into. Furthermore, making
3146 % an endnote a child of the text surrounding its mark leaves an empty
3147 % ``skeleton'' of the endnotes section: the heading, the list structure, etc.
3148 % Technically, we could clean that too, but clearly that's not the way to
3149 % go\dots{}.
3150 %
3151 % Finally, the parent-child relation is not required by \texttt{PDF} standards
3152 % for the relevant structure types. The \texttt{PDF} 2.0 standard
3153 % (ISO~32000-2:2020), says the following about \texttt{FENote}:
3154 %
3155 % \begin{quote}
3156 % Used to markup footnotes and endnotes. Footnotes and endnotes are content
3157 % that is not normally read as part of the enclosing content from which it
3158 % is referenced, but rather consulted at the reading person's discretion.
3159 % In order for text to be considered a footnote or endnote, there should be
3160 % a reference from the enclosing content to the footnote or endnote. Such
3161 % reference may be achieved by means of a Link structure element through a
3162 % structure destination in its link annotation (see ``Table 368 — General
3163 % inline level structure types''), or use of Ref in structure elements (see
3164 % ``Table 355 — Entries in a structure element dictionary'').
3165 % \end{quote}
3166 %
3167 % The \texttt{PDF} 1.7 standard (PDF~32000-1:2008), says the following about
3168 % \texttt{Note}:
3169 %
3170 % \begin{quote}
3171 % An item of explanatory text, such as a footnote or an endnote, that is
3172 % referred to from within the body of the document. It may have a label
3173 % (structure type Lbl; see ``List Elements'' in 14.8.4.3, ``Block-Level
3174 % Structure Elements'') as a child. The note may be included as a child of
3175 % the structure element in the body text that refers to it, or it may be
3176 % included elsewhere (such as in an endnotes section) and accessed by means
3177 % of a reference (structure type Reference).
3178 %
3179 % Tagged PDF does not prescribe the placement of footnotes in the page
3180 % content order. They may be either inline or at the end of the page, at
3181 % the discretion of the conforming writer.
3182 % \end{quote}
3183 %
3184 % So, the note \emph{may} be included as a child of the surrounding text, but
3185 % that's not required (PDF 2.0 does not even mention that). What is required
3186 % is the reference between the elements. All in all, let's not follow
3187 % footnotes in establishing the parent-child relation.
3188 %
3189 %
3190 % Another smaller but related issue is how to treat the list structure in
3191 % \cs{printpostnotes} when \opt{listenv} is used. The natural thing here
3192 % would be to use an \env{enumerate} type list (or, in PDF lingo, for the
3193 % \texttt{ListNumbering} attribute to be \texttt{Ordered}), where the mark is
3194 % used as the item's label (even if, technically, we use the list like a
3195 % \env{description} in that we feed the label of every \cs{item} and though
3196 % there is an implicit underlying counter, the list itself has no bearing upon
3197 % it). The problem here is that the PDF 2.0 standards determine that the
3198 % \texttt{FENote} structure element cannot be a child of a \texttt{LI} (list
3199 % item). However, at least in principle, we also would like to have the
3200 % \texttt{endnotelabel} element to be a child of the \texttt{endnote} element.
3201 % Thus, we have a conflict, the mc-chunk can only be used once, and can be
3202 % either the \texttt{Lbl} of the \texttt{LI}, or the \texttt{endnotelabel} for
3203 % the \texttt{endnote}. Currently, for the list case, I'm using an
3204 % \texttt{EndnotesList} class, which we define to have \texttt{ListNumbering}
3205 % as \texttt{Ordered}, with the mark as \texttt{Lbl} for \texttt{LI}, and
3206 % letting \texttt{endnote} be a child of \texttt{LBody}. In a way, the
3207 % possibility of exporting the tagged content to different formats makes me
3208 % think that this is the most appropriate for the this case. For the case of
3209 % \texttt{listenv=none}, the \texttt{endnote}s were made child of the
3210 % \texttt{Sect} in which they occur. The \texttt{endnotelabel} was then
3211 % included as part (child) of the \texttt{endnote}. In this, this treatment
3212 % emulates the one given for footnotes in the kernel. But, at the same time,
3213 % it is less than ideal for machine readability purposes, since whether the
3214 % \texttt{endnotelabel} is part of \texttt{endnote} or not depends on if there
3215 % is a list environment involved. Alas, I see no easy way around the PDF
3216 % standard restriction for the list case.
3217 %
3218 %
3219 % On the \LaTeX{} side of things, adding support for tagging entails two basic
3220 % tasks: i) applying the tagging markup at the appropriate places; ii)
3221 % generating references between the ``mark(s)'' and the ``text'' (plus
3222 % cross-reference commands to their respective targets).
3223 %
3224 % Regarding tagging references, we have three different cases: i) a regular
3225 % \cs{postnote}; ii) a \cs{postnoteref} to a note labeled from inside the
3226 % note; and iii) a \cs{postnoteref} to a note labeled with the \opt{label}
3227 % option.
3228 %
3229 % For regular \cs{postnote}s it is trivial to establish the reference using
3230 % the \texttt{label} / \texttt{ref} options of \pkg{tagpdf}.
3231 %
3232 % For \cs{postnoteref}s, however labeled, the connection \emph{must} be
3233 % established at \cs{postnoteref}, for the simple fact that any \cs{postnote}
3234 % can be referenced by arbitrarily many \cs{postnoteref}s. So we need to be
3235 % able to retrieve the note ID from the ``text'' to which the reference refers
3236 % to at \cs{postnoteref}. However, at \cs{postnoteref} the only information we
3237 % have is the \meta{label} but, since it is unique, we can establish a
3238 % connection through it.
3239 %
3240 % When the label is set from inside the note, it is actually set at
3241 % \cs{printpostnotes}, at which place we have access to
3242 % \cs{l_postnotes_print_note_id_tl} so we can use the \meta{label} to pass
3243 % that information around to \cs{postnoteref}. With a standard \cs{label} we
3244 % must set an additional \pkg{ltproperties} label, using the new
3245 % \texttt{label} hook, which \cs{postnoteref} can retrieve from its own
3246 % \meta{label} argument. For \cs{zlabel} this particular task is trivial,
3247 % since we can simply add a property to store the note ID with the label,
3248 % which \cs{postnotezref} can extract.
3249 %
3250 % When the label is set from the option, things are slightly more complicated,
3251 % because the label is set at \cs{postnote}, at which place we do not have
3252 % access to the note ID of the ``text''. What we do here is then store the
3253 % label with the note and restore it later at \cs{printpostnotes} as usual.
3254 % Then, at that point, we can set an auxiliary label which can be retrieved
3255 % from \cs{postnoteref} from its own \meta{label} argument, as we did for the
3256 % case of labels inside the note. Auxiliary labels are handled with
3257 % \pkg{ltproperties} labels.
3258 %
3259 %
3260 % Unconditionally define tagging support sockets.
3261 % \begin{macrocode}
3262 \socket_new:nn { tagsupport/postnotes/mark/begin }{ 0 }
3263 \socket_new:nn { tagsupport/postnotes/mark/end }{ 0 }
3264 \socket_new:nn { tagsupport/postnotes/nomark/begin }{ 0 }
3265 \socket_new:nn { tagsupport/postnotes/nomark/end }{ 0 }
3266 \socket_new:nn { tagsupport/postnotes/multisep/begin }{ 0 }
3267 \socket_new:nn { tagsupport/postnotes/multisep/end }{ 0 }
3268 \socket_new:nn { tagsupport/postnotes/printlist/begin }{ 0 }
3269 \socket_new:nn { tagsupport/postnotes/printlist/end }{ 0 }
3270 \socket_new:nn { tagsupport/postnotes/printnote/begin }{ 0 }
3271 \socket_new:nn { tagsupport/postnotes/printnote/end }{ 0 }
3272 \socket_new:nn { tagsupport/postnotes/printmark/begin }{ 0 }
3273 \socket_new:nn { tagsupport/postnotes/printmark/end }{ 0 }
3274 \socket_new:nn { tagsupport/postnotes/printtext/begin }{ 0 }
3275 \socket_new:nn { tagsupport/postnotes/printtext/end }{ 0 }
3276 \socket_new:nn { tagsupport/postnotes/postnoteref/begin }{ 0 }
3277 \socket_new:nn { tagsupport/postnotes/postnoteref/end }{ 0 }
3278 \socket_new:nn { tagsupport/postnotes/postnotezref/begin }{ 0 }
3279 \socket_new:nn { tagsupport/postnotes/postnotezref/end }{ 0 }
3280 % \end{macrocode}
3281 %
3282 % \begin{macrocode}
3283 \bool_lazy_and:nnT
3284 { \cs_if_exist_p:N \tag_if_active_p: }
3285 { \tag_if_active_p: }
3286 {
3287 % \end{macrocode}
3288 % FIXME Review or remove these settings if/when they are included upstream
3289 % (see \url{https://github.com/latex3/tagging-project/issues/728}).
3290 % \begin{macrocode}
3291 \tagpdfsetup
3292 {
3293 role/new-tag = { tag=endnote, role=FENote } ,
3294 role/new-tag = { tag=endnotemark, role=Lbl } ,
3295 role/new-tag = { tag=endnotelabel, role=Lbl } ,
3296 role/new-attribute =
3297 { EndnoteType } { /O /FENote /NoteType /Endnote } ,
3298 role/new-attribute =
3299 { EndnotesList } { /O /List /ListNumbering /Ordered } ,
3300 }
3301 % \end{macrocode}
3302 % \cs{postnote}
3303 % \begin{macrocode}
3304 \socket_new_plug:nnn { tagsupport/postnotes/mark/begin } { default }
3305 {
3306 \tag_mc_end_push:
3307 \tag_struct_begin:n
3308 {
3309 tag = endnotemark ,
3310 label = { postnotemark. \l_postnotes_note_id_tl } ,
3311 ref = { postnote. \l_postnotes_note_id_tl } ,
3312 }
3313 \@@_tagsup_store_sctructnum:nN
3314 { postnotemark } \l_postnotes_note_id_tl
3315 \tag_mc_begin:n { }
3316 }
3317 \socket_new_plug:nnn { tagsupport/postnotes/mark/end } { default }
3318 {
3319 \tag_mc_end:
3320 \tag_struct_end: % endnotemark
3321 \tag_mc_begin_pop:n { }
3322 }
3323 \socket_new_plug:nnn { tagsupport/postnotes/nomark/begin } { default }
3324 {
3325 \tag_struct_begin:n
3326 {
3327 tag = NonStruct ,
3328 label = { postnotemark. \l_postnotes_note_id_tl } ,
3329 ref = { postnote. \l_postnotes_note_id_tl } ,
3330 }
3331 \@@_tagsup_store_sctructnum:nN
3332 { postnotemark } \l_postnotes_note_id_tl
3333 }
3334 \socket_new_plug:nnn { tagsupport/postnotes/nomark/end } { default }
3335 { \tag_struct_end: } % NonStruct
3336 \socket_assign_plug:nn { tagsupport/postnotes/mark/begin } { default }
3337 \socket_assign_plug:nn { tagsupport/postnotes/mark/end } { default }
3338 \socket_assign_plug:nn { tagsupport/postnotes/nomark/begin } { default }
3339 \socket_assign_plug:nn { tagsupport/postnotes/nomark/end } { default }
3340 % \end{macrocode}
3341 % \opt{multiple}
3342 % \begin{macrocode}
3343 \socket_new_plug:nnn { tagsupport/postnotes/multisep/begin } { default }
3344 {
3345 \tag_mc_end_push:
3346 \tag_mc_begin:n { artifact }
3347 }
3348 \socket_new_plug:nnn { tagsupport/postnotes/multisep/end } { default }
3349 {
3350 \tag_mc_end:
3351 \tag_mc_begin_pop:n { }
3352 }
3353 \socket_assign_plug:nn { tagsupport/postnotes/multisep/begin } { default }
3354 \socket_assign_plug:nn { tagsupport/postnotes/multisep/end } { default }
3355 % \end{macrocode}
3356 % \cs{printpostnotes}
3357 % \begin{macrocode}
3358 \socket_new_plug:nnn { tagsupport/postnotes/printlist/begin } { default }
3359 { \tag_tool:n { para/tagging=false } }
3360 \socket_new_plug:nnn { tagsupport/postnotes/printlist/end } { default }
3361 { }
3362 \socket_assign_plug:nn { tagsupport/postnotes/printlist/begin } { default }
3363 \socket_assign_plug:nn { tagsupport/postnotes/printlist/end } { default }
3364 \socket_new_plug:nnn { tagsupport/postnotes/printnote/begin } { default }
3365 {
3366 \bool_if:NF \l_@@_print_as_list_bool
3367 {
3368 \tag_struct_begin:n
3369 {
3370 tag = endnote ,
3371 attribute-class = EndnoteType ,
3372 label = { postnote. \l_postnotes_print_note_id_tl } ,
3373 % \end{macrocode}
3374 % CHECK Should we really add a back reference here? I couldn't find any hint
3375 % about this in the standards, but \pkg{latex-lab-footnotes} does it. No
3376 % harm, I guess.
3377 % \begin{macrocode}
3378 ref = { postnotemark. \l_postnotes_print_note_id_tl } ,
3379 }
3380 \@@_tagsup_store_sctructnum:nN
3381 { postnote } \l_postnotes_print_note_id_tl
3382 }
3383 }
3384 \socket_new_plug:nnn { tagsupport/postnotes/printnote/end } { default }
3385 {
3386 \bool_if:NF \l_@@_print_as_list_bool
3387 { \tag_struct_end: } % endnote
3388 }
3389 \socket_assign_plug:nn { tagsupport/postnotes/printnote/begin } { default }
3390 \socket_assign_plug:nn { tagsupport/postnotes/printnote/end } { default }
3391 \socket_new_plug:nnn { tagsupport/postnotes/printmark/begin } { default }
3392 {
3393 \bool_if:NF \l_@@_print_as_list_bool
3394 {
3395 \tag_struct_begin:n { tag=endnotelabel }
3396 \tag_mc_begin:n { tag=Lbl }
3397 }
3398 }
3399 \socket_new_plug:nnn { tagsupport/postnotes/printmark/end } { default }
3400 {
3401 \bool_if:NF \l_@@_print_as_list_bool
3402 {
3403 \tag_mc_end:
3404 \tag_struct_end: % endnotelabel
3405 }
3406 }
3407 \socket_assign_plug:nn { tagsupport/postnotes/printmark/begin } { default }
3408 \socket_assign_plug:nn { tagsupport/postnotes/printmark/end } { default }
3409 \socket_new_plug:nnn { tagsupport/postnotes/printtext/begin } { default }
3410 {
3411 \bool_if:NTF \l_@@_print_as_list_bool
3412 {
3413 \tag_struct_begin:n
3414 {
3415 tag = endnote ,
3416 attribute-class = EndnoteType ,
3417 label = { postnote. \l_postnotes_print_note_id_tl } ,
3418 % \end{macrocode}
3419 % CHECK Ditto.
3420 % \begin{macrocode}
3421 ref = { postnotemark. \l_postnotes_print_note_id_tl } ,
3422 }
3423 \@@_tagsup_store_sctructnum:nN
3424 { postnote } \l_postnotes_print_note_id_tl
3425 \tag_struct_begin:n { tag=text-unit }
3426 \tag_struct_begin:n { tag=text }
3427 \tag_tool:n { para/tagging=true }
3428 \tag_mc_begin:n { }
3429 }
3430 {
3431 \tag_struct_begin:n { tag=text-unit }
3432 \tag_struct_begin:n { tag=text }
3433 \tag_tool:n { para/tagging=true }
3434 \tag_mc_begin:n { }
3435 }
3436 }
3437 \socket_new_plug:nnn { tagsupport/postnotes/printtext/end } { default }
3438 {
3439 \bool_if:NTF \l_@@_print_as_list_bool
3440 {
3441 \tag_mc_end:
3442 \tag_tool:n { para/tagging=false }
3443 \tag_struct_end: % text
3444 \tag_struct_end: % text-unit
3445 \tag_struct_end: % endnote
3446 }
3447 {
3448 \tag_mc_end:
3449 \tag_tool:n { para/tagging=false }
3450 \tag_struct_end: % text
3451 \tag_struct_end: % text-unit
3452 }
3453 }
3454 \socket_assign_plug:nn { tagsupport/postnotes/printtext/begin } { default }
3455 \socket_assign_plug:nn { tagsupport/postnotes/printtext/end } { default }
3456 % \end{macrocode}
3457 % Provide \pkg{xtemplate} based redefinitions of \env{postnoteslist} and
3458 % \pkg{postnoteslisthang}. This is needed because, as far as I can tell, it
3459 % is the only way to set \opt{tag} and \opt{attribute-class} for the list
3460 % struct without tampering with \pkg{latex-lab-testphase-block}'s internals.
3461 % \begin{macrocode}
3462 \IfInstanceExistsT { blockenv } { list }
3463 {
3464 \DeclareInstance { blockenv } { postnoteslist } { display }
3465 {
3466 env-name = postnoteslist ,
3467 tag-name = L ,
3468 tag-class = EndnotesList ,
3469 tagging-recipe = list ,
3470 inner-level-counter = ,
3471 level-increase = true ,
3472 setup-code = ,
3473 block-instance = list ,
3474 inner-instance = postnoteslist ,
3475 }
3476 \DeclareInstanceCopy { blockenv }
3477 { postnoteslisthang } { postnoteslist }
3478 \EditInstance { blockenv } { postnoteslisthang }
3479 { env-name = postnoteslisthang }
3480 \DeclareInstance { list } { postnoteslist } { std }
3481 { item-instance = postnoteslist }
3482 \DeclareInstance { item } { postnoteslist } { std }
3483 {
3484 label-format = { \hspace { \labelsep } \normalfont ~ #1 } ,
3485 label-align = left ,
3486 }
3487 \RenewDocumentEnvironment { postnoteslist } { }
3488 {
3489 \UseInstance { blockenv } { postnoteslist }
3490 {
3491 leftmargin = 0pt ,
3492 label-width = 0pt ,
3493 item-indent = .5\parindent ,
3494 rightmargin = 0pt ,
3495 parindent = \parindent ,
3496 par-skip = \parskip ,
3497 item-skip = 0pt ,
3498 beginsep = .5\topsep ,
3499 begin-par-skip = .5\partopsep ,
3500 }
3501 }
3502 { \endblockenv }
3503 \RenewDocumentEnvironment { postnoteslisthang } { }
3504 {
3505 \UseInstance { blockenv } { postnoteslisthang }
3506 {
3507 leftmargin = 1em ,
3508 label-width = -\leftmargin ,
3509 item-indent = -2\leftmargin ,
3510 rightmargin = 0pt ,
3511 parindent = \parindent ,
3512 par-skip = \parskip ,
3513 item-skip = 0pt ,
3514 beginsep = .5\topsep ,
3515 begin-par-skip = .5\partopsep ,
3516 }
3517 }
3518 { \endblockenv }
3519 }
3520 % \end{macrocode}
3521 % Setup for \cs{label} and \cs{zlabel} inside the note.
3522 % \begin{macrocode}
3523 \bool_new:N \l_@@_inside_note_bool
3524 \AddToHookWithArguments { label } [ postnotes/tagsup ]
3525 {
3526 \bool_if:NT \l_@@_inside_note_bool
3527 {
3528 \property_record:nn { postnote@label@innote. #1 }
3529 { postnotes/tagsup@noteid }
3530 }
3531 }
3532 \AddToHook { postnotes/print/note/begin } [ postnotes/tagsup ]
3533 { \bool_set_true:N \l_@@_inside_note_bool }
3534 \property_new:nnnn { postnotes/tagsup@noteid } { now } { 0 }
3535 { \l_postnotes_print_note_id_tl }
3536 \AddToHook { package/zref-user/after } [ postnotes/tagsup ]
3537 {
3538 \zref@newprop { postnotes@tagsup@noteid } [ 0 ]
3539 { \l_postnotes_print_note_id_tl }
3540 \AddToHook { postnotes/print/note/begin } [ postnotes/tagsup ]
3541 { \zref@localaddprop { main } { postnotes@tagsup@noteid } }
3542 }
3543 % \end{macrocode}
3544 % Setup for \opt{label} and \opt{zlabel} options.
3545 % \begin{macrocode}
3546 \AddToHook { postnotes/note/store } [ postnotes/tagsup ]
3547 {
3548 \str_if_empty:NF \l_@@_note_label_str
3549 {
3550 \prop_gput:cnV
3551 { \@@_data_name:e { \l_postnotes_note_id_tl } }
3552 { label } \l_@@_note_label_str
3553 }
3554 }
3555 \AddToHook { package/zref-user/after } [ postnotes/tagsup ]
3556 {
3557 \AddToHook { postnotes/note/store } [ postnotes/tagsup ]
3558 {
3559 \str_if_empty:NF \l_@@_note_zlabel_str
3560 {
3561 \prop_gput:cnV
3562 { \@@_data_name:e { \l_postnotes_note_id_tl } }
3563 { zlabel } \l_@@_note_zlabel_str
3564 }
3565 }
3566 }
3567 \AddToHook { postnotes/print/note/begin } [ postnotes/tagsup ]
3568 {
3569 \@@_prop_get:nnN { \l_postnotes_print_note_id_tl }
3570 { label } \l_@@_restore_tmp_tl
3571 \tl_if_empty:NF \l_@@_restore_tmp_tl
3572 {
3573 \exp_args:Ne \property_record:nn
3574 { postnote@label@option. \l_@@_restore_tmp_tl }
3575 { postnotes/tagsup@noteid }
3576 }
3577 \@@_prop_get:nnN { \l_postnotes_print_note_id_tl }
3578 { zlabel } \l_@@_restore_tmp_tl
3579 \tl_if_empty:NF \l_@@_restore_tmp_tl
3580 {
3581 \exp_args:Ne \property_record:nn
3582 { postnote@zlabel@option. \l_@@_restore_tmp_tl }
3583 { postnotes/tagsup@noteid }
3584 }
3585 }
3586 % \end{macrocode}
3587 % CHECK \pkg{latex-lab-footnotes} creates the footnote structure element
3588 % (\texttt{FENote} tag) and adds to it a \texttt{/Ref} entry pointing to the
3589 % structures of \emph{all} marks related to the note, and that includes
3590 % \cs{footref}s. I don't see anything stating something of the sort in the
3591 % standards, the backref of the original mark is already a stretch. I also
3592 % fail to see why this is needed, and how it could be used. But\dots{} I
3593 % trust Ulrike knows better than me.
3594 % \begin{macro}
3595 % {
3596 % \@@_tagsup_store_sctructnum:nN ,
3597 % \@@_tagsup_store_crossref:nN ,
3598 % }
3599 % \begin{syntax}
3600 % \cs{@@_tagsup_store_sctructnum:nN} \Arg{ref type} \Arg{ID number of note}
3601 % \cs{@@_tagsup_store_crossref:nN} \Arg{ref type} \Arg{ID number of note}
3602 % \end{syntax}
3603 % \meta{ref type} is either ``\texttt{postnote}'' or
3604 % ``\texttt{postnotemark}''.
3605 % \begin{macrocode}
3606 \prop_new:N \g_@@_tagsup_structnums_prop
3607 \cs_new_protected:Npn \@@_tagsup_store_sctructnum:nN #1#2
3608 {
3609 \prop_gput:Nee \g_@@_tagsup_structnums_prop
3610 { #1 . #2 } { \tag_get:n { struct_num } }
3611 }
3612 \prop_new:N \g_@@_tagsup_crossrefs_prop
3613 \cs_new_protected:Npn \@@_tagsup_store_crossref:nN #1#2
3614 {
3615 \prop_gput:Nee \g_@@_tagsup_crossrefs_prop
3616 { \tag_get:n { struct_num } } { #1 . #2 }
3617 }
3618 % \end{macrocode}
3619 % \end{macro}
3620 % \begin{macro}{\@@_tagsup_gput_ref:nn}
3621 % \begin{syntax}
3622 % \cs{@@_tagsup_gput_ref:nn} \Arg{structnum refering from}
3623 % ~~~~\Arg{structnum being referenced to}
3624 % \end{syntax}
3625 % See \cs{__fnote_gput_ref:nn}.
3626 % \begin{macrocode}
3627 \cs_new_protected:Npn \@@_tagsup_gput_ref:nn #1#2
3628 {
3629 \tag_if_active:T
3630 { \tag_struct_gput:ene {#1} {ref} { \tag_struct_object_ref:e {#2} } }
3631 }
3632 % \end{macrocode}
3633 % \end{macro}
3634 % The actual inclusion of the reference has to be done at the end, since the
3635 % \opt{ref} option called by \cs{tag_struct_begin:n} does not check if the
3636 % variable to store the refs already exists, resulting in a clash if we add it
3637 % immediately and a \cs{posnoteref} is made before \cs{printpostnotes}, and
3638 % also so that the ``main'' reference always comes first at the list.
3639 % \begin{macrocode}
3640 \AddToHook { tagpdf/finish/before } [ postnotes/tagsup ]
3641 {
3642 \prop_map_inline:Nn \g_@@_tagsup_crossrefs_prop
3643 {
3644 \@@_tagsup_gput_ref:nn
3645 { \prop_item:Nn \g_@@_tagsup_structnums_prop {#2} }
3646 {#1}
3647 }
3648 }
3649 % \end{macrocode}
3650 % \cs{postnoteref}
3651 % \begin{macrocode}
3652 \socket_new_plug:nnn { tagsupport/postnotes/postnoteref/begin } { default }
3653 {
3654 \tag_mc_end_push:
3655 \property_if_recorded:eeTF
3656 { postnote@label@innote. \l_@@_note_ref_label_str }
3657 { postnotes/tagsup@noteid }
3658 {
3659 % \end{macrocode}
3660 % Label coming from a \cs{label} inside the note.
3661 % \begin{macrocode}
3662 \tl_set:Ne \l_@@_tmpa_tl
3663 {
3664 \property_ref:ee
3665 { postnote@label@innote. \l_@@_note_ref_label_str }
3666 { postnotes/tagsup@noteid }
3667 }
3668 \tag_struct_begin:n
3669 {
3670 tag = endnotemark ,
3671 ref = { postnote. \l_@@_tmpa_tl } ,
3672 }
3673 \@@_tagsup_store_crossref:nN
3674 { postnote } \l_@@_tmpa_tl
3675 }
3676 {
3677 \property_if_recorded:eeTF
3678 { postnote@label@option. \l_@@_note_ref_label_str }
3679 { postnotes/tagsup@noteid }
3680 {
3681 % \end{macrocode}
3682 % Label coming from a \opt{label} option.
3683 % \begin{macrocode}
3684 \tl_set:Ne \l_@@_tmpa_tl
3685 {
3686 \property_ref:ee
3687 { postnote@label@option. \l_@@_note_ref_label_str }
3688 { postnotes/tagsup@noteid }
3689 }
3690 \tag_struct_begin:n
3691 {
3692 tag = endnotemark ,
3693 ref = { postnotemark. \l_@@_tmpa_tl } ,
3694 }
3695 \@@_tagsup_store_crossref:nN
3696 { postnotemark } \l_@@_tmpa_tl
3697 }
3698 { \tag_struct_begin:n { tag = endnotemark } }
3699 }
3700 \tag_mc_begin:n { }
3701 }
3702 \socket_new_plug:nnn { tagsupport/postnotes/postnoteref/end } { default }
3703 {
3704 \tag_mc_end:
3705 \tag_struct_end: % endnotemark
3706 \tag_mc_begin_pop:n { }
3707 }
3708 \socket_assign_plug:nn { tagsupport/postnotes/postnoteref/begin } { default }
3709 \socket_assign_plug:nn { tagsupport/postnotes/postnoteref/end } { default }
3710 % \end{macrocode}
3711 % \cs{postnotezref}
3712 % \begin{macrocode}
3713 \AddToHook { package/zref-user/after } [ postnotes/tagsup ]
3714 {
3715 \socket_new_plug:nnn { tagsupport/postnotes/postnotezref/begin } { default }
3716 {
3717 \tag_mc_end_push:
3718 \zref@ifrefcontainsprop { \l_@@_note_zref_zlabel_str }
3719 { postnotes@tagsup@noteid }
3720 {
3721 % \end{macrocode}
3722 % Label coming from a \cs{zlabel} inside the note.
3723 % \begin{macrocode}
3724 \tl_set:Ne \l_@@_tmpa_tl
3725 {
3726 \zref@extract { \l_@@_note_zref_zlabel_str }
3727 { postnotes@tagsup@noteid }
3728 }
3729 \tag_struct_begin:n
3730 {
3731 tag = endnotemark ,
3732 ref = { postnote. \l_@@_tmpa_tl } ,
3733 }
3734 \@@_tagsup_store_crossref:nN
3735 { postnote } \l_@@_tmpa_tl
3736 }
3737 {
3738 \property_if_recorded:eeTF
3739 { postnote@zlabel@option. \l_@@_note_zref_zlabel_str }
3740 { postnotes/tagsup@noteid }
3741 {
3742 % \end{macrocode}
3743 % Label coming from a \opt{zlabel} option.
3744 % \begin{macrocode}
3745 \tl_set:Ne \l_@@_tmpa_tl
3746 {
3747 \property_ref:ee
3748 {
3749 postnote@zlabel@option.
3750 \l_@@_note_zref_zlabel_str
3751 }
3752 { postnotes/tagsup@noteid }
3753 }
3754 \tag_struct_begin:n
3755 {
3756 tag = endnotemark ,
3757 ref = { postnotemark. \l_@@_tmpa_tl } ,
3758 }
3759 \@@_tagsup_store_crossref:nN
3760 { postnotemark } \l_@@_tmpa_tl
3761 }
3762 { \tag_struct_begin:n { tag = endnotemark } }
3763 }
3764 \tag_mc_begin:n { }
3765 }
3766 \socket_new_plug:nnn { tagsupport/postnotes/postnotezref/end } { default }
3767 {
3768 \tag_mc_end:
3769 \tag_struct_end: % endnotemark
3770 \tag_mc_begin_pop:n { }
3771 }
3772 \socket_assign_plug:nn { tagsupport/postnotes/postnotezref/begin } { default }
3773 \socket_assign_plug:nn { tagsupport/postnotes/postnotezref/end } { default }
3774 }
3775 }
3776 % \end{macrocode}
3777 %
3778 %
3779 % \section{Languages}
3780 % \label{sec:languages}
3781 %
3782 % \begin{macro}[int]
3783 % {
3784 % \pntitle ,
3785 % \pnhdnotes ,
3786 % \pnhdtopage ,
3787 % \pnhdtopages ,
3788 % }
3789 % Set of language specific user variables. They are used in the default
3790 % value of the \opt{heading} option and in \cs{pnheaderdefault} which,
3791 % ultimately, is also used in the same place.
3792 % \begin{macrocode}
3793 \tl_new:N \pntitle
3794 \tl_new:N \pnhdnotes
3795 \tl_new:N \pnhdtopage
3796 \tl_new:N \pnhdtopages
3797 \tl_set:Nn \pntitle { Notes }
3798 \tl_set:Nn \pnhdnotes { Notes }
3799 \tl_set:Nn \pnhdtopage { to~page }
3800 \tl_set:Nn \pnhdtopages { to~pages }
3801 % \end{macrocode}
3802 % \end{macro}
3803 %
3804 %
3805 % \begin{macro}{\@@_define_language:nn}
3806 % Defines language specific values for \meta{postnote language} by storing a
3807 % set of assignments for the language specific variables in \meta{setup}.
3808 % \meta{postnote language} is an internal name, typically the ``main'' name
3809 % of the language, based on which we can set specific \pkg{babel} or
3810 % \pkg{polyglossia} languages or variants.
3811 % \begin{syntax}
3812 % \cs{@@_define_language:nn} \Arg{postnote language} \Arg{setup}
3813 % \end{syntax}
3814 % \begin{macrocode}
3815 \cs_new_protected:Npn \@@_define_language:nn #1#2
3816 {
3817 \tl_new:c { g_@@_language_ #1 _tl }
3818 \tl_gset:cn { g_@@_language_ #1 _tl } {#2}
3819 }
3820 % \end{macrocode}
3821 % \end{macro}
3822 %
3823 %
3824 % For \pkg{babel} we use the new hook system, it's clean, and avoids the
3825 % \cs{addto} pitfalls. The appropriate hook to use is
3826 % \texttt{babel/\meta{language}/beforeextras} so that users can override it
3827 % with a traditional
3828 % \texttt{\textbackslash{}addto\textbackslash{}extras\meta{language}}.
3829 %
3830 % Note that, for \pkg{babel}, the captions are currently handled in two
3831 % different ways -- the ``old way'' and the ``new way'' -- and which of them
3832 % is used depends on the language. Most still use the ``old way'', but the
3833 % problem is that it is not universal. And the ``new way'' uses a different
3834 % naming scheme -- \texttt{\textbackslash{}\meta{language}\meta{caption}},
3835 % which is meant to be set with \cs{setlocalecaption}, and not suitable for
3836 % our needs. The \texttt{\textbackslash{}extras\meta{language}} macros are
3837 % meant for ``arbitrary'' code to be run when the language is selected, which
3838 % is what we want. The captions used to work in the same way, but no longer
3839 % for languages which use the ``new way''.
3840 %
3841 % Note also that there seems to exist some qualms about \pkg{babel}'s
3842 % \cs{addto}. A number of packages define their own versions of it. Do so at
3843 % least \pkg{varioref} (probably the original), \pkg{backref}, and
3844 % \pkg{cleveref}. The latter comments that \cs{addto} is ``flawed''.
3845 % \pkg{babel} itself comments the definition recognizing that there is an
3846 % ``inconsistency'': depending on the case, the operation will be either local
3847 % or global. This is documented in the manual, which explains this
3848 % inconsistent behavior is preserved for backward compatibility, and
3849 % recommends \pkg{etoolbox}'s facilities if available. \pkg{polyglossia} also
3850 % recommends \pkg{etoolbox}'s \cs{gappto}. All in all, if there's need to use
3851 % the traditional way instead of the new hooks, just rely on \texttt{expl3}
3852 % and use \cs{tl_gput_right:Nn}.
3853 %
3854 % \begin{macro}{\@@_set_babel_language:nn}
3855 % Sets \meta{babel language} to execute the setup defined by
3856 % \cs{@@_define_language:nn} for \meta{postnote language} at the
3857 % \texttt{babel/\meta{language}/beforeextras} hook.
3858 % \begin{syntax}
3859 % \cs{@@_set_babel_language:nn} \Arg{babel language} \Arg{postnote language}
3860 % \end{syntax}
3861 % \begin{macrocode}
3862 \cs_new_protected:Npn \@@_set_babel_language:nn #1#2
3863 {
3864 \ActivateGenericHook { babel/#1/beforeextras }
3865 \exp_args:Nnv \AddToHook { babel/#1/beforeextras }
3866 { g_@@_language_ #2 _tl }
3867 }
3868 % \end{macrocode}
3869 % \end{macro}
3870 %
3871 %
3872 % \pkg{polyglossia} uses a similar set of macros for setting up languages as
3873 % \pkg{babel} does. However, the
3874 % \texttt{\textbackslash{}blockextras@\meta{language}} macros are
3875 % unfortunately internal (despite what the manual says, that's what the code
3876 % does), thus requiring \cs{makeatletter}/\cs{makeatother} for user
3877 % configuration, which would be an inconvenience. On the other hand,
3878 % \pkg{polyglossia}'s \texttt{\textbackslash{}captions\meta{language}} works
3879 % as in \pkg{babel}'s ``old way'', meaning it is just a ``hook'' to which we
3880 % can append some code. So we use
3881 % \texttt{\textbackslash{}captions\meta{language}} for \pkg{polyglossia}.
3882 % Things may complicate here if there's need to set up different values for
3883 % different language variants, since the hooks available are all necessarily
3884 % internal, but I doubt we'll ever need variants for these simple strings.
3885 %
3886 % \begin{macro}{\@@_set_polyglossia_language:nn}
3887 % Sets \meta{polyglossia language} to execute the setup defined by
3888 % \cs{@@_define_language:nn} for \meta{postnote language} at the
3889 % \pkg{polyglossia} \texttt{\textbackslash{}captions\meta{language}} hook.
3890 % \begin{syntax}
3891 % \cs{@@_set_polyglossia_language:nn} \Arg{polyglossia language}
3892 % ~~\Arg{postnote language}
3893 % \end{syntax}
3894 % \begin{macrocode}
3895 \cs_new_protected:Npn \@@_set_polyglossia_language:nn #1#2
3896 {
3897 \AddToHook { package/polyglossia/after }
3898 {
3899 \exp_args:Nnv \csgappto { captions #1 }
3900 { g_@@_language_ #2 _tl }
3901 }
3902 }
3903 % \end{macrocode}
3904 % \end{macro}
3905 %
3906 %
3907 % \subsection*{English}
3908 %
3909 % \begin{macrocode}
3910 \@@_define_language:nn { english }
3911 {
3912 \tl_set:Nn \pntitle { Notes }
3913 \tl_set:Nn \pnhdnotes { Notes }
3914 \tl_set:Nn \pnhdtopage { to~page }
3915 \tl_set:Nn \pnhdtopages { to~pages }
3916 }
3917 \@@_set_babel_language:nn { english } { english }
3918 \@@_set_babel_language:nn { british } { english }
3919 \@@_set_babel_language:nn { american } { english }
3920 \@@_set_babel_language:nn { canadian } { english }
3921 \@@_set_babel_language:nn { australian } { english }
3922 \@@_set_babel_language:nn { newzealand } { english }
3923 \@@_set_babel_language:nn { UKenglish } { english }
3924 \@@_set_babel_language:nn { USenglish } { english }
3925 \@@_set_polyglossia_language:nn { english } { english }
3926 % \end{macrocode}
3927 %
3928 %
3929 % \subsection*{Portuguese}
3930 %
3931 % \begin{macrocode}
3932 \@@_define_language:nn { portuguese }
3933 {
3934 \tl_set:Nn \pntitle { Notas }
3935 \tl_set:Nn \pnhdnotes { Notas }
3936 \tl_set:Nn \pnhdtopage { da~página }
3937 \tl_set:Nn \pnhdtopages { das~páginas }
3938 }
3939 \@@_set_babel_language:nn { portuguese } { portuguese }
3940 \@@_set_babel_language:nn { brazilian } { portuguese }
3941 \@@_set_babel_language:nn { portuges } { portuguese }
3942 \@@_set_babel_language:nn { brazil } { portuguese }
3943 \@@_set_polyglossia_language:nn { portuguese } { portuguese }
3944 % \end{macrocode}
3945 %
3946 %
3947 % \subsection*{French}
3948 %
3949 % French localization validated by \contributor{\username{Pika78}} at
3950 % \githubissue{1}.
3951 %
3952 % \pkg{babel-french} also has \file{.ldf}s for \texttt{francais},
3953 % \texttt{frenchb}, and \texttt{canadien}, but they are deprecated as options
3954 % and, if used, they fall back to either \texttt{french} or \texttt{acadian}.
3955 %
3956 % \begin{macrocode}
3957 \@@_define_language:nn { french }
3958 {
3959 \tl_set:Nn \pntitle { Notes }
3960 \tl_set:Nn \pnhdnotes { Notes }
3961 \tl_set:Nn \pnhdtopage { de~la~page }
3962 \tl_set:Nn \pnhdtopages { des~pages }
3963 }
3964 \@@_set_babel_language:nn { french } { french }
3965 \@@_set_babel_language:nn { acadian } { french }
3966 \@@_set_polyglossia_language:nn { french } { french }
3967 % \end{macrocode}
3968 %
3969 %
3970 % \subsection*{German}
3971 %
3972 % German localization provided by \contributor{Herbert Voß} at
3973 % \githubissue{2}.
3974 %
3975 % \pkg{babel-german} also has \file{.ldf}s for \texttt{germanb} and
3976 % \texttt{ngermanb}, but they are deprecated as options and, if used, they
3977 % fall back respectively to \texttt{german} and \texttt{ngerman}.
3978 %
3979 % \begin{macrocode}
3980 \@@_define_language:nn { german }
3981 {
3982 \tl_set:Nn \pntitle { Endnoten }
3983 \tl_set:Nn \pnhdnotes { Endnoten }
3984 \tl_set:Nn \pnhdtopage { zu~Seite }
3985 \tl_set:Nn \pnhdtopages { zu~Seiten }
3986 }
3987 \@@_set_babel_language:nn { german } { german }
3988 \@@_set_babel_language:nn { ngerman } { german }
3989 \@@_set_babel_language:nn { austrian } { german }
3990 \@@_set_babel_language:nn { naustrian } { german }
3991 \@@_set_babel_language:nn { swissgerman } { german }
3992 \@@_set_babel_language:nn { nswissgerman } { german }
3993 \@@_set_polyglossia_language:nn { german } { german }
3994 % \end{macrocode}
3995 %
3996 %
3997 % \begin{macrocode}
3998 %</package>
3999 % \end{macrocode}
4000 %
4001 %
4002 % \PrintIndex
4003 %
4004 % \endinput
4005 %
4006 % Local Variables:
4007 % jinx-local-words: "endnote endnotes"
4008 % End: