1

This is both a question as well as a (potential) suggestion for the LaTeX3 documentation:

When specifying the syntax of documented macros, <description> is used to denote an argument to be filled in, produced by \meta{description}, which is a default macro in the l3doc class. However, these meta variables themselves are not documented (at least not all, and also not in a central place) like the functions themselves are.

In most cases, this is also not necessary, since the names are very descriptive, and one can deduce the exact meaning by context / macro documentation etc.

However, at least in some cases this has caused confusion for me, especially when code does not work and being unsure whether I understood the documentation the wrong way or whether my code was simply incorrect.

Concretely, I'm wondering what the meaning of <balanced text> exactly is. For me, at first glance this sounded like text, that is, no macros involved, no math mode etc. But I assume that this would technically just mean any sequence of tokens balanced with respect to the {} argument grouping, and so far this perceiption has worked out. Is this correct in general, or is there some more trickery involved?

Remarking a bit more: Are there considerations to introduce some index for the meta variables and also (shortly) document them - at least the nontrivial ones (whatever that means). I know that this also comes with some nonnegligible effort, but I believe that for such cases, this could really be beneficial. In the best case, this would truly yield some abstract grammar on how a LaTeX3 command (at least the non-weird etc) commands is formed, but of course this does not have to be the goal.

Thought the other way around, this could also be a good lookup table for other package authors on how to name their meta variables (and refer to the LaTeX3 documentation) to have some unique style for this.

Improve this question
3
  • this comes from the TeXBook (although l3 documentation ought to be self standing without requiring that) it more or less means a run of tokens with matching {...} so {ab {xyz}} but not {zzz
    – David Carlisle
    Jan 19, 2022 at 16:42
  • thanks, I'll look it up there in more detail.
    – Maximilian Keßler
    Jan 19, 2022 at 16:52
  • @MaximilianKeßler Also <balanced text> has no restriction on its contents (other than, of course, explicit { and } being balanced), so macros, math-mode material, or really anything goes (even implicit unbalanced braces, if you will) as long as explicit braces (if any) are balanced. Of course, depending on what function you are using, it may not make sense to pass math stuff as argument
    – Phelype Oleinik
    Jan 19, 2022 at 17:24

0

Reset to default

You must log in to answer this question.

Browse other questions tagged .