-
-
Notifications
You must be signed in to change notification settings - Fork 264
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Please provide details/examples about hooks #410
Comments
I would use the shipout/background or foreground hook to add pictures, for example
I don't really see a need for
Why? |
I think that sentence is a little misleading. The new hook implementation provides a single and consistent set of high-level commands, e.g.,
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. |
@FrankMittelbach I'm aware of that but what would have been a better place for such an "enhancement" issue? |
@u-fischer Thanks, that's what I was missing:
Sorry, the example was not well reduced: the real code involves
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. |
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 |
@FrankMittelbach Good choice, thanks for reopening! |
This issue has been automatically marked as stale because it has not had recent activity. |
An article with examples will have to wait until summer, but it is in the works ... |
I just read in the documentation and stumbled over hook |
As there is currently some activity at https://github.com/latex3/latex2e/tree/lthooks-doc-updates I just wanted to mention, that |
is used where @mrpiggi ? in the lthooks docs or elsewhere? |
Ah sorry, forgot to mention in the first comment that I'm taking about |
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. |
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:
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. |
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 Easier (and safer) is imho to use the
|
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. |
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, |
See also #1155 |
It would be nice if additional details/examples would be provided about hooks.
For instance, the
everypage
's documentation says:but section 2.4 "Emulating everypage" of
ltshipout
's documentation doesn't help me to know how to do a simple:I have read, in
ltfilehook
's documentation, section 1.5 "High-level interfaces for LaTeX":and that makes me sad 😉
The text was updated successfully, but these errors were encountered: