Please provide details/examples about hooks

[dbitouze]

It would be nice if additional details/examples would be provided about hooks.

For instance, the everypage's documentation says:

Functionality similar to that provided by this package is directly implemented in LaTeX since its 2020 Fall release. Do not use everypage in new documents and do not rely on it in new packages or classes of yours.

but section 2.4 "Emulating everypage" of ltshipout's documentation doesn't help me to know how to do a simple:

\AddEverypageHook{
  \tikz[remember~picture,overlay] { ... ; }
}

I have read, in ltfilehook's documentation, section 1.5 "High-level interfaces for LaTeX":

We do not provide any high-level LaTeX commands (like filehook or scrlfile do) but think that for package writers the commands from for hook management are sufficient.

and that makes me sad :wink:

[u-fischer]

but section 2.4 "Emulating everypage" of ltshipout's documentation doesn't help me to know how to do a simple:

I would use the shipout/background or foreground hook to add pictures, for example

\usepackage{tikzducks}
\AddToHook{shipout/background}{\put(0.5\paperwidth,-0.5\paperheight){\tikz[scale=3]\duck;}}

I don't really see a need for remember picture and overlay.

and that makes me sad

Why?

[FrankMittelbach]

I have read, in ltfilehook's documentation, section 1.5 "High-level interfaces for LaTeX":

We do not provide any high-level LaTeX commands (like filehook or scrlfile do) but think that for package writers the commands from for hook management are sufficient.

and that makes me sad 😉

I think that sentence is a little misleading. The new hook implementation provides a single and consistent set of high-level commands, e.g., \AddToHookand there is therefore no need to invent additional wrappers around each and every hook with names that often are rather arbitrary. What is the problem with writing in your package or class (or preamble)

\AddToHook{package/after/array}{ ... do something after array package was loaded ...}

This works consistently across all hooks and whether you have to remember the hook names (with consistent naming conventions) or a set of wrapper commands with sometimes strange names doesn't make much difference and I don't think it is anything to be sad about.

As to "please provide more examples" we agree with you that there is some potential for improvement and we plan at some point to write up an article for TUB on that subject. Anyway, please remember that we try to keep the issue list for latex2e as a list of "bugs" not as a more general discussion forum - thanks.

[dbitouze]

Anyway, please remember that we try to keep the issue list for latex2e as a list of "bugs" not as a more general discussion forum - thanks.

@FrankMittelbach I'm aware of that but what would have been a better place for such an "enhancement" issue?

[dbitouze]

I would use the shipout/background or foreground hook to add pictures, [...]

@u-fischer Thanks, that's what I was missing: everypage's documentation says "Functionality similar to that provided by this package is directly implemented in LaTeX" but without specifying the now LaTeX's (more or less) equivalents.

I don't really see a need for remember picture and overlay.

Sorry, the example was not well reduced: the real code involves tikzpagenodes code which requires remember picture and overlay.

and that makes me sad

Why?

I probably misunderstood this sentence but what I wanted to point out is the lack of correspondence between the old, "usual" hooks and the new ones, as said above.

[FrankMittelbach]

@FrankMittelbach I'm aware of that but what would have been a better place for such an "enhancement" issue?

I didn't mean to indicate that explicit enhancement requests (also those about documentation) should not go here, but they need to be actionable and not general discussions. I think your original issue was ok, my comment was more on reminding us to not start on going from A to B to X. So I keep this open as a task to add more examples to lthooks documentation.

[car222222]

@FrankMittelbach Good choice, thanks for reopening! "keep this open as a task to add more examples to lthooks documentation"

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity.

[FrankMittelbach]

An article with examples will have to wait until summer, but it is in the works ...

[mrpiggi]

So I keep this open as a task to add more examples to lthooks documentation.

I just read in the documentation and stumbled over hook ?? which is used for default relations. Despite the fact that the name of the hook is a bit unfortunate in my opinion and something like ?default? would be more comprehensible, a clearer markup in the documentation would make sense. In the first place, this actually looks like a reference to a non-existent label. Currently, lthooks.dtx contains both \texttt{??} as well as \verb=??=.

[mrpiggi]

As there is currently some activity at https://github.com/latex3/latex2e/tree/lthooks-doc-updates I just wanted to mention, that |??| is used as well at least two times

[FrankMittelbach]

that |??| is used as well at least two times

is used where @mrpiggi ? in the lthooks docs or elsewhere?

[mrpiggi]

Ah sorry, forgot to mention in the first comment that I'm taking about lthooks.dtx

[FrankMittelbach]

there have been some more examples in different places, but I'll keep this open to remind me that a full article one day would be nice.

[kmccurley]

It's now two years later, and this page showed up highly ranked for the query [latex lthooks examples]. I think the problem persists, and in fact this is endemic to a lot of LaTeX API documentation. There is a spectrum of documentation from "reference guides" to "cookbooks". Reference guides are the kind that list all API methods with no complete examples that combine any of them. At the other end of the spectrum is "cookbooks" that give complete examples but completely lack comprehensiveness. In the middle is "User's guide" which documents APIs and at the same time shows how to use them. Most packages have documentation written with a User's Guide, followed by an annotated description of the implementation. Unfortunately too many of the LaTeX APIs fall into the category of providing only a reference guide, which makes it very difficult for developers to get started. What happens is that people fall back to just looking at other .sty or .cls files to see how they used it. Unfortunately this slows down adoption and contributes to a lot of poorly written code in the code base. It's precisely the kind of complaint leveled against the use of stackoverflow, though occasionally you will see a very well written post there.

In the particular example of lthooks-doc.pdf, this is pretty close to being a bare reference guide. This not a criticism of the document itself, but rather a recognition that it falls to one end of the spectrum, and there is nothing resembling a User Guide or Cookbook that anyone can find. In this particular example, it would be useful to give some basic examples along with the explanation. For example, consider the two examples:

\AfterEndEnvironment{enumerate}{That was a list} 
\AtBeginEnvironment{enumerate}{\item first item}                                                     

The first one works pretty much as expected and is a simple example for how to add a hook to an environment. The second one doesn't work, apparently because the hook is executed before the environment is set up and \item is not yet defined. The natural question is: how would someone construct a hook that is executed after the environment is set up (i.e., to insert something after \begin{itemize} but before the first \item).

Adding too many of these things to a reference guide makes it unwieldy, but having none makes an API pretty impenetrable. It's not easy to strike the right balance.

[u-fischer]

@kmccurley

The natural question is: how would someone construct a hook that is executed after the environment is set up (i.e., to insert something after \begin{itemize} but before the first \item).

Generic hooks, hooks that work for all environments or commands, can only be added to "generic" places like the begin and the end. If you want to inject code in the middle of an environment—as a list has to setup lots of things, the first item is in the middle—then you will have to study the code to find a suitable place and method to inject your code. If you then find something (you can e.g. try \AddToHookNext{cmd/list/after}{\item first} or \AddToHookNext{cmd/item/before}{\item first item}) it will be quite specific to lists and your use case and so not something that you can find in some documentation.

Easier (and safer) is imho to use the enumitem package. It has an interface:

\documentclass{article}
\usepackage{enumitem}

\begin{document}
\begin{enumerate}[first=\item First item]
\item Second item
\end{enumerate}

\end{document}

[kmccurley]

I didn't really intend for this to become another stackexchange to resolve a particular question. I was merely providing an example of an unresolved question from the documentation. There is not a single example in the document with a value substituted for the arguments in \AddToHookNext, and this is what distinguishes the document as an API reference rather than a user's guide. The title of this issue is "Please provide details/examples about hooks" and the point is that there are no examples in the documentation.

[FrankMittelbach]

Agreed , this is an issue tracker and not helpful if it is mixed with "how can I ..." questions and answers.

Anyway, I agree with your comments and this is why this stays open, but the day has only 24 hours and writing good documentation takes a lot of time and at the moment I have other fish to fry.

And just as a side remark, \AtBeginEnvironment etc are commands we explicitly say we recommend not to use in new work (because they do not fit into naming conventions of the hook management system). They are only offered to mimic the interfaces of existing legacy packages that attempt to add hooks to environments that would conflict with hook mgt system if loaded on top.

[josephwright]

See also https://github.com/latex3/latex2e/issues/1155