-
-
Notifications
You must be signed in to change notification settings - Fork 305
Expand file tree
/
Copy pathlthooks.dtx
More file actions
8137 lines (8133 loc) · 305 KB
/
lthooks.dtx
File metadata and controls
8137 lines (8133 loc) · 305 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% \iffalse meta-comment
%
% Copyright (C) 2020-2025
% Frank Mittelbach, Phelype Oleinik, The LaTeX Project
%
% This file is part of the LaTeX base system.
% -------------------------------------------
%
% It may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
% https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008 or later.
%
% This file has the LPPL maintenance status "maintained".
%
% The list of all files belonging to the LaTeX base distribution is
% given in the file `manifest.txt'. See also `legal.txt' for additional
% information.
%
% The list of derived (unpacked) files belonging to the distribution
% and covered by LPPL is defined by the unpacking scripts (with
% extension .ins) which are part of the distribution.
%
% \fi
%
% \iffalse
%%% From File: lthooks.dtx
%
%<*driver>
% \fi
\ProvidesFile{lthooks.dtx}
[2026-01-16 v1.1n LaTeX Kernel (hooks)]
% \iffalse
%
\documentclass{l3in2edoc}
\GetFileInfo{lthooks.dtx}
\providecommand\InternalDetectionOff{}
\providecommand\InternalDetectionOn{}
\EnableCrossrefs
\CodelineIndex
\begin{document}
\DocInput{lthooks.dtx}
\end{document}
%</driver>
%
% \fi
%
% \renewcommand\hook[1]{\texttt{#1}\SpecialAuxHookIndex{#1}}
% \newcommand\describehook[1]{\texttt{#1}\SpecialHookIndex{#1}}
%
%
% \providecommand\fmi[1]{\marginpar{\footnotesize FMi: #1}}
% \providecommand\fmiinline[1]{\begin{quote}\itshape\footnotesize FMi: #1\end{quote}}
% \providecommand\pho[1]{\marginpar{\footnotesize PhO: #1}}
% \providecommand\phoinline[1]{\begin{quote}\itshape\footnotesize PhO: #1\end{quote}}
%
%
%
% \title{\LaTeX{}'s hook management\thanks{This module has version
% \fileversion\ dated \filedate, \copyright\ \LaTeX\
% Project.}}
%
% \author{Frank Mittelbach\thanks{Code improvements for speed and other goodies by Phelype Oleinik}}
%
% \maketitle
%
%
% \tableofcontents
%
% \section{Introduction}
%
% Hooks are points in the code of commands or environments where it
% is possible to add processing code into existing commands. This
% can be done by different packages that do not know about each
% other, and to allow for hopefully safe processing it is necessary
% to sort different chunks of code added by different packages into
% a suitable processing order.
%
% This is done by the packages adding chunks of code (via
% \cs{AddToHook}) and labeling their code with some label by
% default using the package name as a label.
%
% At \verb=\begin{document}= all code for a hook is then sorted
% according to some rules (given by \cs{DeclareHookRule}) for fast
% execution without processing overhead. If the hook code is
% modified afterwards (or the rules are changed),
% a new version for fast processing is generated.
%
% Some hooks are used already in the preamble of the document. If
% that happens then the hook is prepared for execution (and sorted)
% already at that point.
%
%
% \section{Package writer interface}
%
% The hook management system is offered as a set of CamelCase
% commands for traditional \LaTeXe{} packages (and for use in the
% document preamble if needed) as well as \texttt{expl3} commands
% for modern packages, that use the L3 programming layer of
% \LaTeX{}. Behind the scenes, a single set of data structures is
% accessed so that packages from both worlds can coexist and access
% hooks in other packages.
%
%
%
% \subsection{\LaTeXe\ interfaces}
%
% \subsubsection{Declaring hooks}
%
% With a few exceptions, hooks have to be declared before they can
% be used. The exceptions are the generic hooks for commands and
% environments (executed at \cs{begin} and \cs{end}), and the generic
% hooks run when loading files (see section~\ref{sec:generic}).
%
% \begin{function}{\NewHook}
% \begin{syntax}
% \cs{NewHook} \Arg{hook}
% \end{syntax}
% Creates a new \meta{hook}.
% If this hook is declared within a package it is suggested
% that its name is always structured as follows:
% \meta{package-name}\texttt{/}\meta{hook-name}. If necessary you
% can further subdivide the name by adding more \texttt{/} parts.
% If a hook name is already taken, an error is raised and the hook
% is not created.
%
% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
% The string \texttt{??} can't be used as a hook name because it
% has a special significance as a placeholder in hook rules.
%
% \end{function}
%
% \begin{function}{\NewReversedHook}
% \begin{syntax}
% \cs{NewReversedHook} \Arg{hook}
% \end{syntax}
% Like \cs{NewHook} declares a new \meta{hook}.
% the difference is that the code chunks for this hook are in
% reverse order by default (those added last are executed first).
% Any rules for the hook are applied after the default ordering.
% See sections~\ref{sec:order} and \ref{sec:reversed-order}
% for further details.
%
% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
% \begin{function}{\NewMirroredHookPair}
% \begin{syntax}
% \cs{NewMirroredHookPair} \Arg{hook-1} \Arg{hook-2}
% \end{syntax}
% A shorthand for
% \cs{NewHook}\Arg{hook-1}\cs{NewReversedHook}\Arg{hook-2}.
%
% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
%
% \begin{function}{\NewHookWithArguments}
% \begin{syntax}
% \cs{NewHookWithArguments} \Arg{hook} \Arg{number}
% \end{syntax}
% Creates a new \meta{hook} whose code takes \meta{number} arguments,
% and otherwise works exactly like \cs{NewHook}.
% Section~\ref{sec:hook-args} explains hooks with arguments.
%
% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
% \begin{function}{\NewReversedHookWithArguments}
% \begin{syntax}
% \cs{NewReversedHookWithArguments} \Arg{hook} \Arg{number}
% \end{syntax}
% Like \cs{NewReversedHook}, but creates a hook whose code takes
% \meta{number} arguments.
% Section~\ref{sec:hook-args} explains hooks with arguments.
%
% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
% \begin{function}{\NewMirroredHookPairWithArguments}
% \begin{syntax}
% \cs{NewMirroredHookPairWithArguments} \Arg{hook-1} \Arg{hook-2} \Arg{number}
% \end{syntax}
% A shorthand for
% \cs{NewHookWithArguments}\Arg{hook-1}\Arg{number}\\
% \cs{NewReversedHookWithArguments}\Arg{hook-2}\Arg{number}.
% Section~\ref{sec:hook-args} explains hooks with arguments.
%
% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
%
% \subsubsection{Special declarations for generic hooks}
%
% The declarations here should normally not be used. They are available
% to provide support for special use cases mainly involving
% generic command hooks.
%
% \changes{v1.0p}{2021/08/20}{Documentation updates for generic hook commands (gh/638)}
%
% \begin{function}{\DisableGenericHook}
% \begin{syntax}
% \cs{DisableGenericHook} \Arg{hook}
% \end{syntax}
% After this declaration\footnotemark{} the \meta{hook} is no longer
% usable: Any further attempt to add code to it will result in an
% error and any use, e.g., via \cs{UseHook}, will simply do nothing.
%
% This is intended to be used with generic command hooks (see
% \texttt{ltcmdhooks-doc}) as depending on the definition of the
% command such generic hooks may be unusable. If that is known, a
% package developer can disable such hooks up front.
%
% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
% \end{function}\footnotetext{In the 2020/06 release this command was
% called \cs{DisableHook}, but that name was misleading as it
% shouldn't be used to disable non-generic hooks.}
%
%
% \begin{function}{\ActivateGenericHook}
% \begin{syntax}
% \cs{ActivateGenericHook} \Arg{hook}
% \end{syntax}
% This declaration activates a generic hook provided by a package/class
% (e.g., one used in code with \cs{UseHook} or
% \cs{UseOneTimeHook}) without it being explicitly declared with
% \cs{NewHook}).
% If the hook is already activated, this command does nothing.
%
% Note that this command does not undo the effect of \cs{DisableGenericHook}.
% See section~\ref{sec:generic-hooks} for a discussion of when this
% declaration is appropriate.
% \end{function}
%
%
%
%
%
% \subsubsection{Using hooks in code}
%
% Using a hook that is executing the code that has been associated
% with it is only allowed if the hook has been previously declared
% with \cs{NewHook}. For performance reason there are no runtime
% checks for this and it is the responsibility of the programmer of a
% package to ensure that all hooks that are used in a package (with
% one of the commands in this section) are declared first.
%
% \begin{function}{\UseHook}
% \begin{syntax}
% \cs{UseHook} \Arg{hook}
% \end{syntax}
% Execute the code stored in the \meta{hook}.
%
% Before \verb=\begin{document}= the fast execution code for a hook
% is not set up, so in order to use a hook there it is explicitly
% initialized first. As that involves assignments using a hook at
% those times is not 100\% the same as using it after
% \verb=\begin{document}=.
%
% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
% A leading |.| is treated literally.
% \end{function}
%
% \begin{function}{\UseHookWithArguments}
% \begin{syntax}
% \cs{UseHookWithArguments} \Arg{hook} \Arg{number} \Arg{arg_1} \ldots \Arg{arg_n}
% \end{syntax}
% Execute the code stored in the \meta{hook} and pass the arguments
% \Arg{arg_1} through \Arg{arg_n} to the \meta{hook}. Otherwise, it
% works exactly like \cs{UseHook}.
% The \meta{number} should be the number of arguments declared for
% the hook. If the hook is not declared, this command does nothing
% and it will remove \meta{number} items from the input.
% Section~\ref{sec:hook-args} explains hooks with arguments.
%
% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
% A leading |.| is treated literally.
% \end{function}
%
% \begin{function}{\UseOneTimeHook}
% \begin{syntax}
% \cs{UseOneTimeHook} \Arg{hook}
% \end{syntax}
% Some hooks are only used (and can be only used) in one place, for
% example, those in \verb=\begin{document}= or
% \verb=\end{document}=. From that point onwards, adding to the hook
% through a defined \cs[no-index]{\meta{addto-cmd}} command (e.g.,
% \cs{AddToHook} or \cs{AtBeginDocument}, etc.\@) would have no
% effect (as would the use of such a command inside the hook code
% itself). It is therefore customary to redefine
% \cs{\meta{addto-cmd}} to simply process its argument, i.e.,
% essentially make it behave like \cs{@firstofone}.
%
% \cs{UseOneTimeHook} does that: it records that the hook has been
% consumed and any further attempt to add to it will result in
% executing the code to be added immediately.
%
% Using \cs{UseOneTimeHook} several times with the same
% \Arg{hook} means that it only executes the first time it is used.
% For example, if it is used in a command that can be called several times
% then the hook executes during only the \emph{first} invocation of that
% command; this allows its use as an \enquote{initialization hook}.
%
% Mixing \cs{UseHook} and \cs{UseOneTimeHook} for the same
% \Arg{hook} should be avoided, but if this is done then neither will execute
% after the first \cs{UseOneTimeHook}.
%
% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
% A leading |.| is treated literally. See
% section~\ref{sec:default-label} for details.
%
% \end{function}
%
% \begin{function}{\UseOneTimeHookWithArguments}
% \begin{syntax}
% \cs{UseOneTimeHookWithArguments} \Arg{hook} \Arg{number} \Arg{arg_1} \ldots \Arg{arg_n}
% \end{syntax}
% Works exactly like \cs{UseOneTimeHook}, but passes arguments
% \Arg{arg_1} through \Arg{arg_n} to the \meta{hook}.
% The \meta{number} should be the number of arguments declared for
% the hook. If the hook is not declared, this command does nothing
% and it will remove \meta{number} items from the input.
%
% It should be noted that after a one-time hook is used, it is no
% longer possible to use \cs{AddToHookWithArguments} or similar with
% that hook. \cs{AddToHook} continues to work as normal.
% Section~\ref{sec:hook-args} explains hooks with arguments.
%
% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
% A leading |.| is treated literally. See
% section~\ref{sec:default-label} for details.
%
% \end{function}
%
%
% \subsubsection{Updating code for hooks}
%
% In contrast to the commands from the previous section, declarations
% such as \cs{AddToHook} or \cs{DeclareHookRule} can be
% used even when the hook is not yet declared. The rationale is that
% the hook declaration may be in some package that is loaded later, or
% perhaps not loaded at all.
%
% A side effect of this design is that misspellings do not raise an
% error but are simply regarded as declarations for hooks with a
% different name.
%
% \begin{function}{\AddToHook}
% \begin{syntax}
% \cs{AddToHook} \Arg{hook} \oarg{label} \Arg{code}
% \end{syntax}
% Adds \meta{code} to the \meta{hook} labeled by \meta{label}.
% When the optional argument \meta{label} is not provided, the
% \meta{default label} is used (see section~\ref{sec:default-label}).
% If \cs{AddToHook} is used in a package/class, the
% \meta{default label} is the package/class name, otherwise it is
% \texttt{top-level} (the \texttt{top-level} label is treated
% differently: see section~\ref{sec:top-level}).
%
% If there already exists code under the \meta{label} then the new
% \meta{code} is appended to the existing one (even if this is a reversed hook).
% If you want to replace existing code under the
% \meta{label}, first apply \cs{RemoveFromHook}.
%
% The hook doesn't have to exist for code to be added to
% it. However, if it is not declared, then obviously the
% added \meta{code} will never be executed. This
% allows for hooks to work regardless of package loading order and
% enables packages to add to hooks from other packages without
% worrying whether they are actually used in the current document.
% See section~\ref{sec:querying}.
%
% The \meta{hook} and \meta{label} can be specified using the
% dot-syntax to denote the current package name.
% See section~\ref{sec:default-label}.
% \end{function}
%
% \begin{function}{\AddToHookWithArguments}
% \begin{syntax}
% \cs{AddToHookWithArguments} \Arg{hook} \oarg{label} \Arg{code}
% \end{syntax}
% Works exactly like \cs{AddToHook}, except that the \meta{code} can
% access the arguments passed to the hook using \verb|#1|, \verb|#2|,
% \ldots, \verb|#n| (up to the number of arguments declared for the
% hook). If the \meta{code} should contain \emph{parameter tokens}
% (\verb|#|) that are not supposed to be understood as the arguments
% of the hook, such tokens should be doubled. For example, with
% \cs{AddToHook} one can write:
%\begin{verbatim}
% \AddToHook{myhook}{\def\foo#1{Hello, #1!}}
%\end{verbatim}
% but to achieve the same with \cs{AddToHookWithArguments}, one should
% write:
%\begin{verbatim}
% \AddToHookWithArguments{myhook}{\def\foo##1{Hello, ##1!}}
%\end{verbatim}
% because in the latter case, \verb|#1| refers to the first argument
% of the hook \hook{myhook}.
% Section~\ref{sec:hook-args} explains hooks with arguments.
%
% The \meta{hook} and \meta{label} can be specified using the
% dot-syntax to denote the current package name.
% See section~\ref{sec:default-label}.
% \end{function}
%
% \begin{function}{\RemoveFromHook}
% \begin{syntax}
% \cs{RemoveFromHook} \Arg{hook} \oarg{label}
% \end{syntax}
% Removes any code labeled by \meta{label} from the \meta{hook}.
% When the optional argument \meta{label} is not provided, the
% \meta{default label} is used (see section~\ref{sec:default-label}).
% \end{function}
%
% If there is no code under the \meta{label} in the \meta{hook},
% or if the \meta{hook} does not exist, a warning is issued when
% you attempt to \cs{RemoveFromHook}, and the command is ignored.
% \cs{RemoveFromHook}\marginpar{\raggedleft\rightskip5pt\itshape
% \textbf{Important:}\break The \cs{RemoveFromHook} command should be
% only used if one has full control over the code chunk to be removed.
% In particular it should not be used to remove code chunks from other
% packages! For this the \texttt{voids} relation is provided.}
% should be used only when you know exactly what
% labels are in a hook. Typically this will be when some code gets added to a hook
% by a package, then later this code is removed by that same package.
% If you want to prevent the execution of code from another
% package, use the |voids| rule instead (see section~\ref{sec:rules}).
%
% If the optional \meta{label} argument is \texttt{*}, then all code chunks are
% removed. This is rather dangerous as it may well drop code from other
% packages (that one may not know about); it should therefore not be used
% in packages but only in document preambles!
%
% The \meta{hook} and \meta{label} can be specified using the
% dot-syntax to denote the current package name.
% See section~\ref{sec:default-label}.
%
% In contrast to the \texttt {voids} relationship between two labels
% in a \cs{DeclareHookRule} this is a destructive operation as the
% labeled code is removed from the hook data structure, whereas the
% relationship setting can be undone by providing a different
% relationship later.
%
% \medskip
%
% A useful application for this declaration inside the document body
% is when one wants to temporarily add code to hooks and later remove
% it again, e.g.,
% \changes{v1.1l}{2025/01/03}{Correct example to use \texttt{env/quote/begin}
% instead of \texttt{/before} (gh/1599)}
%\begin{verbatim}
% \AddToHook{env/quote/begin}{\small}
% \begin{quote}
% A quote set in a smaller typeface
% \end{quote}
% ...
% \RemoveFromHook{env/quote/begin}
% ... now back to normal for further quotes
%\end{verbatim}
% Note that you can't cancel the setting with
%\begin{verbatim}
% \AddToHook{env/quote/begin}{}
%\end{verbatim}
% because that only \enquote{adds} a further empty chunk of code to
% the hook. Adding \cs{normalsize} would work but that means the hook
% then contained \cs{small}\cs{normalsize} which means two font size
% changes for no good reason.
%
% The above is only needed if one wants to typeset several quotes in a
% smaller typeface. If the hook is only needed once then
% \cs{AddToHookNext} is simpler, because it resets itself after one use.
%
%
% \begin{function}{\AddToHookNext}
% \begin{syntax}
% \cs{AddToHookNext} \Arg{hook} \Arg{code}
% \end{syntax}
% Adds \meta{code} to the next invocation of the \meta{hook}.
% The code is executed after the normal hook code has finished and
% it is executed only once, i.e. it is deleted after it was used.
%
% Using this declaration is a global operation, i.e., the code is
% not lost even if the declaration is used inside a group and the
% next invocation of the hook happens after the end of that group.
% If the declaration is
% used several times before the hook is executed then all code is
% executed in the order in which it was declared.\footnotemark
%
% If this declaration is used with a one-time hook then the code
% is only ever used if the declaration comes before the hook’s
% invocation. This is because, in contrast
% to \cs{AddToHook}, the code in this declaration is not
% executed immediately in the case when the invocation of the hook
% has already happened---in other words, this code will truly execute
% only on the next invocation of the hook (and in the case of a
% one-time hook there is no such \enquote{next invocation}).
% This gives you a choice: should my code execute
% always, or should it execute only at the point where the
% one-time hook is used (and not at all if this is impossible)? For
% both of these possibilities there are use cases.
%
% It is possible to nest this declaration using the same hook (or
% different hooks): e.g.,
% \begin{quote}
% \cs{AddToHookNext}\Arg{hook}\verb={=\meta{code-1}^^A
% \cs{AddToHookNext}\Arg{hook}\Arg{code-2}\verb=}=
% \end{quote}
% will execute \meta{code-1} next time the \meta{hook} is used and at
% that point puts \meta{code-2} into the \meta{hook} so that it gets
% executed on following time the hook is run.
%
% A hook doesn't have to exist for code to be added to it. This
% allows for hooks to work regardless of package loading
% order.
% See section~\ref{sec:querying}.
%
% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
% \end{function}\footnotetext{There is
% no mechanism to reorder such code chunks (or delete them).}
%
% \begin{function}{\AddToHookNextWithArguments}
% \begin{syntax}
% \cs{AddToHookNextWithArguments} \Arg{hook} \Arg{code}
% \end{syntax}
% Works exactly like \cs{AddToHookNext}, but the \meta{code} can
% contain references to the arguments of the \meta{hook} as described
% for \cs{AddToHookWithArguments} above.
% Section~\ref{sec:hook-args} explains hooks with arguments.
%
% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
% \end{function}
%
%
%
% \begin{function}{\ClearHookNext}
% \begin{syntax}
% \cs{ClearHookNext} \Arg{hook}
% \end{syntax}
% Normally \cs{AddToHookNext} is only used when you know precisely
% where it will apply and why you want some extra code at that
% point. However, there are a few use cases in which such a
% declaration needs to be canceled, for example, when
% discarding a page with \cs{DiscardShipoutBox} (but even then not
% always), and in such situations \cs{ClearHookNext} can be
% used.
% \end{function}
%
%
%
%
% \subsubsection{Hook names and default labels}
% \label{sec:default-label}
%
% It is best practice to use \cs{AddToHook} in packages or classes
% \emph{without specifying a \meta{label}} because then the package
% or class name is automatically used, which is helpful if rules are
% needed, and avoids mistyping the \meta{label}.
%
% Using an explicit \meta{label} is only necessary in very specific
% situations, e.g., if you want to add several chunks of code into a
% single hook and have them placed in different parts of the hook
% (by providing some rules).
%
% The other case is when you develop a larger package with several
% sub-packages. In that case you may want to use the same
% \meta{label} throughout the sub-packages in order to avoid
% that the labels change if you internally reorganize your code.
%
% Except for \cs{UseHook}, \cs{UseOneTimeHook} and \cs{IfHookEmptyTF}
% (and their \pkg{expl3} interfaces \cs{hook_use:n},
% \cs{hook_use_once:n} and \cs{hook_if_empty:nTF}), all \meta{hook}
% and \meta{label} arguments are processed in the same way: first,
% spaces are trimmed around the argument, then it is fully expanded
% until only character tokens remain. If the full expansion of the
% \meta{hook} or \meta{label} contains a non-expandable non-character
% token, a low-level \TeX{} error is raised (namely, the \meta{hook} is
% expanded using \TeX's \cs{csname}\ldots\cs{endcsname}, as such,
% Unicode characters are allowed in \meta{hook} and \meta{label}
% arguments). The arguments of \cs{UseHook}, \cs{UseOneTimeHook}, and
% \cs{IfHookEmptyTF} are
% processed much in the same way except that spaces are not trimmed
% around the argument, for better performance.
%
% It is not enforced, but highly recommended that the hooks defined by
% a package, and the \meta{labels} used to add code to other hooks
% contain the package name to easily identify the source of the code
% chunk and to prevent clashes. This should be the standard practice,
% so this hook management code provides a shortcut to refer to the
% current package in the name of a \meta{hook} and in a \meta{label}.
% If the \meta{hook} name or the \meta{label} consist just of a single dot
% (|.|), or starts with a dot followed by a slash (|./|) then the dot
% denotes the \meta{default label} (usually the current package or class
% name---see~\cs{SetDefaultHookLabel}).
% A \enquote{|.|} or \enquote{|./|} anywhere else in a \meta{hook} or in
% \meta{label} is treated literally and is not replaced.
%
% For example,
% inside the package \texttt{mypackage.sty}, the default label is
% \texttt{mypackage}, so the instructions:
% \begin{verbatim}
% \NewHook {./hook}
% \AddToHook {./hook}[.]{code} % Same as \AddToHook{./hook}{code}
% \AddToHook {./hook}[./sub]{code}
% \DeclareHookRule{begindocument}{.}{before}{babel}
% \AddToHook {file/foo.tex/after}{code}
% \end{verbatim}
% are equivalent to:
% \begin{verbatim}
% \NewHook {mypackage/hook}
% \AddToHook {mypackage/hook}[mypackage]{code}
% \AddToHook {mypackage/hook}[mypackage/sub]{code}
% \DeclareHookRule{begindocument}{mypackage}{before}{babel}
% \AddToHook {file/foo.tex/after}{code} % unchanged
% \end{verbatim}
%
% The \meta{default label} is automatically set equal to the name of the
% current package or class at the time the package is loaded. If the
% hook command is used outside of a package, or the current file wasn't
% loaded with \cs{usepackage} or \cs{documentclass}, then the
% \texttt{top-level} is used as the \meta{default label}. This may have
% exceptions---see \cs{PushDefaultHookLabel}.
%
% This syntax is available in all \meta{label} arguments and most
% \meta{hook} arguments, both in the \LaTeXe{} interface, and the \LaTeX3
% interface described in section~\ref{sec:l3hook-interface}.
%
% Note,\marginpar{\raggedleft\rightskip5pt\itshape \textbf{Important:}\break The dot-syntax
% is \textbf{not} available with
% \cs{UseHook} and some other commands that are typically used within code!}
% however, that the replacement of |.| by the \meta{default label}
% takes place when the hook command is executed, so actions that are
% somehow executed after the package ends will have the wrong
% \meta{default label} if the dot-syntax is used. For that reason,
% this syntax is not available in \cs{UseHook} (and \cs{hook_use:n})
% because the hook is most of the time used outside of the package file
% in which it was defined. This syntax is also not available in the hook
% conditionals \cs{IfHookEmptyTF} (and \cs{hook_if_empty:nTF}), because these
% conditionals are used in some performance-critical parts of the hook
% management code, and because they are usually used to refer to other
% package's hooks, so the dot-syntax doesn't make much sense.
%
% In some cases, for example in large packages, one may want to separate
% the code in logical parts, but still use the main package name as the
% \meta{label}, then the \meta{default label} can be set using
% \cs{PushDefaultHookLabel}\verb={...}=\,\ldots\cs{PopDefaultHookLabel}
% or \cs{SetDefaultHookLabel}\verb={...}=.
%
% \begin{function}{\PushDefaultHookLabel,\PopDefaultHookLabel}
% \begin{syntax}
% \cs{PushDefaultHookLabel} \Arg{default label}
% \quad \meta{code}
% \cs{PopDefaultHookLabel}
% \end{syntax}
% \cs{PushDefaultHookLabel} sets the current \meta{default label} to
% be used in \meta{label} arguments, or when replacing a leading
% ``|.|'' (see above). \cs{PopDefaultHookLabel} reverts the
% \meta{default label} to its previous value.
%
% Inside a package or class, the \meta{default label} is equal to the
% package or class name, unless explicitly changed. Everywhere else,
% the \meta{default label} is |top-level| (see
% section~\ref{sec:top-level}) unless explicitly changed.
%
% The effect of \cs{PushDefaultHookLabel} holds until the next
% \cs{PopDefaultHookLabel}. \cs{usepackage} (and \cs{RequirePackage}
% and \cs{documentclass}) internally use
% \begin{quote}
% \cs{PushDefaultHookLabel}\Arg{package name} \\
% \null \quad \meta{package code} \\
% \cs{PopDefaultHookLabel}
% \end{quote}
% to set the \meta{default label} for the package or class file.
% Inside the \meta{package code} the \meta{default label} can also be
% changed with \cs{SetDefaultHookLabel}. \cs{input} and other
% file input-related commands from the \LaTeX{} kernel do not use
% \cs{PushDefaultHookLabel}, so code within files loaded by these
% commands does \emph{not} get a dedicated \meta{label}! (that is, the
% \meta{default label} is the current active one when the file was
% loaded.)
%
% Packages that provide their own package-like interfaces
% (Ti\textit{k}Z's \cs{usetikzlibrary}, for example) can use
% \cs{PushDefaultHookLabel} and \cs{PopDefaultHookLabel} to set
% dedicated labels and to emulate \cs{usepackage}-like hook behavior
% within those contexts.
%
% The |top-level| label is treated differently, and is reserved to the
% user document, so it is not allowed to change the
% \meta{default label} to |top-level|.
% \end{function}
%
% \begin{function}{\SetDefaultHookLabel}
% \begin{syntax}
% \cs{SetDefaultHookLabel} \Arg{default label}
% \end{syntax}
% Similarly to \cs{PushDefaultHookLabel},
% sets the current \meta{default label} to
% be used in \meta{label} arguments, or when replacing a leading
% ``|.|''. The effect holds until the label is changed again or until
% the next \cs{PopDefaultHookLabel}. The difference between
% \cs{PushDefaultHookLabel} and \cs{SetDefaultHookLabel} is that the
% latter does not save the current \meta{default label}.
%
% This command is useful when a large package is composed of several
% smaller packages, but all should have the same \meta{label}, so
% \cs{SetDefaultHookLabel} can be used at the beginning of each
% package file to set the correct label.
%
% \cs{SetDefaultHookLabel} is not allowed in the main document, where
% the \meta{default label} is |top-level| and there is no
% \cs{PopDefaultHookLabel} to end its effect.
% It is also not allowed to change the \meta{default label} to
% |top-level|.
% \end{function}
%
% \subsubsection{The \texttt{top-level} label}
% \label{sec:top-level}
%
% The |top-level| label, assigned to code added from the main document,
% is different from other labels. Code added to hooks (usually
% \cs{AtBeginDocument}) in the preamble is almost always to change
% something defined by a package, so it should go at the very end of the
% hook.
%
% Therefore, code added in the |top-level| is always executed at the end
% of the hook, regardless of where it was declared. If the hook is
% reversed (see \cs{NewReversedHook}), the |top-level| chunk is executed
% at the very beginning instead.
%
% Rules regarding |top-level| have no effect: if a user wants to have a
% specific set of rules for a code chunk, they should use a different
% label to said code chunk, and provide a rule for that label instead.
%
% The |top-level| label is exclusive for the user, so trying to add code
% with that label from a package results in an error.
%
% \subsubsection{Defining relations between hook code}
% \label{sec:rules}
%
% The default assumption is that code added to hooks by different
% packages are independent and the order in which they are executed is
% irrelevant. While this is true in many cases it is obviously false
% in others.
%
% Before the hook management system was introduced
% packages had to take elaborate precautions to determine whether some other
% package had also been loaded (before or after) and then to find some ways to
% alter its behavior accordingly. In addition is was often the user's
% responsibility to load packages in the right order so that alterations
% made by packages were done in thsat same order; and in some cases even
% altering the loading order wouldn't resolve the conflicts.
%
% With the new hook management system it is now possible to define
% rules (i.e., relationships) between code chunks added by different
% packages and to specify explicitly the order in which they should be
% processed.
%
% The rules can be declared for hooks before the hook has been
% declared with \cs{NewHook} and they are allowed to refer to code
% labels that do not yet exist, e.g., because a package defining the
% code chunk with that label has not yet been loaded.
% When the hook code is finally sorted for fast execution, all rules that apply are acted on
% and the others are ignored.
%
% This offers the flexibility needed to handle complicated
% relationships between code from different packages and to set this up
% beforehand in a way that is independent of whether or not the packages are actually loaded in a
% specific document. The downside of this is that misspellings of
% hook names or code labels will not raise any error, instead the rule
% will simply never apply!
%
% \begin{function}{\DeclareHookRule}
% \begin{syntax}
% \cs{DeclareHookRule} \Arg{hook} \Arg{label1} \Arg{relation} \Arg{label2}
% \end{syntax}
% Defines a relation between \meta{label1} and \meta{label2} for a
% given \meta{hook}. If \meta{hook} is \texttt{??} this defines a default
% relation for all hooks that use the two labels, i.e., that have
% chunks of code labeled with \meta{label1} and \meta{label2}.
%
% Currently, the supported relations are the following:
% \begin{itemize}
%
% \item[\texttt{before} or \texttt{\string<}]
%
% Code for \meta{label1} comes before code for \meta{label2}.
%
% \item[\texttt{after} or \texttt{\string>}]
% Code for \meta{label1} comes after code for \meta{label2}.
%
% \item[\texttt{incompatible-warning}]
%
% Only code for either \meta{label1} or \meta{label2} can appear
% for that hook (a way to say that two packages---or parts of
% them---are incompatible). A warning is raised if both labels
% appear in the same hook.
%
% \item[\texttt{incompatible-error}]
%
% Like \texttt{incompatible-error} but instead of a warning a
% \LaTeX{} error is raised, and the code for both labels are
% dropped from that hook until the conflict is resolved.
%
% \item[\texttt{voids}]
%
% Code for \meta{label1} overwrites code for \meta{label2}. More
% precisely, code for \meta{label2} is dropped for that
% hook. This can be used, for example if one package is a
% superset in functionality of another one and therefore wants to
% undo code in some hook and replace it with its own version.
%
% \item[\texttt{unrelated}]
%
% The order of code for \meta{label1} and \meta{label2} is
% irrelevant. This rule is there to undo an incorrect rule
% specified earlier.
%
% \end{itemize}
% There can only be a single relation between two labels for a
% given hook, i.e., a later \cs{DeclareHookRule} overwrites any
% previous declaration. In all cases rules specific to a given
% hook take precedence over default rules that use \texttt{??} as
% the \meta{hook}.
%
% If a default rule is applied, it is done before reversing the
% label order in a reversed hook, e.g., \texttt{before} in a
% default rule effectively becomes \texttt{after} in such a hook.
% In contrast, a rule for a specific hook is always applied to the
% state after any reversal (i.e., the state you see when using
% \cs{ShowHook} on that hook).
%
% The \meta{hook} and \meta{label} can be specified using the
% dot-syntax to denote the current package name.
% See section~\ref{sec:default-label}.
%
% \end{function}
%
%
% \begin{function}{\ClearHookRule}
% \begin{syntax}
% \cs{ClearHookRule} \Arg{hook} \Arg{label1} \Arg{label2}
% \end{syntax}
% Syntactic sugar for saying that \meta{label1} and \meta{label2}
% are unrelated for the given \meta{hook}.
% \end{function}
%
%
%
% \begin{function}{\DeclareDefaultHookRule}
% \begin{syntax}
% \cs{DeclareDefaultHookRule} \Arg{label1} \Arg{relation} \Arg{label2}
% \end{syntax}
% This sets up a relation between \meta{label1} and \meta{label2}
% for all hooks unless overwritten by a specific rule for a hook.
% Useful for cases where one package has a specific relation to
% some other package, e.g., is \texttt{incompatible} or always
% needs a special ordering \texttt{before} or \texttt{after}.
% (Technically it is just a shorthand for using \cs{DeclareHookRule}
% with \texttt{??} as the hook name.)
%
% If such a rule is applied to a reversed
% hook it behaves as if the rule is reversed (e.g.,
% \texttt{after} becomes \texttt{before})
% because those rules are applied first and then the order is reversed.
% The rationale is that in hook pairs (in which the ordering in one
% is reversed) default rules have to be reversed too in nearly all
% scenarios. If this is not the case, a default rule can't be used
% or has to be overwritten with an explicit \cs{DeclareHookRule}
% for that specific hook.
%
% Declaring default rules is only supported in the document
% preamble.\footnotemark{}
%
% The \meta{label} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
% \end{function}\footnotetext{Trying to do so, e.g., via
% \cs{DeclareHookRule} with \texttt{??} has bad side-effects and
% is not supported (though not explicitly caught for performance
% reasons).}
%
%
%
% \subsubsection{Querying hooks}
% \label{sec:querying}
%
% Simpler data types, like token lists, have three possible states; they
% can:
% \begin{itemize}
% \item exist and be empty;
% \item exist and be non-empty; and
% \item not exist (in which case emptiness doesn't apply);
% \end{itemize}
% Hooks are a bit more complicated:
% a hook may exist or not, and independently it may or may not be empty.
% This means that even a hook that doesn't exist may be non-empty and
% it can also be disabled.
%
% This seemingly strange state may happen when, for example, package~$A$
% defines hook \hook{A/foo}, and package $B$ adds some code to that
% hook. However, a document may load package $B$ before package $A$, or
% may not load package $A$ at all. In both cases some code is added to
% hook \hook{A/foo} without that hook being defined yet, thus that
% hook is said to be non-empty, whereas it doesn't exist. Therefore,
% querying the existence of a hook doesn't imply its emptiness, neither
% does the other way around.
%
% Given that code or rules can be added to a hook even if it doesn't
% physically exist yet, means that a querying its existence has no
% real use case (in contrast to other variables that can only be
% update if they have already been declared). For that reason only the
% test for emptiness has a public interface.
%
% A hook is said to be empty when no code was added to it, either to
% its permanent code pool, or to its ``next'' token list. The hook
% doesn't need to be declared to have code added to its code pool.
% A hook is said to exist when it was declared with \cs{NewHook} or
% some variant thereof. Generic hooks such as \hook{file/\meta{???}} and \hook{env/\meta{???}} hooks are
% automatically declared when code is added to them.
%
% \begin{function}[EXP]{\IfHookEmptyTF,\IfHookEmptyT,\IfHookEmptyF}
% \begin{syntax}
% \cs{IfHookEmptyTF} \Arg{hook} \Arg{true code} \Arg{false code}
% \end{syntax}
% Tests if the \meta{hook} is empty (\emph{i.e.}, no code was added to
% it using either \cs{AddToHook} or \cs{AddToHookNext}) or such code
% was removed again (via \cs{RemoveFromHook}), and
% branches to either \meta{true code} or \meta{false code} depending
% on the result.
%
% The \meta{hook} \emph{cannot} be specified using the dot-syntax.
% A leading |.| is treated literally.
% \end{function}
%
%
%
% \subsubsection{Displaying hook code}\label{sec:display-hooks}
%
% If one has to adjust the code execution in a hook using a hook
% rule it is helpful to get some information about the code
% associated with a hook, its current order and the existing rules.
%
% \begin{function}{\ShowHook,\LogHook}
% \begin{syntax}
% \cs{ShowHook} \Arg{hook}
% \cs{LogHook} \Arg{hook}
% \end{syntax}
% Displays information about the \meta{hook} such as
% \begin{itemize}
% \item
% the code chunks (and their labels) added to it,
% \item
% any rules set up to order them,
% \item
% the computed order in which the chunks are executed,
% \item
% any code executed on the next invocation only.
% \end{itemize}
% \end{function}
%
% \cs{LogHook} prints the information to the |.log| file, and
% \cs{ShowHook} prints them to the terminal/command window and starts
% \TeX's prompt (only in \cs{errorstopmode}) to wait for user action.
%
% The \meta{hook} can be specified using the dot-syntax to denote
% the current package name. See section~\ref{sec:default-label}.
%
%^^A % Code for the listing below:
%^^A \NewHook{example-hook}
%^^A \AddToHook{example-hook}{[code from 'top-level']}
%^^A \AddToHook{example-hook}[foo]{[code from package 'foo']}
%^^A \AddToHook{example-hook}[bar]{[from package 'bar']}
%^^A \AddToHook{example-hook}[baz]{[package 'baz' is here]}
%^^A \AddToHookNext{example-hook}{[one-time code]}
%^^A \DeclareHookRule{example-hook}{baz}{before}{foo}
%^^A \DeclareDefaultHookRule{bar}{after}{baz}
%^^A \ShowHook{example-hook}
%
% \def\theFancyVerbLine{\textcolor[gray]{0.5}{%^^A
% \sffamily\tiny\arabic{FancyVerbLine}}}
%
% \bigskip
% Suppose a hook \texttt{example-hook} whose output of
% \cs{ShowHook}|{example-hook}| is:
% \begin{verbatim}[numbers=left]
% -> The hook 'example-hook':
% > Code chunks: