summaryrefslogtreecommitdiff
path: root/macros/latex/required/firstaid/latex2e-first-aid-for-external-files.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-10-02 03:03:29 +0000
committerNorbert Preining <norbert@preining.info>2020-10-02 03:03:29 +0000
commit37f9a57b2f39142fbccb20b758af8e0502499671 (patch)
tree3ad423febb91fa4309d19667a0423ae94e2ecb89 /macros/latex/required/firstaid/latex2e-first-aid-for-external-files.dtx
parentd2a6bb90e56a2836bb59477b8f27248aab9149f5 (diff)
CTAN sync 202010020303
Diffstat (limited to 'macros/latex/required/firstaid/latex2e-first-aid-for-external-files.dtx')
-rw-r--r--macros/latex/required/firstaid/latex2e-first-aid-for-external-files.dtx351
1 files changed, 351 insertions, 0 deletions
diff --git a/macros/latex/required/firstaid/latex2e-first-aid-for-external-files.dtx b/macros/latex/required/firstaid/latex2e-first-aid-for-external-files.dtx
new file mode 100644
index 0000000000..e722438fb1
--- /dev/null
+++ b/macros/latex/required/firstaid/latex2e-first-aid-for-external-files.dtx
@@ -0,0 +1,351 @@
+% \iffalse meta-comment
+%
+%% File: latex2e-first-aid-for-external-files.dtx (C) Copyright 2020
+%% The LaTeX Project and any individual authors listed elsewhere
+%% in this file.
+%
+% It may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3c
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% https://www.latex-project.org/lppl.txt
+% and version 1.3c or later is part of all distributions of LaTeX
+% version 2008 or later.
+%
+% This file has the LPPL maintenance status "maintained".
+%
+%
+%
+%<*driver>
+\documentclass{ltxdoc}
+\EnableCrossrefs
+\CodelineIndex
+\begin{document}
+ \DocInput{latex2e-first-aid-for-external-files.dtx}
+\end{document}
+%</driver>
+%
+% \fi
+%
+%
+% \providecommand\pkg[1]{\texttt{#1}}
+%
+% \title{First aid for external files and packages that need updating\thanks{}}
+% \author{Frank Mittelbach, \LaTeX{} Project}
+%
+% \maketitle
+%
+%
+% \begin{abstract}
+% This file contains some first aid for packages or classes that
+% require updates because of internal changes to \LaTeX{} but that
+% aren't yet reflected in the package/class code.
+% \end{abstract}
+%
+% \tableofcontents
+%
+% \section{Introduction}
+%
+% Over the years package writers have hooked into
+% various parts of internal \LaTeX{} commands (largely because
+% proper interfaces were missing in important places) and if
+% we are now gradually adding such interfaces these internal
+% commands do change and as a result patching into them stops
+% working.
+%
+% As part of making such internal changes the \LaTeX{} Project team
+% attempts to check for such usage in packages, alert the package
+% maintainers and ensures that the packages get updated alongside
+% the core \LaTeX{} system. However it is not always possible to
+% get packages that will fail with a new kernel updated in time and
+% if that is the case we try to provide a temporary fix in this
+% file for them.
+% Once the package gets updated the fix will then be removed again.
+%
+% For that reason, it is put into a separate bundle so that we can
+% update it easily without requiring the CTAN maintainers to
+% install a new full LaTeX system just because we take out (or add)
+% a fix for a package here.
+%
+% In the best case scenario the file documented here should be
+% empty. In practice it will probably always contain one or the
+% other fix while we are waiting for the package to get updated.
+%
+% \begin{quote} \textbf{Important notice:} The fixes provided here
+% are not meant to be a permanent solution, but are only provided
+% to support the transition period. They are (usually) neither
+% complete nor necessarily the best solution! Furthermore, as they
+% are done from the ``outside'', they usually add some burden and
+% slow down \LaTeX{} processing, even if the package/class is not
+% used in the document.
+%
+% We will therefore remove such code as soon as possible
+% again. In practice this means that if some package never gets
+% updated/corrected, then it will eventually fail to work, because
+% after one or at most two \LaTeX{} releases we will take out the
+% transition code to ensure that this ``first aid patching''
+% doesn't get out of bounds.
+% \end{quote}
+%
+% \StopEventually{\setlength\IndexMin{200pt} \PrintIndex }
+%
+%
+% \section{The Implementation}
+%
+% This file is meant to be loaded during format generation which is
+% why we give it the extension \texttt{.ltx}.
+% \begin{macrocode}
+%<*kernel>
+% \end{macrocode}
+%
+% \begin{macrocode}
+\def\LaTeXFirstAidDate{2020/09/29}
+\def\LaTeXFirstAidVersion{v1.0c}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\ProvidesFile{latex2e-first-aid-for-external-files.ltx}
+ [\LaTeXFirstAidDate\space \LaTeXFirstAidVersion\space
+ LaTeX kernel fixes to external files and packages]
+% \end{macrocode}
+ %
+
+% \begin{macro}{\FirstAidNeededT}
+% This is a very simple help to ensure that we only apply first aid
+% to an unmodified package or class. It only works in the case the
+% file has already been loaded and the csname \cs{ver@\#1.\#2} got
+% defined (holding the current date, version, and short description
+% info). We then compare its content to a frozen string and make
+% the modification \verb=#3= only if both agree. If they differ we
+% assume that the package/class in question got updated by its
+% maintainer.
+% \begin{macrocode}
+\ExplSyntaxOn
+\cs_new:Npn\FirstAidNeededT#1#2#3{
+ \exp_args:Nc\str_if_eq:onT{ver@#1.#2}{#3}
+}
+\ExplSyntaxOff
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+%</kernel>
+% \end{macrocode}
+%
+%
+% \subsection{The \pkg{filehook} package first aid}
+%
+% The \pkg{filehook} package implements hooks into file loading
+% commands. These days this is already provided by the kernel
+% albeit not with the same user interface. Until that package gets
+% updated (to use the kernel interfaces) we provide a
+% substitution. This does not offer all hooks from \pkg{filehook}
+% but all that have been used in packages available in \TeX{} Live.
+%
+% Note that this doesn't fix \pkg{currfile} because that package
+% uses \pkg{filehook} but relies on the internals of the old
+% implementation.
+%
+% The package has now got an update so we aren't activating the
+% first aid. However, it basically bypasses the new hook mechanism
+% and puts the old hooks in thereby disabling, for example, the
+% possibility to reorder code through rules.
+%
+% We therefore keep \texttt{filehook-ltx.sty} around as a guideline
+% for further updates.
+%
+% \begin{macrocode}
+%<*kernel>
+%\declare@file@substitution{filehook.sty}{filehook-ltx.sty}
+%</kernel>
+% \End{macrocode}
+%
+% If a new filehook package becomes available it can be tested
+% simply by undoing the above substitution via
+% \begin{verbatim}
+% \undeclare@file@substitution{filehook.sty}
+% \end{verbatim}
+% Once ready this will then taken out of the first aid file.
+%
+% What follows is a partial implementation of the \pkg{filehook}
+% interfaces.
+%
+% Not implemented are:
+%\begin{verbatim}
+% \AtBeginOfFiles
+% \AtEndOfFiles
+% \AtBeginOfInputs
+% \AtEndOfInputs
+% \AtBeginOfInputFile
+% \AtEndOfInputFile
+%\end{verbatim}
+%
+% \begin{macrocode}
+%<*filehook>
+% \end{macrocode}
+%
+% \begin{macrocode}
+\newcommand\AtBeginOfEveryFile [1]
+ {\AddToHook{file/before}{#1}}
+\newcommand\AtEndOfEveryFile [1]
+ {\AddToHook{file/after}{#1}}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\newcommand\AtBeginOfIncludes [1]
+ {\AddToHook{include/before}{#1}}
+\newcommand\AtEndOfIncludes [1]
+ {\AddToHook{include/end}{#1}}
+\newcommand\AfterIncludes [1]
+ {\AddToHook{include/after}{#1}}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\newcommand\AtBeginOfPackages [1]
+ {\AddToHook{package/before}{#1}}
+\newcommand\AtEndOfPackages [1]
+ {\AddToHook{package/after}{#1}}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\newcommand\AtBeginOfClasses [1]
+ {\AddToHook{class/before}{#1}}
+\newcommand\AtEndOfClasses [1]
+ {\AddToHook{class/after}{#1}}
+% \end{macrocode}
+%
+% For normal files we drop the \texttt{.tex} extension for now:
+% \begin{macrocode}
+\newcommand\AtBeginOfFile [2]
+ {\AddToHook{file/before/#1}{#2}}
+\newcommand\AtEndOfFile [2]
+ {\AddToHook{file/after/#1}{#2}}
+% \end{macrocode}
+%
+% \begin{macrocode}
+\DeclareDocumentCommand \AtBeginOfPackageFile {smm}
+ {\IfBooleanTF{#1}%
+ {\@ifpackageloaded{#2}%
+ {#3}%
+ {\AddToHook{package/before/#2}{#3}}}%
+ {\AddToHook{package/before/#2}{#3}}%
+ }
+\DeclareDocumentCommand \AtEndOfPackageFile {smm}
+ {\IfBooleanTF{#1}%
+ {\@ifpackageloaded{#2}%
+ {#3}%
+ {\AddToHook{package/after/#2}{#3}}}%
+ {\AddToHook{package/after/#2}{#3}}%
+ }
+% \end{macrocode}
+%
+% Are the * forms here of any use? I know they are use 3--4 times
+% on CTAN but I wonder if those are real or mistaken usages.
+% \begin{macrocode}
+\DeclareDocumentCommand \AtBeginOfClassFile {smm}
+ {\IfBooleanTF{#1}%
+ {\@ifclassloaded{#2}%
+ {#3}%
+ {\AddToHook{class/before/#2}{#3}}}%
+ {\AddToHook{class/before/#2}{#3}}%
+ }
+\DeclareDocumentCommand \AtEndOfClassFile {smm}
+ {\IfBooleanTF{#1}%
+ {\@ifclassloaded{#2}%
+ {#3}%
+ {\AddToHook{class/after/#2}{#3}}}%
+ {\AddToHook{class/after/#2}{#3}}%
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
+\newcommand\AtBeginOfIncludeFile [2]
+ {\AddToHook{include/before/#1}{#2}}
+\newcommand\AtEndOfIncludeFile [2]
+ {\AddToHook{include/end/#1}{#2}}
+\newcommand\AfterIncludeFile [2]
+ {\AddToHook{include/after/#1}{#2}}
+% \end{macrocode}
+%
+% \begin{macrocode}
+%</filehook>
+% \end{macrocode}
+%
+%
+%
+%
+% \subsection{The \pkg{bidi} package first aid}
+%
+% The \pkg{bidi} package adds a lot of hooks in various places and
+% those added to \cs{document} and \cs{enddocument} are now no
+% longer necessary as the kernel already provides the right hooks
+% there.
+%
+% However, we aren't trying to change that but instead only make
+% sure that the existing patches still work by adding some first
+% aid after \pkg{biditools} has been loaded.
+%
+% If the package gets updated one can easily take that out simply
+% through
+%\begin{verbatim}
+% \RemoveFromHook{file/after/biditools.sty}[firstaid]
+%\end{verbatim}
+% This makes it easy to test new bidi code while the first aid code
+% is still in the kernel.
+%
+% \begin{macrocode}
+\AddToHook{file/after/biditools.sty}[firstaid]{%
+ \FirstAidNeededT{biditools}{sty}%
+ {2020/05/13 v2 Programming tools for bidi package}%
+ {
+% \end{macrocode}
+% \pkg{bidi} adds some code to the beginning of \cs{document} which
+% contains \cs{endgroup} and \cs{begingroup} which is no longer
+% correct.
+%
+% Patching \cs{document} using \cs{bidi@patchcmd} doesn't work so
+% we take the extra groups out by hand:
+% \begin{macrocode}
+ \def\firstaid@bidi@document@patch
+ \endgroup#1\begingroup#2\firstaid@bidi@document@patch
+ {\unexpanded{#1#2}}%
+ \edef\document{\expandafter\firstaid@bidi@document@patch\document
+ \firstaid@bidi@document@patch}%
+% \end{macrocode}
+% There are also some patches into \cs{enddocument}, some continue
+% to go in but one fails, so we add that now into the right place.
+% \begin{macrocode}
+ \AddToHook{enddocument/info}%
+ {\let\bidi@AfterEndDocumentCheckLabelsRerun\@firstofone
+ \bidi@afterenddocumentchecklabelsrerunhook}%
+ }
+}
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<*kernel>
+% \end{macrocode}
+%
+%
+%
+% \subsection{The \pkg{dinbrief} class first aid}
+%
+% Again a case of a no longer correct \cs{endgroup} in document.
+% Here the fix is simply though.
+% \begin{macrocode}
+\AddToHook{file/after/dinbrief.cls}[firstaid]{%
+ \FirstAidNeededT{dinbrief}{cls}{2000/03/02 LaTeX2e class}%
+ {\AddToHook{env/document/begin}{\begingroup}}%
+}
+% \end{macrocode}
+%
+%
+%
+%
+%
+% \begin{macrocode}
+%</kernel>
+% \end{macrocode}
+%
+% \Finale
+%