## LATEX-L@LISTSERV.UNI-HEIDELBERG.DE

 Options: Use Classic View Use Monospaced Font Show Text Part by Default Show All Mail Headers Topic: [<< First] [< Prev] [Next >] [Last >>]

 Re: Guidelines on the new hook management Joseph Wright <[log in to unmask]> Thu, 23 Jul 2020 11:00:27 +0100 text/plain (127 lines) On 23/07/2020 08:07, Michal Hoftich wrote: > Hi all, > >> Inspired by issue #900 on the PGF/TikZ repo [1], I'd like to kick off >> the discussion on how to correctly integrate the new hook management >> system into existing LaTeX package codebases. > > I've just tested latex-dev with TeX4ht and I can confirm that it > fatally crashes with latex-dev. > > Test file sample.tex: > > --- > \documentclass{article} > \begin{document} > Hello world > \end{document} > --- > > build file that requires latex-dev, sample.mk4: > > ---- > Make:htlatex {htlatex = "lualatex-dev"} > ---- > > Compile using: > > make4ht -a debug sample.tex > > The result: > > [STATUS] make4ht: Conversion started > [STATUS] make4ht: Input file: sample.tex > [ERROR] htlatex: Compilation errors in the htlatex run > [ERROR] htlatex: Filename Line Message > [ERROR] htlatex: ./sample.tex 2 Extra \endgroup. > [ERROR] htlatex: ? ? Emergency stop. > [ERROR] htlatex: ? ? ==> Fatal error occurred, no output > PDF file produced! > [FATAL] make4ht-lib: Fatal error. Command htlatex returned exit code 1 > > TeX4ht patches \document command on line 166 in tex4ht.sty. When I > comment out this definition, the compilation doesn't fail, but tags > inserted at the beginning of the HTML file are missing. So, the > question is, how can we adapt this existing code for the new LaTeX > hook handling? > > Best regards, > Michal > Hello Michal, The new hook code addresses a number of areas, but the key changes that may require package author action are - Any direct modification of \shipout, which *will* need to be altered - Any modification of the \document macro, which *may* need adjustment # Core idea In all cases, one would do      \AddToHook{}{} or with a 'named' hook addition      \AddToHook{}[]{} This latter form allows hooks to be sorted based on the pkg names. As I've detailed in the parallel reply to Henri, one will need to test for \AddToHook, most likely using \@ifundefined, to know that this functionality is available. # \shipout There are very few packages that actually modify the \shipout primitive: almost everyone uses either everyshi or atbegshi, and we have arranged for those to be emulated. As such, the only packages that need to be modified here are those that *directly*, which is limited as far as we know to pgf, crop and a few other packages. There are then a number of hooks one can use - shipout/before - shipout/foreground - shipout/background - shipout/firstpage - shipout/lastpage as described in "texdoc ltshipout". # \document Many more packages patch \document. Those adding code using \AtBeginDocument will have no issues: this kernel-level hook will continue to be available, although it is now a wrapper around \AddToHook. Many others will be using etoolbox's hooks: they are already aware of the new kernel hooks and again will need no work from package authors. For people directly altering \document, the need to take action will depend on the exact nature of the changes. For example, I have had to adjust beamer, but siunitx, which also patches \document, continues to work with no action. (I will update to use 'best practice', but that is not a *requirement*.) Basically, anything that starts messing with the detail of \document needs action, whereas simply adding a macro to the end of \document works out OK. Where you do need to take action, there are now a number of hooks - env/document/before: Occurs as soon as \begin{document} is seen,      before the group is opened - env/document/begin: Occurs just after environment group is opened:     for \document this is not really different from the above due to     the special nature of \document - begindocument: Replaces \AtBeginDocument, occurring after the .aux      file is read - begindocument/end: Occurs right at the end of \document, followed      only by \ignorespaces: where many people add 'last minute' stuff to      \document Hopefully, one or more of these hooks covers the use cases people have now: they were set up informed by etoolbox and others. Joseph