[latex3-commits] [git/LaTeX3-latex3-latex2e] copyedits-chris: Lthooks.dtx so far (a11b3c07)
Chris Rowley
car222222 at github.github.io
Sun Sep 12 11:31:35 CEST 2021
Repository : https://github.com/latex3/latex2e
On branch : copyedits-chris
Link : https://github.com/latex3/latex2e/commit/a11b3c07d59293e0a5a8602997c16c6dd03d27fe
>---------------------------------------------------------------
commit a11b3c07d59293e0a5a8602997c16c6dd03d27fe
Author: Chris Rowley <car222222 at users.noreply.github.com>
Date: Sun Sep 12 16:31:35 2021 +0700
Lthooks.dtx so far
This one is never ending!
>---------------------------------------------------------------
a11b3c07d59293e0a5a8602997c16c6dd03d27fe
base/lthooks.dtx | 285 ++++++++++++++++++++++++++++---------------------------
1 file changed, 144 insertions(+), 141 deletions(-)
diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 2b74663e..708d2012 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -128,8 +128,8 @@
% \subsubsection{Declaring hooks}
%
% With a few exceptions, hooks have to be declared before they can
-% be used. The exceptions are the generic hooks for commands,
-% environments (i.e., executed at \cs{begin} and \cs{end}) and
+% be used. The exceptions are the generic hooks for commands and
+% environments (executed at \cs{begin} and \cs{end}), and the
% hooks run when loading files (see section~\ref{sec:generic}).
%
% \begin{function}{\NewHook}
@@ -137,8 +137,8 @@
% \cs{NewHook} \Arg{hook}
% \end{syntax}
% Creates a new \meta{hook}.
-% If this is a hook declared as part of a package it is suggested
-% that the \meta{hook} name is always structured as follows:
+% If this hook is declared within a package it is suggested
+% that its name is always structured as follows:
% \meta{package-name}\texttt{/}\meta{hook-name}. If necessary you
% can further subdivide the name by adding more \texttt{/} parts.
% If a hook name is already taken, an error is raised and the hook
@@ -210,7 +210,7 @@
% \end{syntax}
% This declaration activates a generic hook provided by a package/class
% (e.g., one used in code with \cs{UseHook} or
-% \cs{UseOneTimeHook} without it being explicitly declared with
+% \cs{UseOneTimeHook}) without it being explicitly declared with
% \cs{NewHook}).
% This command undoes the effect of \cs{DisableGenericHook}.
% If the hook is already activated, this command does nothing.
@@ -265,15 +265,15 @@
% section~\ref{sec:default-label} for details.
%
% Using \cs{UseOneTimeHook} several times with the same
-% \Arg{hook} means that it only executes the first time, for
-% example, if used in a command that can be called several times
-% then the hook executes only during the first invocation allowing
-% to use it as an \enquote{initialization} hook.
+% \Arg{hook} means that it only executes the first time it is used.
+% For example, if it is used in a command that can be called several times
+% then the hook executes during only the \emph{first} invocation of that
+% command; this allows its use as an \enquote{initialization hook}
%
% \fmiinline{Last statement is not yet implemented!}
%
% Mixing \cs{UseHook} and \cs{UseOneTimeHook} for the same
-% \Arg{hook} should be avoided, but if used then neither execute
+% \Arg{hook} should be avoided, but if this is done then neither will execute
% after the first \cs{UseOneTimeHook}.
%
% \end{function}
@@ -322,16 +322,16 @@
% If there is no code under the \meta{label} in the \meta{hook},
% or if the \meta{hook} does not exist, a warning is issued when
% you attempt to \cs{RemoveFromHook}, and the command is ignored.
-% \cs{RemoveFromHook} should be used when you know exactly what
-% labels are in a hook, usually some code is added to a hook, and
-% later removed by that same package
+% \cs{RemoveFromHook} should be used only when you know exactly what
+% labels are in a hook. Typically this will be when some code gets added to a hook
+% by a package, then later this code is removed by that same package.
% If you want to prevent the execution of code from another
% package, use the |voids| rule instead (see section~\ref{sec:rules}).
%
% If the optional \meta{label} argument is \texttt{*}, then all code chunks are
-% removed. This is rather dangerous as it drops code from other
-% packages one may not know about and should therefore not be used
-% by packages but only in document preambles!
+% removed. This is rather dangerous as it may well drop code from other
+% packages (that one may not know about); it should therefore not be used
+% in packages but only in document preambles!
%
% The \meta{hook} and \meta{label} can be specified using the
% dot-syntax to denote the current package name.
@@ -380,24 +380,28 @@
% The code is executed after the normal hook code has finished and
% it is executed only once, i.e. it is deleted after it was used.
%
-% Using the declaration is a global operation, i.e., the code is
-% not lost, even if the declaration is used inside a group and the
-% next invocation happens after the group. If the declaration is
+% Using this declaration is a global operation, i.e., the code is
+% not lost even if the declaration is used inside a group and the
+% next invocation of the hook happens after the end of that group.
+% If the declaration is
% used several times before the hook is executed then all code is
% executed in the order in which it was declared.\footnotemark
%
-% If this command is used with a one-time hook the code is only
-% ever used if we are before the hook execution, i.e., in contrast
-% to \cs{AddToHook} the code is not executed immediately if the
-% hook execution already happened---in other words it truly
-% executes on the next invocation, only there is none in case of a
-% one-time hook. This gives you a choice: should my code execute
-% always or should it execute only at the point where the
-% one-time hook is used and not at all if this is impossible? For
-% both there are use cases.
-%
-% It is possible to nest declarations using the same hook (or
-% different hooks), e.g.,
+% If this declaration is used with a one-time hook then the code
+% is only ever used if the declaration comes before the hook’s
+# invocation. This is because, in contrast
+% to \cs{AddToHook}, the code in this declaration is not
+% executed immediately in the case when the invocation of the hook
+% has already happened---in other words, this code will truly execute
+% only on the next invocation of the hook (and in the case of a
+% one-time hook there is no such \enquote{next invocation}).
+% This gives you a choice: should my code execute
+% always, or should it execute only at the point where the
+% one-time hook is used (and not at all if this is impossible)? For
+% both of these possibilities there are use cases.
+%
+% It is possible to nest this declaration using the same hook (or
+% different hooks): e.g.,
% \begin{quote}
% \cs{AddToHookNext}\Arg{hook}\verb={=\meta{code-1}^^A
% \cs{AddToHookNext}\Arg{hook}\Arg{code-2}\verb=}=
@@ -425,7 +429,7 @@
% Normally \cs{AddToHookNext} is only used when you know precisely
% where it will apply and why you want some extra code at that
% point. However, there are a few use cases in which such a
-% declaration needs to be canceled again, for example, when
+% declaration needs to be canceled, for example, when
% discarding a page with \cs{DiscardShipoutBox} (but even then not
% always), and in such situations \cs{ClearHookNext} can be
% used.
@@ -565,7 +569,7 @@
% Packages that provide their own package-like interfaces
% (Ti\textit{k}Z's \cs{usetikzlibrary}, for example) can use
% \cs{PushDefaultHookLabel} and \cs{PopDefaultHookLabel} to set
-% dedicated labels and emulate \cs{usepackage}-like hook behavior
+% dedicated labels and to emulate \cs{usepackage}-like hook behavior
% within those contexts.
%
% The |top-level| label is treated differently, and is reserved to the
@@ -745,7 +749,7 @@
% \item not exist (in which case emptiness doesn't apply);
% \end{itemize}
% Hooks are a bit more complicated:
-% a hook may exist or not, and either way it may or may not be empty.
+% a hook may exist or not, and independently it may or may not be empty.
% This means that even a hook that doesn't exist may be non-empty and
% it can also be disabled.
%
@@ -1048,7 +1052,7 @@
%
% If there is no code under the \meta{label} in the \meta{hook},
% or if the \meta{hook} does not exist, a warning is issued when
-% you attempt to \cs{hook_gremove_code:nn}, and the command is ignored.
+% you attempt to use \cs{hook_gremove_code:nn}, and the command is ignored.
%
% If the second argument is \texttt{*}, then all code chunks are
% removed. This is rather dangerous as it drops code from other
@@ -1354,35 +1358,36 @@
% where it is unreasonable to declare them beforehand, e.g, each
% and every command has (in theory) an associated \texttt{before}
% and \texttt{after} hook. In such cases, i.e., for command,
-% environment or file hooks, they can simply by used by adding code
+% environment or file hooks, they can be used simply by adding code
% to them with \cs{AddToHook}. For more specialized generic hooks,
% e.g., those provided by \pkg{babel}, you have to additionally
% enable them with \cs{ActivateGenericHook} as explained below.
%
-% The generic hooks provided by \LaTeX{}, i.e., for
+% The generic hooks provided by \LaTeX{} are those for
% \hook{cmd},
% \hook{env},
% \hook{file},
% \hook{include}
% \hook{package}, and
% \hook{class},
-% are available out of the box. You only have to use \cs{AddToHook} to
+% and all these are available out of the box: you only have to
+% use \cs{AddToHook} to
% add code to them, but you don't have to add \cs{UseHook} or
% \cs{UseOneTimeHook} to your code, because this is already done for
-% you (or, in case of \hook{cmd} hooks, the command is patched at
-% \verb=\begin{document}=, if necessary).
+% you (or, in the case of \hook{cmd} hooks, the command’s code is
+% patched at \verb=\begin{document}=, if necessary).
%
-% However, if you want to offer your own generic hooks in your
-% code, the situation is slightly different. You provide for such a
-% generic hook by using \cs{UseHook} or \cs{UseOneTimeHook}, but
+% However, if you want to provide further generic hooks in your own
+% code, the situation is slightly different. To do this you should
+% use \cs{UseHook} or \cs{UseOneTimeHook}, but
% \emph{without declaring the hook} with \cs{NewHook}. As
% mentioned earlier, a call to \cs{UseHook} with an undeclared hook
% name does nothing. So as an additional setup step, you need to
-% explicitly activate the generic hook. Note that a generic hook
+% explicitly activate your generic hook. Note that a generic hook
% produced in this way is always a normal hook.
%
% For a truly generic hook, with a variable part in the hook name,
-% an upfront activation would be difficult or impossible, because
+% such upfront activation would be difficult or impossible, because
% you typically do not know what kind of variable parts may come up
% in real documents.
%
@@ -1391,18 +1396,17 @@
% \pkg{babel} is often done through external language
% packages. Thus doing the activation for all languages inside the
% core \pkg{babel} code is not a viable approach. Instead it needs
-% to by done by such language packages (or by the user who wants to
+% to be done by each language package (or by the user who wants to
% use a particular hook).
%
% Because the hooks are not declared with \cs{NewHook} their names
% should be carefully chosen to ensure that they are (likely to be)
% unique. Best practice is to include the package or
-% command name as it was
-% done in the \pkg{babel} example.
+% command name, as was done in the \pkg{babel} example above.
%
% Generic hooks defined in this way are always normal hooks (i.e.,
% you can't implement reversed hooks this way). This is a
-% deliberate limitation, because it speeds up and the processessing
+% deliberate limitation, because it speeds up the processessing
% conciderably.
%
%
@@ -1452,7 +1456,7 @@
% add to them. They are listed here and are retained for backwards
% compatibility.
%
-% With the new hook management several additional hooks have been added
+% With the new hook management, several additional hooks have been added
% to \LaTeX\ and more will follow. See the next section for what
% is already available.
%
@@ -1522,42 +1526,43 @@
% \section{\LaTeXe{} commands and environments augmented by hooks}
%
% In this section we describe the standard hooks that are now
-% offered by \LaTeX{} or give pointers to other documents in which
-% they are described. This section is will grow over time (and
-% perhaps move to usrguide3 eventually.
+% offered by \LaTeX{}, or give pointers to other documents in which
+% they are described. This section will grow over time (and
+% perhaps eventually move to usrguide3).
%
% \subsection{Generic hooks}
% \label{sec:generic}
%
-% As stated earlier, all hooks have to be declared with \cs{NewHook}
-% before they can be used with the exception of generic hooks. All
-% generic hooks are named
+% As stated earlier, with the exception of generic hooks, all hooks must
+% be declared with \cs{NewHook} before they can be used.
+% All generic hooks have names of the form
% \enquote{\meta{type}/\meta{name}/\meta{position}}, where \meta{type}
-% is one in the predefined list shown below, \meta{name} is the variable
-% part, whose meaning will depend on the \meta{type}, and
-% \meta{position}, which can be |before| or |after|, and also |begin| or
-% |end| for |env| hooks, and |end| for |include| hooks. Each specific
-% hook is documented below or in \texttt{ltcmdhooks-doc.pdf} or
+% is from the predefined list shown below, and \meta{name} is the variable
+% part whose meaning will depend on the \meta{type}. The last component,
+% \meta{position}, has more complex possibilities:
+% it can always be |before| or |after|; for |env| hooks, it can also be |begin|
+% or |end|; and for |include| hooks it can also be |end|. Each specific
+% hook is documented below, or in \texttt{ltcmdhooks-doc.pdf} or
% \texttt{ltfilehook-doc.pdf}.
%
% The generic hooks provided by \LaTeX{} belong to one of the six types:
% \begin{description}
-% \item[env] Hooks executed before and after environments.
+% \item[env] Hooks executed before and after environments --
% \meta{name} is the name of the environment, and available values
% for \meta{position} are |before|, |begin|, |end|, and |after|;
-% \item[cmd] Hooks added to and executed before and after commands.
+% \item[cmd] Hooks added to and executed before and after commands --
% \meta{name} is the name of the command, and available values
% for \meta{position} are |before| and |after|;
-% \item[file] Hooks executed before and after reading a file;
+% \item[file] Hooks executed before and after reading a file --
% \meta{name} is the name of the file (with extension), and
% available values for \meta{position} are |before| and |after|;
-% \item[package] Hooks executed before and after packages;
+% \item[package] Hooks executed before and after loading packages --
% \meta{name} is the name of the package, and available values for
% \meta{position} are |before| and |after|;
-% \item[class] Hooks executed before and after classes;
+% \item[class] Hooks executed before and after loading classes --
% \meta{name} is the name of the class, and available values for
% \meta{position} are |before| and |after|;
-% \item[include] Hooks executed before and after \cs{include}d files;
+% \item[include] Hooks executed before and after \cs{include}d files --
% \meta{name} is the name of the included file (without the |.tex|
% extension), and available values for \meta{position} are |before|,
% |end|, and |after|.
@@ -1627,10 +1632,10 @@
% to add the outer hooks, etc.
%
%
-% Largely for compatibility with existing packages the following
-% four commands are also available to set the environments, but for
-% new packages we recommend to use the hooks names and
-% \cs{AddToHook} directly instead.
+% Largely for compatibility with existing packages, the following
+% four commands are also available to set the environment hooks; but for
+% new packages we recommend directly using the hook names and
+% \cs{AddToHook}.
%
%
% \begin{function}{\BeforeBeginEnvironment}
@@ -1646,21 +1651,21 @@
% \begin{syntax}
% \cs{AtBeginEnvironment} \oarg{label} \Arg{env} \Arg{code}
% \end{syntax}
-% Like \cs{BeforeBeginEnvironment} but adds to the \hook{env/\meta{env}/begin} hook.
+% This is like \cs{BeforeBeginEnvironment} but it adds to the \hook{env/\meta{env}/begin} hook.
% \end{function}
%
% \begin{function}{\AtEndEnvironment}
% \begin{syntax}
% \cs{AtEndEnvironment} \oarg{label} \Arg{env} \Arg{code}
% \end{syntax}
-% Like \cs{BeforeBeginEnvironment} but adds to the \hook{env/\meta{env}/end} hook.
+% This is like \cs{BeforeBeginEnvironment} but it adds to the \hook{env/\meta{env}/end} hook.
% \end{function}
%
% \begin{function}{\AfterEndEnvironment}
% \begin{syntax}
% \cs{AfterEndEnvironment} \oarg{label} \Arg{env} \Arg{code}
% \end{syntax}
-% Like \cs{BeforeBeginEnvironment} but adds to the \hook{env/\meta{env}/after} hook.
+% This is like \cs{BeforeBeginEnvironment} but it adds to the \hook{env/\meta{env}/after} hook.
% \end{function}
%
%
@@ -1876,7 +1881,7 @@
% \subsection{Hooks provided for paragraphs}
% \label{sec:para}
%
-% The paragraph processing has be augmented to include a number of
+% The paragraph processing has been augmented to include a number of
% internal and public hooks. These are documented in
% \texttt{ltpara-doc.pdf} or with code in
% \texttt{ltpara-code.pdf}.
@@ -1886,32 +1891,31 @@
% \subsection{Hooks provided in NFSS commands}
%
% In languages that need to support for more than one script in
-% parallel (and thus several sets of fonts), e.g., Latin and
-% Japanese fonts, NFSS font commands, such as \cs{sffamily}, need
+% parallel (and thus several sets of fonts, e.g., supporting both Latin and
+% Japanese fonts), NFSS font commands such as \cs{sffamily} need
% to switch both the Latin family to ``Sans Serif'' and in addition
% alter a second set of fonts.
%
-% To support this several NFSS have hooks in which such support can
-% be added.
+% To support this, several NFSS commands have hooks to which
+% such support can be added.
% \begin{description}
%
% \item[\hook{rmfamily}]
%
% After \cs{rmfamily} has done its initial checks and prepared a
-% any font series update this hook is executed and only
-% afterwards \cs{selectfont}.
+% font series update, this hook is executed before \cs{selectfont}.
%
% \item[\hook{sffamily}]
%
-% Like the \hook{rmfamily} hook but for the \cs{sffamily} command.
+% This is like the \hook{rmfamily} hook, but for the \cs{sffamily} command.
%
% \item[\hook{ttfamily}]
%
-% Like the \hook{rmfamily} hook but for the \cs{ttfamily} command.
+% This is like the \hook{rmfamily} hook, but for the \cs{ttfamily} command.
%
% \item[\hook{normalfont}]
%
-% The \cs{normalfont} command resets font encoding family series
+% The \cs{normalfont} command resets the font encoding, family, series
% and shape to their document defaults. It then executes this
% hook and finally calls \cs{selectfont}.
%
@@ -1926,24 +1930,24 @@
%
% \item[\hook{bfseries/defaults}, \hook{bfseries}]
%
-% If the \cs{bfdefault} was explicitly changed by the user its
+% If the \cs{bfdefault} was explicitly changed by the user, its
% new value is used to set the bf series defaults for the meta
-% families (rm/sf/tt) when \cs{bfseries} is called. In the
-% \hook{bfseries/defaults} hook further adjustments can be made
+% families (rm/sf/tt) when \cs{bfseries} is called. The
+% \hook{bfseries/defaults} hook allows further adjustments to be made
% in this case. This hook is only executed if such a change is
-% detected. In contrast the \hook{bfseries} hook is always
+% detected. In contrast, the \hook{bfseries} hook is always
% executed just before \cs{selectfont} is called to change to the
% new series.
%
%
% \item[\hook{mdseries/defaults}, \hook{mdseries}]
%
-% These two hooks are like the previous ones but used in
+% These two hooks are like the previous ones but they are in the
% \cs{mdseries} command.
%
% \item[\hook{selectfont}]
%
-% This hook is executed inside \cs{selectfont} after the current
+% This hook is executed inside \cs{selectfont}, after the current
% values for \textit{encoding}, \textit{family}, \textit{series},
% \textit{shape}, and \textit{size} are evaluated and the new font
% is selected (and if necessary loaded). After the hook has
@@ -1951,10 +1955,10 @@
% \textit{size} (such as changing the size of \cs{strut}) and any
% updates necessary to a change in \textit{encoding}.
%
-% This hook is intended for use cases where in parallel to a
-% change in the main font some other fonts need to be altered in
-% parallel, e.g., in CJK processing where you deal with several
-% different alphabets in parallel.
+% This hook is intended for use cases where, in parallel to a
+% change in the main font, some other fonts need to be altered
+% (e.g., in CJK processing where you may need to deal with several
+% different alphabets).
%
% \end{description}
%
@@ -2263,19 +2267,19 @@
% \label{sec:existence}
%
% A hook may be in different states of existence. Here we give an
-% overview of internal commands to set up hooks and explain how the
+% overview of the internal commands to set up hooks and explain how the
% different states are distinguished. The actual implementation
-% then follows in the next sections.
+% then follows in subsequent sections.
%
-% One problem we have to solve is, that we need to be able to add
+% One problem we have to solve is that we need to be able to add
% code to hooks (e.g., with \cs{AddToHook}) even if that code has
-% not been declared yet. For example, one package needs to write
+% not yet been declared. For example, one package needs to write
% into a hook of another package, but that package may not get
-% loaded or only loaded later. Another problem most hooks require
-% declaration but this is not the case for the generic hooks.
+% loaded, or is loaded only later. Another problem is that most hooks,
+% but not the generic hooks, require a declaration.
%
-% We therefore distinguish the following states for a hook and they
-% are managed with four different tests: structure existence
+% We therefore distinguish the following states for a hook, which
+% are managed by four different tests: structure existence
% (\cs{@@_if_structure_exist:nTF}), creation
% (\cs{@@_if_usable:nTF}), declaration (\cs{@@_if_declared:nTF})
% and disabled or not (\cs{@@_if_disabled:nTF})
@@ -2731,8 +2735,8 @@
% \end{macro}
%
% \begin{macro}[EXP]{\@@_currname_or_default:}
-% Uses \cs{g_@@_hook_curr_name_tl} if it is set, otherwise tries
-% \cs{@currname}. If neither is set, raises an error and uses the
+% This uses \cs{g_@@_hook_curr_name_tl} if it is set, otherwise it tries
+% \cs{@currname}. If neither is set, it raises an error and uses the
% fallback value \verb|label-missing|.
% \begin{macrocode}
\cs_new:Npn \@@_currname_or_default:
@@ -2753,7 +2757,7 @@
% \end{macro}
%
% \begin{macro}[EXP]{\@@_make_name:n,\@@_make_name:w}
-% Provides a standard sanitization of a hook's name.
+% This provides a standard sanitization of a hook's name.
% It uses \cs{cs:w} to build a control sequence out of the hook name,
% then uses \cs{cs_to_str:N} to get the string representation of that,
% without the escape character. \cs{cs:w}-based expansion is used
@@ -2777,7 +2781,7 @@
% \begin{macro}{\@@_normalize_hook_args:Nnn}
% \begin{macro}{\@@_normalize_hook_rule_args:Nnnnn}
% \begin{macro}{\@@_normalize_hook_args_aux:Nn}
-% Standard route for normalizing hook and label arguments. The main
+% This is the standard route for normalizing hook and label arguments. The main
% macro does the entire operation within a group so that csnames made
% by \cs{@@_make_name:n} are wiped off before continuing. This means
% that this function cannot be used for \cs{hook_use:n}!
@@ -2824,8 +2828,8 @@
% \begin{macro}{\@@_curr_name_pop:}
% \begin{macro}{\@@_end_document_label_check:}
% The token list \cs{g_@@_hook_curr_name_tl} stores the name of the
-% current package/file to be used as label for hooks.
-% Providing a consistent interface is tricky, because packages can
+% current package/file to be used as the default label in hooks.
+% Providing a consistent interface is tricky because packages can
% be loaded within packages, and some packages may not use
% \cs{SetDefaultHookLabel} to change the default label (in which
% case \cs{@currname} is used).
@@ -2872,8 +2876,8 @@
% \end{macrocode}
%
% Two commands keep track of the stack: when a file is input,
-% \cs{@@_curr_name_push:n} pushes the current default label to the
-% stack, and sets the new default label in one go:
+% \cs{@@_curr_name_push:n} pushes the current default label onto the
+% stack and sets the new default label (all in one go):
% \begin{macrocode}
\cs_new_protected:Npn \@@_curr_name_push:n #1
{ \exp_args:Nx \@@_curr_name_push_aux:n { \@@_make_name:n {#1} } }
@@ -2895,8 +2899,8 @@
}
% \end{macrocode}
% and when an input is over, the topmost item of the stack is popped,
-% since the label will not be used again, and \cs{g_@@_hook_curr_name_tl}
-% is updated to the now topmost item of the stack:
+% since that label will not be used again, and \cs{g_@@_hook_curr_name_tl}
+% is updated to equal the now topmost item of the stack:
% \begin{macrocode}
\cs_new_protected:Npn \@@_curr_name_pop:
{
@@ -3207,8 +3211,8 @@
%
% The \cs{exp_after:wN} |...| \cs{exp:w} trick is there to remove the
% conditional structure inserted by
-% \cs{@@_try_declaring_generic_hook:wnTF} to allow access to the
-% tokens that follow it, needed to keep things going.
+% \cs{@@_try_declaring_generic_hook:wnTF} and thus allow access to the
+% tokens that follow it, as is needed to keep things going.
%
% When the deprecation cycle ends, the lines below should all be
% replaced by \cs{prg_return_false:}.
@@ -3252,8 +3256,8 @@
% \@@_declare_deprecated_generic:NNw,
% \@@_declare_deprecated_generic:NNw,
% }
-% Now that the user was told about the deprecation, proceed by
-% swapping \meta{name} and \meta{place} and add the code to the
+% Now that the user has been told about the deprecation, we proceed by
+% swapping \meta{name} and \meta{place} and adding the code to the
% correct hook.
% \begin{macrocode}
\cs_new_protected:Npn \@@_do_deprecated_generic:Nn #1 #2
@@ -3478,9 +3482,8 @@
% \begin{macro}{\c_@@_generics_reversed_ii_prop,
% \c_@@_generics_reversed_iii_prop,
% \c_@@_generics_file_prop}
-% Some of the generic hooks are supposed to use reverse ordering,
-% these are the following (the |ii| and |iii| names are kept for the
-% deprecation cycle):
+% The following generic hooks are supposed to use reverse ordering
+% (the |ii| and |iii| names are kept for the deprecation cycle):
% \begin{macrocode}
%<latexrelease>\IncludeInRelease{2021/11/15}{\c_@@_generics_reversed_ii_prop}%
%<latexrelease> {Standardise~generic~hook~names}
@@ -3868,11 +3871,11 @@
{
% \end{macrocode}
% By default the algorithm sorts the code chunks and then saves the
-% result in a token list for fast execution by adding the code one
-% after another using \cs{tl_gput_right:NV}. When we sort code for
+% result in a token list for fast execution; this is done by adding the code chunks
+% one after another, using \cs{tl_gput_right:NV}. When we sort code for
% a reversed hook, all we have to do is to add the code chunks in
% the opposite order into the token list. So all we have to do
-% in preparation is to change two definitions used later on.
+% in preparation is to change two definitions that are used later on.
% \begin{macrocode}
\@@_if_reversed:nTF {#1}
{ \cs_set_eq:NN \@@_tl_gput:Nn \@@_tl_gput_left:Nn
@@ -3994,9 +3997,9 @@
% \end{macrocode}
%
% We loop over the property list holding the code and record all
-% labels listed there. Only rules for those labels are of interest
+% the labels listed there. Only the rules for those labels are of interest
% to us. While we are at it we count them (which gives us the $N$
-% in Knuth's algorithm. The prefix |label_| is added to the variables
+% in Knuth's algorithm). The prefix |label_| is added to the variables
% to ensure that labels named |front|, |rear|, |labels|, or |return|
% don't interact with our code.
% \begin{macrocode}
@@ -4008,11 +4011,11 @@
\seq_clear_new:c { \@@_seq_csname:n {##1} }
}
% \end{macrocode}
-% Steps T2 and T3: Sort the relevant rules into the data structure\ldots
+% Steps T2 and T3: Here we sort the relevant rules into the data structure\ldots
%
% This loop constitutes a square matrix of the labels in
% \cs{l_@@_work_prop} in the
-% vertical and the horizontal directions. However since the rule
+% vertical and the horizontal directions. However, since the rule
% $l_A\meta{rel}l_B$ is the same as $l_B\meta{rel}^{-1}l_A$ we can cut
% the loop short at the diagonal of the matrix (\emph{i.e.}, when
% both labels are equal), saving a good amount of time. The way the
@@ -4034,7 +4037,7 @@
}
}
% \end{macrocode}
-% Take a breath and take a look at the data structures that have
+% Now take a breath, and look at the data structures that have
% been set up:
% \begin{macrocode}
\@@_debug:n { \@@_debug_label_data:N \l_@@_work_prop }
@@ -4061,7 +4064,7 @@
\clist_gclear:N #2
% \end{macrocode}
%
-% The whole loop combines steps T5--T7:
+% The whole loop gets combined in steps T5--T7:
% \begin{macrocode}
\bool_while_do:nn { ! \str_if_eq_p:Vn \l_@@_front_tl { 0 } }
{
@@ -4078,7 +4081,7 @@
\@@_debug:n{ \iow_term:x{Handled~ code~ for~ \l_@@_front_tl} }
% \end{macrocode}
%
-% This is step T6 except that we don't use a pointer $P$ to move
+% This is step T6, except that we don't use a pointer $P$ to move
% through the successors, but instead use \verb=##1= of the mapping
% function.
% \begin{macrocode}
@@ -4096,7 +4099,7 @@
}
}
% \end{macrocode}
-% and step T7:
+% and here is step T7:
% \begin{macrocode}
\tl_set_eq:Nc \l_@@_front_tl
{ \@@_tl_csname:n { \l_@@_front_tl } }
@@ -4114,14 +4117,14 @@
% \end{macrocode}
%
% This is not really the information one needs in the error case
-% but will do for now \ldots \fmiinline{improve output on a rainy day}
+% but it will do for now \ldots \fmiinline{improve output on a rainy day}
% \begin{macrocode}
\@@_debug_label_data:N \l_@@_work_prop
\iow_term:x{====================}
}
% \end{macrocode}
-% After we have added all hook code to \verb=#1= we finish it off
-% with adding extra code for the |top-level| (\verb=#2=) and for one
+% After we have added all hook code to \verb=#1=, we finish it off
+% by adding extra code for the |top-level| (\verb=#2=) and for one
% time execution (\verb=#3=). These should normally be empty. The
% |top-level| code is added with \cs{@@_tl_gput:Nn} as that might
% change for a reversed hook (then |top-level| is the very first code
@@ -4271,10 +4274,10 @@
% \begin{macro}{\@@_apply_rule_->:nnn,\@@_apply_rule_<-:nnn}
% If we see \texttt{\detokenize{->}} we have to drop code for label
% \verb=#3= and carry on. We could do a little better and drop
-% everything for that label since it doesn't matter where we sort
-% in the empty code. However that would complicate the algorithm a
+% everything for that label since it doesn't matter where we put
+% such empty code. However that would complicate the algorithm a
% lot with little gain.\footnote{This also has the advantage that
-% the result of the sorting doesn't change which might otherwise
+% the result of the sorting doesn't change, as it might otherwise do
% (for unrelated chunks) if we aren't careful.} So we still
% unnecessarily try to sort it in and depending on the rules that
% might result in a loop that is otherwise resolved. If that turns
@@ -4282,8 +4285,8 @@
%
% Here the code is removed from \cs{l_@@_cur_hook_tl} rather than
% \verb=#3= because the latter may be \verb=??=, and the default
-% hook doesn't store any code. Removing from \cs{l_@@_cur_hook_tl}
-% makes default rules \verb=->= and \verb=<-= work properly.
+% hook doesn't store any code. Removing it instead from \cs{l_@@_cur_hook_tl}
+% makes the default rules \verb=->= and \verb=<-= work properly.
% \begin{macrocode}
\cs_new_protected:cpn { @@_apply_rule_->:nnn } #1#2#3
{
@@ -4681,8 +4684,8 @@
% the preamble. \cs{@@_preamble_hook:n} initializes the hook in the
% preamble, and is redefined to \cs{use_none:n} at |\begin{document}|.
%
-% Both versions do the same internally: check if the hook exist as
-% given, and if so use it as quickly as possible.
+% Both versions do the same thing internally: they check that the hook exists as
+% given, and if so they use it as quickly as possible.
%
% At |\begin{document}|, all hooks are initialized, and any change in
% them causes an update, so \cs{hook_use:n} can be made expandable.
@@ -4857,7 +4860,7 @@
% \end{macro}
%
% \begin{macro}[pTF]{\@@_if_execute_immediately:n}
-% To check if code being added should be executed immediately (that
+% To check whether the code being added should be executed immediately (that
% is, if the hook is a one-time hook), we check if it's usable (it
% can't be one-time if it was not already usable), then we check that
% \cs[no-index]{g_@@_\meta{hook}_reversed_tl} is |I|. The gymnastics
More information about the latex3-commits
mailing list.