IronPort-PHdr: =?us-ascii?q?9a23=3AnAFWGBco8W5apb5a3X1zH4JTlGMj4e+mFxMJ6p?=
               =?us-ascii?q?chl7NFe7ii+JKnBkHE+PFxlwaZDdfB5vZNmrCQrqbhHGwN4JqMtHoPapMKWx?=
               =?us-ascii?q?JWwd4OkVkGB8iIQVb+MOasdzYzScZFT1J9/zekK0laGNrWYlrIpHy04iUOEw?=
               =?us-ascii?q?+lcwFyYPn2ScbJl8ri8ee09tXIZhlQwj+0YLd8NhKz+AfWrcQOgc19MKc+yg?=
               =?us-ascii?q?fhp3xSfeVQynh0LEjJ2R37oNqzr9Z46yoFnfUn+oZbVLniOaQ1SbsNFDM9L2?=
               =?us-ascii?q?U8/9HmrzHGRAqLo2QGCyAYzkEODA/C4xX3GJz2t3Kg5NBw0ySbI8D6CIsMd2?=
               =?us-ascii?q?/+tfVNTxnlwGcdOjow4TuRl8pxyaJWoR6soxZy2YGSbIzHfPx5NrjQe98XXw?=
               =?us-ascii?q?8jFo5YSjBBD4WgboAOE/tJPOBWqJP4rkcPqh32DBelBefmwDtFznHs2qhy3+?=
               =?us-ascii?q?MkGADAlAsuerBG+HbTt9jtNOENS+G6zLXgyDLZafJQ1izh4ZKSNBsm5+yPHP?=
               =?us-ascii?q?pxfcfX1UgzBlbdlFzDzO6tdziR1+kLry2a9786DbPp2zNh8Vso5GT0lY82h4?=
               =?us-ascii?q?LEh5wY0AXe+CFw0dxzONu5DU52YNKpFJFdrS7cO4YlJ6FqC2xupis+zaUL/J?=
               =?us-ascii?q?Chey1fgpYg3BPHa7qYaYmH4g7LUeGLJzZ+i2l5cajlwR21t1WjgL6ZNIH8wB?=
               =?us-ascii?q?NRoyxJn8OZ/HIKzBHL6o6YUPpy/luJ3DGV0QHV5fpYKFpu06HcbYMiiO1V9N?=
               =?us-ascii?q?JboQHIGSn4n1/zhamdexA/++Sm3O/gZ63vup6WM4It0FPEP68jm9KyDaEDCi?=
               =?us-ascii?q?ZVAzfJ3+O62fWj50D9SaQQyOAwk+zZvZHWKMARq7S2RQNYgM4l7F6kAjGq3c?=
               =?us-ascii?q?59/zFPJU9ZeB+Bk4niOk3faPH+A/Clhl2wkTBtj/nYN7zlC5/JIzDNirDkNb?=
               =?us-ascii?q?p67kddzkI0w7U9r9pWDaoMOPK1RVXwu9zEJho+KQq1xen8FNxnjMUVXiSSAe?=
               =?us-ascii?q?7RMa/ft0OJ+vN6JuCNYIEPvzOuTpptr/XqjHI/hRocZfzzhcpROC3+RK4/ZR?=
               =?us-ascii?q?nCMjL2j9wMEHkHpF8kQejjmQfETDhSIna/Xq4x4js2Eo3gAYqQI+LlyLGHwi?=
               =?us-ascii?q?q/GYVbI25cDVXZW3XvbIicW7ETciOdItNJlzseU7mnRJQ93Av08gT9jadkZL?=
               =?us-ascii?q?mxmGVQpdf42d556veG3xM17jFsD4KCyWCCT31cm2QSQT4w07tjqFYnjFyEl7?=
               =?us-ascii?q?V7ya89d5Qb97ZCVQE0MoTZxupxBoXpWw7PSdyOTU6vXtSsBTxoFIALztQDYl?=
               =?us-ascii?q?hwF5CZtj6Yg3X4JbgTmvTLHpEw+7OGmWX3JoN9xnfK2a0rgkMpBMdCZyWgge?=
               =?us-ascii?q?Zk+g7fCpSs8Q3Rnru2dakawC/G9XuShWuIskZCVQdsUKLDFXkBb0rSpN796w?=
               =?us-ascii?q?vMVbirQbggNwJAz4aFJM4oIpXxik5aQf74JNnES2e4mmP1GgzRg73QN8zlfG?=
               =?us-ascii?q?IS2CibA08B0kgS8XuAKQkiF3KhrmbZX1kMXRrkZ0Lh9/U7qWvuFBdliVHXKR?=
               =?us-ascii?q?c7jvzpoU1dn/GXRvIN06hRoioloiQuWku73pfWBtuMqg5rcb9TJ98wszIlnS?=
               =?us-ascii?q?rUsRJwOpu4IuVsnFkbJk51uFjjzxUxFZ9Bnsg2hHYt1gxzL62DzFpbLXWT2t?=
               =?us-ascii?q?btOfeETwu6tADqcKPQ1lzEhZyO/bwT7f0jt1j5lASgF05n7G8+ltcJiD2T4Z?=
               =?us-ascii?q?LFCAdUWpX0GBVSlVAyt/TRZS8z4JnR3HtnPPyvszPM7NkuAfMs1heqe9oGbf?=
               =?us-ascii?q?G0UTTqGshfPPCAbewnn1/zM0ABNeFWsbEuZoaoK6DA16msM+Jt2jmhiDYfud?=
               =?us-ascii?q?wv4ge37yN5D9Xw8dMd2fjChlmCUC36jVGuqdz+g9oCbjZUA2ntkXG1Vr4UXb?=
               =?us-ascii?q?V7eMMwMUnrJsS2wttkgJu3Ayxd80SlBlUJw9OgY0DUZFu7wA4CjUk=3D?=
References: <20200723020053.jq6lnwl7k23htouz@vento15post8>
            <CAOCj1Od4FqYrO02drsP43KWWEqusyYiGNgTLgsuvmELTKXxgBQ@mail.gmail.com>
            <3f1f9ba8-7a63-bc32-58ec-b70a5d8fda11@morningstar2.co.uk>
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:68.0) Gecko/20100101
            Thunderbird/68.10.0
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-GB
Content-Transfer-Encoding: 8bit
Message-ID:  <86ba52fc-9e65-fce6-c15f-a0f90394d22c@morningstar2.co.uk>
Date:         Thu, 23 Jul 2020 11:10:42 +0100
Reply-To:     Mailing list for the LaTeX3 project
              <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
Sender:       Mailing list for the LaTeX3 project <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
From:         Joseph Wright <joseph.wright@MORNINGSTAR2.CO.UK>
Subject: Re: Guidelines on the new hook management
To:           LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
In-Reply-To:  <3f1f9ba8-7a63-bc32-58ec-b70a5d8fda11@morningstar2.co.uk>
Precedence: list
Envelope-To: <rainer.schoepf@gmx.net>
Status: R

On 23/07/2020 11:00, Joseph Wright wrote:
> 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{<name>}{<code>}
> 
> or with a 'named' hook addition
> 
>      \AddToHook{<name>}[<pkg>]{<code>}
> 
> 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

I should add that we (LaTeX team) have been trying to identify possible 
issues in advance of the changes, such that we can both check our code 
can provide the required functionality and so we can help package 
authors with the required changes. There will doubtless be a few we've 
missed, hence the lead time before this code is intended to be released 
to the wider public.

Joseph