diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/base/ltfilehook.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/base/ltfilehook.dtx | 164 |
1 files changed, 97 insertions, 67 deletions
diff --git a/Master/texmf-dist/source/latex/base/ltfilehook.dtx b/Master/texmf-dist/source/latex/base/ltfilehook.dtx index 5d0acc8fdfb..000f4d8c2a2 100644 --- a/Master/texmf-dist/source/latex/base/ltfilehook.dtx +++ b/Master/texmf-dist/source/latex/base/ltfilehook.dtx @@ -31,8 +31,8 @@ %%% From File: ltfilehook.dtx % % \begin{macrocode} -\providecommand\ltfilehookversion{v1.0k} -\providecommand\ltfilehookdate{2021/05/25} +\providecommand\ltfilehookversion{v1.0l} +\providecommand\ltfilehookdate{2021/08/27} % \end{macrocode} % %<*driver> @@ -48,7 +48,7 @@ \vbox_unpack_drop:N \l__codedoc_macro_box \hbox { \llap { \__codedoc_print_macroname:nN {#1} #2 \MacroFont % <----- without it the \ is in lmr10 if a link is made - \ + \ } } } \int_incr:N \l__codedoc_macro_int @@ -115,12 +115,12 @@ % \cs{usepackage}, etc. They are not called for files read using % internal low-level methods, such as \cs{@input} or \cs{openin}. % -% \begin{variable}{file/before,file/before/..., -% file/after/...,file/after, +% \begin{variable}{file/before,file/.../before, +% file/.../after,file/after, % } % These are: % \begin{description} -% \item[\texttt{file/before}, \texttt{file/before/\meta{file-name}}] +% \item[\texttt{file/before}, \texttt{file/\meta{file-name}/before}] % % These hooks are executed in that order just before the file is % loaded for reading. The code of the first hook is used @@ -128,7 +128,7 @@ % file with matching \meta{file-name} allowing you to specify % code that only applies to one file. % -% \item[\texttt{file/after/\meta{file-name}}, \texttt{file/after}] +% \item[\texttt{file/\meta{file-name}/after}, \texttt{file/after}] % % These hooks are after the file with name \meta{file-name} has % been fully consumed. The order is swapped (the specific one @@ -149,9 +149,9 @@ % \begin{tabbing} % mm\=mm\=mm\=mm\=\kill % \>\cs{UseHook}\marg{\hook{file/before}} \\ -% \>\cs{UseHook}\marg{\hook{file/before/\meta{file name}}} \\ +% \>\cs{UseHook}\marg{\hook{file/\meta{file name}/before}} \\ % \>\> \meta{file contents} \\ -% \>\cs{UseHook}\marg{\hook{file/after/\meta{file name}}} \\ +% \>\cs{UseHook}\marg{\hook{file/\meta{file name}/after}} \\ % \>\cs{UseHook}\marg{\hook{file/after}} % \end{tabbing} % @@ -172,8 +172,8 @@ % % When a file is input, the \meta{file name} is available in % \cs{CurrentFile}, which is then used when accessing the -% \hook{file/before/\meta{file name}} and -% \hook{file/after/\meta{file name}}. +% \hook{file/\meta{file name}/before} and +% \hook{file/\meta{file name}/after}. % % \begin{variable}{\CurrentFile} % The name of the file about to be read (or just finished) is @@ -216,7 +216,7 @@ % \cs{RequirePackage}, \cs{LoadPackageWithOptions}, etc.) offer the % hooks from section~\ref{sec:general-file-hooks} when they are % used to load a package or class file, e.g., -% \texttt{file/after/array.sty} would be called after the +% \texttt{file/array.sty/after} would be called after the % \pkg{array} package got loaded. But as packages and classes form as special group % of files, there are some additional hooks available that only % apply when a package or class is loaded. @@ -224,9 +224,9 @@ % % \begin{variable}{ % package/before,package/after, -% package/before/...,package/after/..., +% package/.../before,package/.../after, % class/before,class/after, -% class/before/...,class/after/..., +% class/.../before,class/.../after, % } % These are: % \begin{description} @@ -234,8 +234,8 @@ % % These hooks are called for each package being loaded. % -% \item[\texttt{package/before/\meta{name}}, -% \texttt{package/after/\meta{name}}] +% \item[\texttt{package/\meta{name}/before}, +% \texttt{package/\meta{name}/after}] % % These hooks are additionally called if the package name is % \meta{name} (without extension). @@ -244,7 +244,7 @@ % % These hooks are called for each class being loaded. % -% \item[\texttt{class/before/\meta{name}}, \texttt{class/after/\meta{name}}] +% \item[\texttt{class/\meta{name}/before}, \texttt{class/\meta{name}/after}] % % These hooks are additionally called if the class name is % \meta{name} (without extension). @@ -258,16 +258,16 @@ % \begin{tabbing} % mm\=mm\=mm\=mm\=\kill % \>\cs{UseHook}\marg{\hook{package/before}} \\ -% \>\cs{UseHook}\marg{\hook{package/before/\meta{package name}}} \\[5pt] +% \>\cs{UseHook}\marg{\hook{package/\meta{package name}/before}} \\[5pt] % \>\>\cs{UseHook}\marg{\hook{file/before}} \\ -% \>\>\cs{UseHook}\marg{\hook{file/before/\meta{package name}.sty}} \\ +% \>\>\cs{UseHook}\marg{\hook{file/\meta{package name}.sty/before}} \\ % \>\>\> \meta{package contents} \\ -% \>\>\cs{UseHook}\marg{\hook{file/after/\meta{package name}.sty}} \\ +% \>\>\cs{UseHook}\marg{\hook{file/\meta{package name}.sty/after}} \\ % \>\>\cs{UseHook}\marg{\hook{file/after}} \\[5pt] % \>\>\emph{code from \cs{AtEndOfPackage} if % used inside the package} \\[5pt] -% \>\cs{UseHook}\marg{\hook{package/after/\meta{package name}}} \\ -% \>\cs{UseHook}\marg{\hook{package/after}} +% \>\cs{UseHook}\marg{\hook{package/\meta{package name}/after}} \\ +% \>\cs{UseHook}\marg{\hook{package/after}} % \end{tabbing} % and similar for class file loading, except that \texttt{package/} % is replaced by \texttt{class/} and \cs{AtEndOfPackage} by @@ -276,6 +276,20 @@ % If a package or class is not loaded (or it was loaded before the % hooks were set) none of the hooks are executed! % +% All class or package hooks involving the name of the class or +% package are implemented as +% one-time hooks, whereas all other such hooks are normal hooks. +% This allows for the following use case +%\begin{verbatim} +% \AddToHook{package/varioref/after} +% { ... apply my customizations if the package gets +% loaded (or was loaded already) ... } +%\end{verbatim} +% without the need to first test if the package is already loaded. +% +% +% +% % \subsection{Hooks for \cs{include} files} % % To manage \cs{include} files, \LaTeX{} issues a \cs{clearpage} @@ -300,14 +314,14 @@ % is \enquote{\texttt{No file \meta{filename}.tex}}). % % -% \begin{variable}{include/before,include/before/..., -% include/end,include/end/..., -% include/after,include/after/..., +% \begin{variable}{include/before,include/.../before, +% include/end,include/.../end, +% include/after,include/.../after, % } % These are: % \begin{description} % -% \item[\texttt{include/before}, \texttt{include/before/\meta{name}}] +% \item[\texttt{include/before}, \texttt{include/\meta{name}/before}] % % These hooks are executed (in that order) after the initial % \cs{clearpage} and after \texttt{.aux} file is changed to use @@ -317,14 +331,14 @@ % file. % % -% \item[\texttt{include/end/\meta{name}}, \texttt{include/end}] +% \item[\texttt{include/\meta{name}/end}, \texttt{include/end}] % % These hooks are executed (in that order) after \LaTeX{} has % stopped reading from the \cs{include} file, but before it has % issued a \cs{clearpage} to output any deferred floats. % % -% \item[\texttt{include/after/\meta{name}}, \texttt{include/after}] +% \item[\texttt{include/\meta{name}/after}, \texttt{include/after}] % % These hooks are executed (in that order) after \LaTeX{} has % issued the \cs{clearpage} but before is has switched back @@ -341,6 +355,13 @@ % normally does nothing, but starts a new page if further material % got added this way.} % +% +% All \hook{include} hooks involving the name of the included file are implemented as +% one-time hooks (whereas all other such hooks are normal hooks). +% +% +% +% % \subsection{High-level interfaces for \LaTeX{}} % % We do not provide any additional wrappers around the hooks (like @@ -531,7 +552,7 @@ % 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. -% +% % \begin{macrocode} \cs_new:Npn \@@_file_parse_full_name:nN #1 { @@ -591,6 +612,7 @@ % \changes{v1.0h}{2021/03/18} % {Define \cs{g_@@_input_file_seq} to avoid losing data when % rolling back.} +% \changes{v1.0l}{2021/08/27}{Internal message name changes} % \begin{macrocode} \tl_new:N \l_@@_internal_tl \seq_if_exist:NF \g_@@_input_file_seq @@ -608,7 +630,7 @@ \seq_gpop:NNTF \g_@@_input_file_seq \l_@@_internal_tl { \exp_after:wN \@@_file_pop_assign:nnnn \l_@@_internal_tl } { - \msg_error:nnn { kernel } { should-not-happen } + \msg_error:nnn { latex2e } { should-not-happen } { Tried~to~pop~from~an~empty~file~name~stack. } } } @@ -624,7 +646,7 @@ % \end{macro} % \end{macro} % \end{macro} -% +% % \begin{macrocode} %</2ekernel|latexrelease> %<latexrelease>\EndIncludeInRelease @@ -683,7 +705,7 @@ %<latexrelease> { \use_none:n #1 \prg_do_nothing: } %<latexrelease> {#2} %<latexrelease> } -%<latexrelease>} +%<latexrelease>} %<latexrelease>\ExplSyntaxOff %<latexrelease> %<latexrelease>\EndIncludeInRelease @@ -697,16 +719,17 @@ % % \subsection{Declaring the file-related hooks} % -% All hooks starting with \texttt{file/} \texttt{include/}, -% \texttt{class/} or \texttt{package/} are generic and will be -% allocated if code is added to them. Thus there is no need to -% explicitly declare any hook in the code below. -% -% Furthermore, those named \texttt{.../after} or \texttt{.../end} are -% automatically declared as reversed hooks if filled with code, so this -% is also automatically taken care of. -% +% These hooks have names with three-parts that +% start with \hook{file/}, \hook{include/}, +% \hook{class/} or \hook{package/} and end with \hook{/before} or +% \hook{/after} (or \hook{/end} in the case of \hook{include/}). +% They are all generic hooks +% so will be declared only if code is added to them; +% this declaration is done for you automatically and, indeed, they should +% not be declared explicitly. % +% Those named \hook{.../after} and \texttt{include/.../end} +% are, when code is added, declared as reversed hooks. % % % \subsection{Patching \LaTeX{}'s \cs{InputIfFileExists} command} @@ -760,7 +783,7 @@ % can't rely on that still being true after the file has been % processed. Thus for using the name in the file hooks we need to % preserve the name and then restore it for the -% \texttt{file/after/...} hook. +% \texttt{file/.../after} hook. % % The hook always refers to the file requested by the user. The hook % is \emph{always} loaded for \cs{CurrentFile} which usually is the @@ -814,20 +837,27 @@ % The current file name is available in \cs{CurrentFile} so we use % that in the specific hook. % \begin{macrocode} - \UseHook{file/before/\CurrentFile}% + \UseHook{file/\CurrentFile/before}% \@@input #1% <- trailing space comes from \@filef@und }% % \end{macrocode} % And here, \cs{CurrentFile} is restored % (by \cs{@expl@@@filehook@file@pop@assign@@nnnn}) so we can use it once more. % \begin{macrocode} - \UseHook{file/after/\CurrentFile}% + \UseHook{file/\CurrentFile/after}% \UseHook{file/after}} \def\unqu@tefilef@und"#1" \@nil{#1} +% \end{macrocode} +% +% \changes{v1.0l}{2021/08/25}{Declare non-generic file hooks} +% Now declare the non-generic file hooks used above: +% \begin{macrocode} +\NewHook{file/before} +\NewReversedHook{file/after} %<latexrelease>\EndIncludeInRelease %</2ekernel|latexrelease> % \end{macrocode} -% +% % \changes{v0.9b} % {1993/12/04}{Macro added} % \changes{v0.9p} @@ -949,7 +979,7 @@ { \if_meaning:w #1 #2 .tex \else: \token_to_str:N #2 \fi: } % \end{macrocode} % \end{macro} -% +% % \begin{macro}[int]{\use_ii_iii:nnn} % A variant of \cs[no-index]{use_...} to discard the first of three % arguments. @@ -1085,7 +1115,7 @@ %</2ekernel|latexrelease> %<latexrelease>\EndIncludeInRelease % \end{macrocode} -% +% % \begin{macrocode} %<latexrelease>\IncludeInRelease{2020/10/01}% %<latexrelease> {\set@curr@file}{Setting current file name}% @@ -1108,7 +1138,7 @@ %<latexrelease> \endgroup} %<latexrelease>\EndIncludeInRelease % \end{macrocode} -% +% % \begin{macrocode} %<latexrelease>\IncludeInRelease{2019/10/01}% %<latexrelease> {\set@curr@file}{Setting current file name}% @@ -1124,7 +1154,7 @@ %<latexrelease>} %<latexrelease>\EndIncludeInRelease % \end{macrocode} -% +% % \begin{macrocode} %<latexrelease>\IncludeInRelease{0000/00/00}% %<latexrelease> {\set@curr@file}{Setting current file name}% @@ -1383,6 +1413,7 @@ % \@@_file_subst_cycle_error:NN, % \@@_file_subst_cycle_error:cN, % } +% \changes{v1.0l}{2021/08/27}{Use \cs{msg_...} not \cs{__kernel_msg_...}} % Showing this type of error expandably is tricky, as we have a very % limited amount of characters to show and a potentially large list. % As a work around, several errors are printed, each showing one step @@ -1390,7 +1421,7 @@ % \begin{macrocode} \cs_new:Npn \@@_file_subst_cycle_error:NN #1 #2 { - \__kernel_msg_expandable_error:nnff { kernel } { file-cycle } + \msg_expandable_error:nnff { latex2e } { file-cycle } {#1} { \use:c { @file-subst@ #1 } } \token_if_eq_meaning:NNF #1 #2 { \@@_file_subst_cycle_error:cN { @file-subst@ #1 } #2 } @@ -1400,7 +1431,7 @@ % % And the error message: % \begin{macrocode} -\__kernel_msg_new:nnn { kernel } { file-cycle } +\msg_new:nnn { latex2e } { file-cycle } { File~loop!~#1~replaced~by~#2... } % \end{macrocode} % \end{macro} @@ -1412,7 +1443,7 @@ %<latexrelease>\EndIncludeInRelease %<*2ekernel> % \end{macrocode} -% +% % % \begin{macrocode} %<@@=> @@ -1438,7 +1469,7 @@ \def\disable@package@load#1#2{% \global\@namedef{@pkg-disable@#1.\@pkgextension}{#2}} % \end{macrocode} -% +% % \begin{macrocode} \def\@disable@packageload@do#1#2{% \@ifundefined{@pkg-disable@#1}{#2}% @@ -1453,7 +1484,7 @@ \csname @pkg-disable@#1.\@pkgextension \endcsname \@undefined} % \end{macrocode} % -% +% % \begin{macrocode} %</2ekernel|latexrelease> %<latexrelease>\EndIncludeInRelease @@ -1502,7 +1533,7 @@ %<latexrelease> {\@expl@@@filehook@if@no@extension@@nTF}{2e tmp interfaces}% \ExplSyntaxOn % \end{macrocode} -% +% % \begin{macrocode} \cs_new_eq:NN \@expl@@@filehook@if@no@extension@@nTF \__filehook_if_no_extension:nTF @@ -1512,7 +1543,7 @@ \cs_new_eq:NN \@expl@@@filehook@set@curr@file@@nNN \__filehook_set_curr_file:nNN % \end{macrocode} -% +% % \begin{macrocode} \cs_new_eq:NN \@expl@@@filehook@resolve@file@subst@@w \__filehook_resolve_file_subst:w @@ -1522,7 +1553,7 @@ \cs_new_eq:NN \@expl@@@filehook@normalize@file@name@@w \__filehook_normalize_file_name:w % \end{macrocode} -% +% % \begin{macrocode} \cs_new_eq:NN \@expl@@@filehook@if@file@replaced@@TF \__filehook_if_file_replaced:TF @@ -1537,23 +1568,23 @@ \cs_new_eq:NN \@expl@@@filehook@drop@extension@@N \__filehook_drop_extension:N % \end{macrocode} -% +% % \begin{macrocode} \cs_new_eq:NN \@expl@@@filehook@file@push@@ \__filehook_file_push: % \end{macrocode} -% +% % \begin{macrocode} \cs_new_eq:NN \@expl@@@filehook@file@pop@@ \__filehook_file_pop: % \end{macrocode} -% +% % \begin{macrocode} \cs_new_eq:NN \@expl@@@filehook@file@pop@assign@@nnnn \__filehook_file_pop_assign:nnnn % \end{macrocode} % \InternalDetectionOn -% +% % % \begin{macrocode} \ExplSyntaxOff @@ -1682,7 +1713,7 @@ %<*atveryend-ltx> \ProvidesPackage{atveryend-ltx} [2020/08/19 v1.0a - Emulation of the original atvery package^^Jwith kernel methods] + Emulation of the original atveryend package^^Jwith kernel methods] % \end{macrocode} % % @@ -1698,14 +1729,14 @@ % \begin{macrocode} \newcommand\AtEndAfterFileList{\AddToHook{enddocument/info}} % \end{macrocode} -% +% % \begin{macrocode} \newcommand\AtVeryVeryEnd {\AddToHook{enddocument/end}} % \end{macrocode} % % \begin{macro}{\BeforeClearDocument} % This one is the only one we don't implement or rather don't have -% a dedicated hook in the code. +% a dedicated hook in the code. % \begin{macrocode} \ExplSyntaxOn \newcommand\BeforeClearDocument[1] @@ -1713,7 +1744,7 @@ \atveryend@DEPRECATED{BeforeClearDocument \tl_to_str:n{#1}} } % \end{macrocode} -% +% % \begin{macrocode} \cs_new:Npn\atveryend@DEPRECATED #1 {\iow_term:x{======~DEPRECATED~USAGE~#1~==========}} @@ -1721,7 +1752,7 @@ % \end{macrocode} % \end{macro} % -% +% % \begin{macrocode} %</atveryend-ltx> % \end{macrocode} @@ -1735,4 +1766,3 @@ \endinput %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % - |