lthooks documentation

[jlaurens]

I find the hooking support implemented in LaTeX extremely useful, much more than the documentation suggests. In fact it was very hard for me to really understand this documentation. I found typos and minor errors here and there and wanted to post a simple issue. But the more I understood the concept, the more I found that the documentation does not play its role very well: many terms are not defined explicitly, same terms are used with different meanings, information on the same matter is spread all over the text, some information is of limited interest. For that reasons, I decided to do a bigger clean up and will post a pull request when done.

Two questions

1. Issues and PRs are not that practical to work on pdf documents. Exchanging by mail a pdf with annotations seems more efficient to me. Who would review such a doc?
2. I am facing a more important problem: When \NewHook{foo} has not been executed yet, the documentation and the L3 messages say interchangeably that the hook

• does not exist
• is not created
• is not declared
• is undeclared

The problem is that "not declared" and "undeclared" are not synonyms, and the latter does not apply here because one can declare hooks but cannot undeclare them. So I decided to consistently use the term "not declared" everywhere. Unfortunately, "undeclared" also appears in the code implementation in various functions and variables that are not documented. It makes sense to change undeclared into_notdeclared. If someone disagrees with that change, I will add instead a note in the implementation section to avoid a misunderstanding. Any objection?

[josephwright]

@FrankMittelbach and @PhelypeOleinik are the experts on the hook code and docs, but in terms of workflow the PDFs are just 'output': if you want to log comments or make a PR, this needs to be done at the level of the .dtx sources.

[github-actions[bot]]

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

[github-actions[bot]]

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