guard hooks / config macros #36

New issue

Open

opened 2026-04-12 14:16:01 +00:00 by lukas · 1 comment

lukas commented

2026-04-12 14:16:01 +00:00

Owner

Currently there are several places where the user defines arbitrary code. For instance

\kataSection -> macro with one argument
/kata/step/before first -> code with no argument
\kataStepCnt -> macro with one argument

This approach is not entirely reliable. The user might define code which "eats" more tokens than expected leading to unexpected (and hard to debug) behavior. On the other side the code can also take too few arguments leading to spurious content placed in the document.

Several (new, modern) solutions to this problem exist:

sockets define sockets and plugs. A socket just defines an interface with the amount of arguments. A plug is some arbitrary code (written for that socket) which fits that interface
hooks are defined places where other component can add code to. Usually they don't have arguments (though arguments are possible). The specialty is that hooks are designed to handle multiple components adding code and the different code-chunks get sorted according to some rules.
templates are something like the generalized concept of sockets. The docs read like templates are more thought of being defined by LaTex and the being instanciated by packages/classes (not by the document author). But this feeling might also be wrong.

So sockets would probably the perfect fit.

Though, most users probably don't know how to work with sockets (yet). Thus I reverted to the more simpler (though not entirely "secure") version with concepts much more idiomatic in LaTeX right now.

Currently there are several places where the user defines arbitrary code. For instance - `\kataSection` -> macro with one argument - `/kata/step/before first` -> code with no argument - `\kataStepCnt` -> macro with one argument This approach is not entirely reliable. The user might define code which "eats" more tokens than expected leading to unexpected (and hard to debug) behavior. On the other side the code can also take too few arguments leading to spurious content placed in the document. Several (new, modern) solutions to this problem exist: 1. [`socket`s](https://tug.ctan.org/macros/latex-dev/base/ltsockets-code.pdf) define sockets and plugs. A socket just defines an interface with the amount of arguments. A plug is some arbitrary code (written for that socket) which fits that interface 2. [`hook`s](https://www.latex-project.org/help/documentation/lthooks-doc.pdf) are defined places where other component can add code to. Usually they don't have arguments (though arguments are possible). The specialty is that hooks are designed to handle multiple components adding code and the different code-chunks get sorted according to some rules. 3. [`template`s](https://tug.ctan.org/macros/latex-dev/base/lttemplates-doc.pdf) are something like the generalized concept of `socket`s. The docs read like templates are more thought of being defined by `LaTex` and the being instanciated by packages/classes (not by the document author). But this feeling might also be wrong. So `socket`s would probably the perfect fit. Though, most users probably don't know how to work with `socket`s (yet). Thus I reverted to the more simpler (though not entirely "secure") version with concepts much more idiomatic in LaTeX right now.