Label of codes added to LaTeX hooks

[muzimuzhi]

Assigning labels to hook code chunks opens the possibility to alter the execution order, if needed.

\AddToHook{<hook>}[<label>]{<code>}, if executed when loading a package, uses the (current) package name as default label; otherwise, uses default label top-level. (The texdoc lthooks-doc v1.1h (2024/04/22) is vague about this behavior, but it's reasonable that an \AddToHook hidden in a package macro then is only executed after knows nothing about which package it "belongs" to.)

Currently all uses of \AddToHook in tcolorbox are not executed when loading tcolorbox itself, thus an explicit label name tcolorbox is needed.

$ rg --no-heading 'Hook|\\hook' tex
tex/latex/tcolorbox/tcbdocumentation.code.tex:26:  \AddToHook{begindocument/before}{%
tex/latex/tcolorbox/tcolorbox.sty:1010:  \exp_args:Nne \hook_gput_next_code:nn {para/begin}
tex/latex/tcolorbox/tcolorbox.sty:2565:  \AddToHook{env/#1/before}{%
tex/latex/tcolorbox/tcolorbox.sty:2569:  \AddToHook{env/#1/after}{%

Note that \hook_gput_next_code:nn doesn't take a label argument so code added to next execution of a hook cannot be labeled.

Also compared to \AddToHook{<hook>}[<label>]{<code>}, \hook_gput_code:nnn{<hook>}{<label>}{<code>} saves the time to parse optional argument, hence is slightly quicker.

\documentclass{article}
\usepackage{tcolorbox}

\tcolorboxenvironment{itemize}{}
\ShowHook{env/itemize/before}

\begin{document}
\end{document}

-> The generic hook 'env/itemize/before':
> Code chunks:
>     ---
> Document-level (top-level) code (executed last):
>     -> \begin {tcolorbox}[{savedelimiter={itemize},,wrap@environment,code={\d
ef \tcb@end@tcolorboxenvironment {\end {tcolorbox}}}}]
> Extra code for next invocation:
>     ---
> Rules:
>     ---
> Execution order:
>     ---.
<recently read> }

[T-F-S]

Currently all uses of \AddToHook in tcolorbox are not executed when loading tcolorbox itself, thus an explicit label name tcolorbox is needed.

IMHO lthooks-doc is somewhat misleading in 2.1.5 stating

It is best practice to use \AddToHook in packages or classes without specifying a ⟨label⟩ because then the package or class name is automatically used, which is helpful if rules are needed, and avoids mistyping the ⟨label⟩.

Thank you for pointing me to the missing labels. I will add them for the next version. Also, tcbdocumentation.code.tex has a little bit hidden hook \AtEndPreamble where a label is needed as well.

[muzimuzhi]

Also, tcbdocumentation.code.tex has a little bit hidden hook \AtEndPreamble where a label is needed as well.

Oh I didn't notice this pattern. Searching by \At finds more:

$ rg --no-heading '\\At' tex
tex/latex/tcolorbox/tcolorbox.sty:1106:\AtBeginDocument{%
tex/latex/tcolorbox/tcolorbox.sty:1597:    \begingroup\edef\x{\endgroup\noexpand\AtEndDocument{\noexpand\tcb@saveehg{\tcb@ehgid}}}\x%
tex/latex/tcolorbox/tcbdocumentation.code.tex:69:\AtEndPreamble{%
tex/latex/tcolorbox/tcbdocumentation.code.tex:231:\AtBeginDocument{%
tex/latex/tcolorbox/tcbdocumentation.code.tex:925:\AtBeginDocument{%

[T-F-S]

Oh I didn't notice this pattern. Searching by \At finds more:

Yes, thank you. I missed this.