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
|
