summaryrefslogtreecommitdiff
path: root/macros/latex/base/ltfilehook.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/base/ltfilehook.dtx')
-rw-r--r--macros/latex/base/ltfilehook.dtx133
1 files changed, 100 insertions, 33 deletions
diff --git a/macros/latex/base/ltfilehook.dtx b/macros/latex/base/ltfilehook.dtx
index b4f716748a..5d0acc8fdf 100644
--- a/macros/latex/base/ltfilehook.dtx
+++ b/macros/latex/base/ltfilehook.dtx
@@ -1,7 +1,7 @@
% \iffalse meta-comment
-%%
-%% File: ltfilehook.dtx (C) Copyright 2020 Frank Mittelbach,
-%% Phelype Oleinik & LaTeX Team
+%
+% Copyright (C) 2020-2021
+% Frank Mittelbach, Phelype Oleinik & LaTeX Team
%
% This file is part of the LaTeX base system.
% -------------------------------------------
@@ -31,8 +31,8 @@
%%% From File: ltfilehook.dtx
%
% \begin{macrocode}
-\providecommand\ltfilehookversion{v1.0e}
-\providecommand\ltfilehookdate{2021/01/07}
+\providecommand\ltfilehookversion{v1.0k}
+\providecommand\ltfilehookdate{2021/05/25}
% \end{macrocode}
%
%<*driver>
@@ -55,6 +55,10 @@
}
\ExplSyntaxOff
+\providecommand\InternalDetectionOff{}
+\providecommand\InternalDetectionOn{}
+
+
\usepackage{structuredlog} % for demonstration
\EnableCrossrefs
@@ -75,7 +79,7 @@
% \ltfilehookversion\ dated \ltfilehookdate, \copyright\ \LaTeX\
% Project.}}
%
-% \author{Frank Mittelbach}
+% \author{Frank Mittelbach, Phelype Oleinik, \LaTeX{} Project Team}
%
% \maketitle
%
@@ -339,9 +343,12 @@
%
% \subsection{High-level interfaces for \LaTeX{}}
%
-% We do not provide any high-level \LaTeX{} commands (like
-% \pkg{filehook} or \pkg{scrlfile} do) but think that for package
-% writers the commands from for hook management are sufficient.
+% We do not provide any additional wrappers around the hooks (like
+% \pkg{filehook} or \pkg{scrlfile} do) because we believe that for
+% package writers the high-level commands from the hook management,
+% e.g., \cs{AddToHook}, etc.\
+% are sufficient and in fact easier to work with, given that the hooks
+% have consistent naming conventions.
%
%
%
@@ -371,7 +378,7 @@
% \em
% Please do not misuse this functionality and replace a file with
% another unless if really needed and only if the new version is
-% implementating the same functionality as the original one!
+% implementing the same functionality as the original one!
% \end{quote}
% \end{function}
%
@@ -447,6 +454,7 @@
%
%
% \section{The Implementation}
+%
% \begin{macrocode}
%<*2ekernel>
% \end{macrocode}
@@ -455,6 +463,8 @@
%<@@=filehook>
% \end{macrocode}
%
+% \changes{v1.0k}{2021/05/24}{Use \cs{msg_...} instead of \cs{__kernel_msg...}}
+%
%
% \subsection{Document and package-level commands}
%
@@ -517,7 +527,7 @@
% }
% A utility macro to trigger \pkg{expl3}'s file-parsing and lookup,
% and return a normalized representation of the file name. If the
-% queried file doesn't exist, no normalisation takes place.
+% queried file doesn't exist, no normalization takes place.
% The output of \cs{@@_file_parse_full_name:nN} is passed on to the
% |#2|---a 3-argument macro that takes the \meta{path}, \meta{base},
% and \meta{ext} parts of the file name.
@@ -578,9 +588,13 @@
% places don't use \cs{InputIfFileExists} directly (\cs{include}) or
% need \cs{CurrentFile} earlier (\cs{@onefilewithoptions}), so these
% are manually used elsewhere as well.
+% \changes{v1.0h}{2021/03/18}
+% {Define \cs{g_@@_input_file_seq} to avoid losing data when
+% rolling back.}
% \begin{macrocode}
\tl_new:N \l_@@_internal_tl
-\seq_new:N \g_@@_input_file_seq
+\seq_if_exist:NF \g_@@_input_file_seq
+ { \seq_new:N \g_@@_input_file_seq }
\cs_new_protected:Npn \@@_file_push:
{
\seq_gpush:Nx \g_@@_input_file_seq
@@ -594,7 +608,7 @@
\seq_gpop:NNTF \g_@@_input_file_seq \l_@@_internal_tl
{ \exp_after:wN \@@_file_pop_assign:nnnn \l_@@_internal_tl }
{
- \msg_error:nnn { hooks } { should-not-happen }
+ \msg_error:nnn { kernel } { should-not-happen }
{ Tried~to~pop~from~an~empty~file~name~stack. }
}
}
@@ -619,6 +633,7 @@
% When rolling forward the following expl3 functions may not be defined.
% If we roll back the code does nothing.
% \changes{v1.0d}{2020/11/24}{Support for roll forward (gh/434)}
+% \InternalDetectionOff
% \begin{macrocode}
%<latexrelease>\IncludeInRelease{2020/10/01}%
%<latexrelease> {\file_parse_full_name_apply:nN}{Roll forward help}%
@@ -640,7 +655,8 @@
%<latexrelease> {
%<latexrelease> \tl_if_empty:nTF {#3}
%<latexrelease> { \__file_parse_full_name_base:nw { } #2 . \s__file_stop {#1} }
-%<latexrelease> { \__file_parse_full_name_area:nw { #1 / #2 } #3 \s__file_stop }
+%<latexrelease> { \__file_parse_full_name_area:nw { #1 / #2 }
+%<latexrelease> #3 \s__file_stop }
%<latexrelease> }
%<latexrelease>\cs_new:Npn \__file_parse_full_name_base:nw #1 #2 . #3 \s__file_stop
%<latexrelease> {
@@ -654,7 +670,8 @@
%<latexrelease> }
%<latexrelease> { \__file_parse_full_name_tidy:nnnN {#1} { .#2 } }
%<latexrelease> }
-%<latexrelease> { \__file_parse_full_name_base:nw { #1 . #2 } #3 \s__file_stop }
+%<latexrelease> { \__file_parse_full_name_base:nw { #1 . #2 }
+%<latexrelease> #3 \s__file_stop }
%<latexrelease> }
%<latexrelease>\cs_new:Npn \__file_parse_full_name_tidy:nnnN #1 #2 #3 #4
%<latexrelease> {
@@ -672,6 +689,7 @@
%<latexrelease>\EndIncludeInRelease
%<*2ekernel>
% \end{macrocode}
+% \InternalDetectionOn
%
% \begin{macrocode}
%<@@=>
@@ -844,6 +862,17 @@
%<latexrelease>\long\def \InputIfFileExists#1#2{%
%<latexrelease> \IfFileExists{#1}%
%<latexrelease> {#2\@addtofilelist{#1}\@@input \@filef@und}}
+% \end{macrocode}
+%
+% Also undo the internal command as some packages unfortunately test
+% for their existence instead of using \cs{IfFormatAtLeastTF}.
+% \changes{v1.0g}{2021/02/08}{Undo the internal for robust
+% \cs{InputIfFileExists} in rollback (gh/494)}
+% \begin{macrocode}
+%<latexrelease>\expandafter\let\csname InputIfFileExists \endcsname\@undefined
+% \end{macrocode}
+%
+% \begin{macrocode}
%<latexrelease>\let\@input@file@exists@with@hooks\@undefined
%<latexrelease>\let\unqu@tefilef@und\@undefined
%<latexrelease>\EndIncludeInRelease
@@ -894,7 +923,8 @@
@file-subst@
\@@_subst_file_normalize:Nn \use_ii_iii:nnn {#1}
}
- { \@@_subst_file_normalize:Nn \@@_file_name_compose:nnn {#2} }
+ { \@@_subst_file_normalize:Nn \@@_file_name_compose:nnn
+ {#2} }
\group_end:
}
\cs_new_protected:Npn \@@_subst_remove:n #1
@@ -957,12 +987,18 @@
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
%
+% We are not fully rolling back the file substitutions in case a
+% rollback encounters a package that contains them, but is itself
+% not setup for rollback. So we just bypass them and hope for the
+% best.
+% \changes{v1.0d}{2020/12/04}{Don't drop file substitution commands on
+% rollback}
% \begin{macrocode}
%<latexrelease>\IncludeInRelease{0000/00/00}%
%<latexrelease> {\declare@file@substitution}{File substitution}%
%<latexrelease>
-%<latexrelease>\let \declare@file@substitution \@undefined
-%<latexrelease>\let \undeclare@file@substitution \@undefined
+%<latexrelease>\let \declare@file@substitution \@gobbletwo
+%<latexrelease>\let \undeclare@file@substitution \@gobble
%<latexrelease>
%<latexrelease>\EndIncludeInRelease
%<*2ekernel>
@@ -981,6 +1017,7 @@
% \subsection{Selecting a file (\cs{set@curr@file})}
%
% \begin{macro}{\set@curr@file,\@curr@file,\@curr@file@reqd}
+% \changes{v1.0f}{2021/01/31}{set \cs{protect} to \cs{string} gh/481}
% Now we hook into \cs{set@curr@file} to resolve a possible file
% substitution, and add \cs{@expl@@@filehook@set@curr@file@@nNN}
% at the end, after \cs{@curr@file} is set.
@@ -988,7 +1025,7 @@
% A file name is built using
% \cs{expandafter}\cs{string}\cs{csname}\meta{filename}\cs{endcsname}
% to avoid expanding utf8 active characters. The \cs{csname} expands
-% the normalisation machinery and the routine to resolve a file
+% the normalization machinery and the routine to resolve a file
% substitution, returning a control sequence with the same name as the
% file.
%
@@ -1001,14 +1038,18 @@
% false positives. Here we define \cs{csname\cs{endcsname}} to
% expand to itself to avoid it matching the definition of some other
% control sequence.
+% \changes{v1.0i}{2021/04/20}
+% {Make \string~ expand to a string (tracks change in l3kernel)}
% \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
-%<latexrelease>\IncludeInRelease{2020/10/01}%
+%<latexrelease>\IncludeInRelease{2021/06/01}%
%<latexrelease> {\set@curr@file}{Setting current file name}%
\def\set@curr@file#1{%
\begingroup
\escapechar\m@ne
+ \let\protect\string
+ \edef~{\string~}%
\expandafter\def\csname\expandafter\endcsname
\expandafter{\csname\endcsname}%
% \end{macrocode}
@@ -1018,7 +1059,7 @@
% actual loaded file. \cs{@curr@file} is resolved first, to check if
% a substitution happens. If it doesn't,
% \cs{@expl@@@filehook@if@file@replaced@@TF} short-cuts and just copies
-% \cs{@curr@file}, otherwise the full normalisation procedure is
+% \cs{@curr@file}, otherwise the full normalization procedure is
% executed.
%
% At this stage the file name is parsed and normalized, but if the
@@ -1046,6 +1087,29 @@
% \end{macrocode}
%
% \begin{macrocode}
+%<latexrelease>\IncludeInRelease{2020/10/01}%
+%<latexrelease> {\set@curr@file}{Setting current file name}%
+%<latexrelease>\def\set@curr@file#1{%
+%<latexrelease> \begingroup
+%<latexrelease> \escapechar\m@ne
+%<latexrelease> \expandafter\def\csname\expandafter\endcsname
+%<latexrelease> \expandafter{\csname\endcsname}%
+%<latexrelease> \@expl@@@filehook@if@no@extension@@nTF{#1}%
+%<latexrelease> {\@tempswatrue}{\@tempswafalse}%
+%<latexrelease> \@kernel@make@file@csname\@curr@file
+%<latexrelease> \@expl@@@filehook@resolve@file@subst@@w {#1}%
+%<latexrelease> \@expl@@@filehook@if@file@replaced@@TF
+%<latexrelease> {\@kernel@make@file@csname\@curr@file@reqd
+%<latexrelease> \@expl@@@filehook@normalize@file@name@@w{#1}%
+%<latexrelease> \if@tempswa \@expl@@@filehook@drop@extension@@N\@curr@file@reqd \fi}%
+%<latexrelease> {\if@tempswa \@expl@@@filehook@drop@extension@@N\@curr@file \fi
+%<latexrelease> \global\let\@curr@file@reqd\@curr@file}%
+%<latexrelease> \@expl@@@filehook@clear@replacement@flag@@
+%<latexrelease> \endgroup}
+%<latexrelease>\EndIncludeInRelease
+% \end{macrocode}
+%
+% \begin{macrocode}
%<latexrelease>\IncludeInRelease{2019/10/01}%
%<latexrelease> {\set@curr@file}{Setting current file name}%
%<latexrelease>\def\set@curr@file#1{%
@@ -1097,7 +1161,8 @@
\expandafter\ifx\csname\endcsname#1%
.tex\else\string#1\fi}
% \end{macrocode}
-%
+%
+% \begin{sloppypar}
% Then we call \cs{@expl@@@filehook@set@curr@file@@nNN} once for
% \cs{@curr@file} to set \cs[no-index]{CurrentFile(Path)Used} and once for
% \cs{@curr@file@reqd} to set \cs[no-index]{CurrentFile(Path)}.
@@ -1107,6 +1172,7 @@
% \cs{@curr@file} and \cs{@curr@file@reqd} differ. This macro is
% issued separate from \cs{set@curr@file} because it changes
% \cs{CurrentFile}, and side-effects would quickly get out of control.
+% \end{sloppypar}
% \begin{macrocode}
\def\@filehook@set@CurrentFile{%
\@expl@@@filehook@set@curr@file@@nNN{\@curr@file}%
@@ -1170,13 +1236,13 @@
% \begin{macro}{\@@_resolve_file_subst:w}
% \begin{macro}{\@@_normalize_file_name:w}
% \begin{macro}{\@@_file_name_compose:nnn}
-% Start by sanitising the file with \cs{@@_file_parse_full_name:nN}
+% Start by sanitizing the file with \cs{@@_file_parse_full_name:nN}
% then do \cs{@@_file_subst_begin:nnn}\Arg{path}\Arg{name}\Arg{ext}.
% \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2020/10/01}%
-%<latexrelease> {\@@_resolve_file_subst:w}{Replace files detect loops}%
+%<latexrelease> {\@@_resolve_file_subst:w}{Replace files detect loops}%
\ExplSyntaxOn
\cs_new:Npn \@@_resolve_file_subst:w #1 \@nil
{ \@@_file_parse_full_name:nN {#1} \@@_file_subst_begin:nnn }
@@ -1195,7 +1261,7 @@
% a flag to remember if a substitution happened. We use this in
% \cs{set@curr@file} to short-circuit some of it in case no
% substitution happened (by far the most common case, so it's worth
-% optimising). The flag raised during the file substitution algorithm
+% optimizing). The flag raised during the file substitution algorithm
% must be explicitly cleared after the \cs{@@_if_file_replaced:TF}
% conditional is no longer needed, otherwise further uses of
% \cs{@@_if_file_replaced:TF} will wrongly return true.
@@ -1258,8 +1324,8 @@
% the macro below, \cs{@@_file_subst_loop:cc} is called with
% \cs[no-index]{@file-subst@\meta{file}} and
% \cs[no-index]{@file-subst@\cs[no-index]{@file-subst@\meta{file}}};
-% that is, the substitution of \meta{file} and the substution of that
-% substution: the Tortoise walks one step while the Hare walks two.
+% that is, the substitution of \meta{file} and the substitution of that
+% substitution: the Tortoise walks one step while the Hare walks two.
%
% Within \cs{@@_file_subst_loop:NN} the two substitutions are
% compared, and if they lead to the same file it means that there is
@@ -1275,7 +1341,7 @@
%</2ekernel>
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2020/10/01}%
-%<latexrelease> {\@@_file_subst_tortoise_hare:nn}{Tortoise and Hare}%
+%<latexrelease> {\@@_file_subst_tortoise_hare:nn}{Tortoise and Hare}%
\ExplSyntaxOn
\cs_new:Npn \@@_file_subst_tortoise_hare:nn #1 #2 #3
{
@@ -1428,7 +1494,7 @@
% \begin{macrocode}
%<@@=>
% \end{macrocode}
-%
+% \InternalDetectionOff
% \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
@@ -1474,7 +1540,7 @@
%
% \begin{macrocode}
\cs_new_eq:NN \@expl@@@filehook@file@push@@
- \__filehook_file_push:
+ \__filehook_file_push:
% \end{macrocode}
%
% \begin{macrocode}
@@ -1486,6 +1552,7 @@
\cs_new_eq:NN \@expl@@@filehook@file@pop@assign@@nnnn
\__filehook_file_pop_assign:nnnn
% \end{macrocode}
+% \InternalDetectionOn
%
%
% \begin{macrocode}
@@ -1545,7 +1612,7 @@
% \end{macro}
%
% \begin{macro}{\@@_log_file_record:n}
-% This macro is responsible for increasing and decresing the file
+% This macro is responsible for increasing and decreasing the file
% nesting level, as well as printing to the log. The argument is
% either |STOPTART| or |STOP| and the action it takes on the nesting
% integer depends on that.
@@ -1664,8 +1731,8 @@
% \Finale
%
%
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\endinput
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%