IronPort-PHdr: =?us-ascii?q?9a23=3Ah4V9gxDI10+TjcRVzEEyUyQJPHJ1kqjoPgMT9p?=
               =?us-ascii?q?ssgq5PdaLmxZn5IUjD/qw93A3TUIHS+qgCluzX9qDtWGAN5ZyMqn9EfJEfHw?=
               =?us-ascii?q?Qdh5AwmAotSNWAFVW9NOTjOi49B8laVBl65XC0MVR9HcHkYVzUrWau5CRIXB?=
               =?us-ascii?q?74cxd2dazuAoCHqcOx2qip/oHLJQBBhT6ze7R3eRextgjJto8Jm4ptKroZzx?=
               =?us-ascii?q?zTpHpOdP9KzHkyY1mU2Qv/tY+r5JA21SNWtro68tJYF6X3e6NtVbtDEDEvKH?=
               =?us-ascii?q?w4/uXuvBjHCBSKvz4SDjlQnR1PDAzIqhr9W86r4BH3ved8xiSWePbOY+toA2?=
               =?us-ascii?q?aE6KFmAF/yhSMOJmR/7WfWz8x9ja5WpBisvRM5z4OGKIeSfOFzeK/QZ7Z4DS?=
               =?us-ascii?q?JIQ9pRWipdA4i9c5pHDuwPOvxdppX8oF1GpAW3BA2lDufigjFSgXq+0ao/2u?=
               =?us-ascii?q?UnWQbIuW5oV9AJq3nMrJPqLqYdUfydya7SyzTFYOhK0C2nroPPNA0i4LmNUb?=
               =?us-ascii?q?92bcvN2Bw3DQqW6zfY4YfhPj6TyqEMqz3Bt7smBb/p0jR37V0t8XC1y8whi5?=
               =?us-ascii?q?fEnNcPx1TN5H8/3YA0YN21SUJ2ZdSpCpQWuyzJUuk+Cs4kXWxsvz43j7Mcvp?=
               =?us-ascii?q?vuNioN05k/x1jAcf2Ic5Sg5xX5UueXLixkjWg/Prm4wQuxuxvFqKW0Royv3V?=
               =?us-ascii?q?BGozAQ2NvLrX0V11rM8MmISudV+0C73zeJ2BvP4/seZ0sz07fYYc1EoPZ4ht?=
               =?us-ascii?q?8YtkLNGTXzkUP9gfqNd0kqzeOv7vzufrTsopLFbd1OhwrzM7ojlomEOcpjbl?=
               =?us-ascii?q?dceW+d9Kz8zrDn9FyjBqhMj7g2n6jVvZTQKN4U4KK0UUdT1c445hCzAi3Dsp?=
               =?us-ascii?q?xQlGQbLF9DZBOMjpT4c1DILvfiCP6jglOq2D51zvHCN7flD93DNH/G2LvmeL?=
               =?us-ascii?q?987QZbxm9RhZhd4IlZErFHP+jyVU/tnNnfFBk4NQOv3+/9UpN20cUDWiPHA6?=
               =?us-ascii?q?OUNr/TrU7d4+suJ+eWY4pG3VS1Y/Mh5vPokTo4gQpHJfjvjcZRMSroWKg6cA?=
               =?us-ascii?q?2DbHHhg8kMCzIQsw43XbaslVuDFD5eZnq/W6gx/D59BI/1aOWLDo2rnrGF2z?=
               =?us-ascii?q?+2W5NMYWUTQFKLCnrwd8ObQfYDaD66J8h7lD0CWqO9QpV7kxqp8hL5gekCTK?=
               =?us-ascii?q?Kc6mgDuJTv2cIgre/Ujhwq9XprFcWS032lSmZumGIOSCQq1bol50d6jEqAm/?=
               =?us-ascii?q?sd4bQQBZlY4PVHVR0/PJjXwrlhCtz8bQnGe8+AVFesRtj/W2MLQ9k8wsEDbw?=
               =?us-ascii?q?NGI/v50k+R+S2sDvdVjbGPDY1utL/a3j3xKsdxxnLM2bMuyVUrEINJMiW9i6?=
               =?us-ascii?q?hz+hK2ZcaBmliFl6usaaUX3TLcvGaFw22UuUhEUQl2GazbVHEbb0HSoJz3/E?=
               =?us-ascii?q?THB7OpDL0mNENGx6vgYuNSbcb1iFxdWPr5ENHXYmb0hGLpQBjUmvWDa43lf2?=
               =?us-ascii?q?hb1yLYSQAFnw0V4XeaJF0+CyOm8Ae8RHRlEVPiZV+p8PEr8ivqCB9piVjQPw?=
               =?us-ascii?q?s9i+n94BMeiP2CRulGxL8AsTZ77ShyHRO90tPaBt6KqhBuOqlRMrZfqB9K03?=
               =?us-ascii?q?zUswtlM9muNadn0xQcdB96p0OoyA92BYVcuc0ttnUrygVpNauCihVKcHWF3t?=
               =?us-ascii?q?qjX9+fYnm35x2pZ6PMjxvG182K/64U9Pkig1DqvQXsCU97tns7j59a1HyT4p?=
               =?us-ascii?q?iMBw0XG8GUMA5/511xoLfUZTM47oXf2Ch3MKW6hTTF3sogGOovzhv5I4VvdZ?=
               =?us-ascii?q?icHQq3KPU0QtC0IbZyyV2udBQFOu9J6KcuZYWtcL2b2/zzZbsyrHedlW1Cpb?=
               =?us-ascii?q?tF/AeM+i57ELOa2p8Ex7SH21LCWWugylimtc/zlMZPYjRARjPumxihP5ZYY+?=
               =?us-ascii?q?hJRahODG6vJ8OtwdAk38zoXGRe9VisHE8PwpXvch3Ucl+vhQA=3D?=
References: <20200723020053.jq6lnwl7k23htouz@vento15post8>
            <CAOCj1Od4FqYrO02drsP43KWWEqusyYiGNgTLgsuvmELTKXxgBQ@mail.gmail.com>
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: 7bit
Message-ID:  <3f1f9ba8-7a63-bc32-58ec-b70a5d8fda11@morningstar2.co.uk>
Date:         Thu, 23 Jul 2020 11:00:27 +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:  <CAOCj1Od4FqYrO02drsP43KWWEqusyYiGNgTLgsuvmELTKXxgBQ@mail.gmail.com>
Precedence: list
Envelope-To: <rainer.schoepf@gmx.net>
Status: R

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