[latex3-commits] [git/LaTeX3-latex3-latex2e] lthooks2: Doc improvements (8f8e6f1a)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex2e
On branch  : lthooks2
Link       : https://github.com/latex3/latex2e/commit/8f8e6f1aa5220a660e3330134e2de070b86a50c0

>---------------------------------------------------------------

commit 8f8e6f1aa5220a660e3330134e2de070b86a50c0
Author: PhelypeOleinik <tex.phelype at gmail.com>
Date:   Tue Aug 18 21:26:23 2020 -0300

    Doc improvements


>---------------------------------------------------------------

8f8e6f1aa5220a660e3330134e2de070b86a50c0
 base/ltfilehook.dtx |  4 ++--
 base/lthooks.dtx    | 30 +++++++++++++++++++++++++-----
 2 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/base/ltfilehook.dtx b/base/ltfilehook.dtx
index 699ba180..6244a743 100644
--- a/base/ltfilehook.dtx
+++ b/base/ltfilehook.dtx
@@ -561,7 +561,7 @@
      \@filehook at file@push
      \@filehook at set@CurrentFile
 %    \end{macrocode}
-%    If the file exists then \cs{@curr at file} holds its name. But we
+%    If the file exists then \cs{CurrentFile} holds its name. But we
 %    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 restored it for the
@@ -595,7 +595,7 @@
           \@addtofilelist{#1}%
           \UseHook{file/before}%
 %    \end{macrocode}
-%    The current file name is available in \cs{@curr at file} so we use
+%    The current file name is available in \cs{CurrentFile} so we use
 %    that in the specific hook.
 %    \begin{macrocode}
           \UseHook{file/before/\CurrentFile}%
diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index afd51806..465f25d7 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -1728,7 +1728,7 @@
 %    get added again  later if the hook data gets updated.
 %    \begin{macrocode}
             \tl_gclear:c { @#1hook }
-           }
+          }
       }
     \debug_resume:
   }
@@ -1836,13 +1836,19 @@
 \cs_new_protected:Npn \@@_gput_code:nnn #1 #2 #3
   {
 %    \end{macrocode}
-%    First we check if the hook exists.\pho{correct docu}
+%    First check if the current \meta{hook}/\meta{label} pair was marked
+%    for removal, in which case \cs{@@_unmark_removal:nn} is used to
+%    remove that mark (once).  This may happen when a package removes
+%    code from another package which was not yet loaded:  the removal
+%    order is stored, and at this stage it is executed by not adding to
+%    the hook.
 %    \begin{macrocode}
     \@@_if_marked_removal:nnTF {#1} {#2}
       { \@@_unmark_removal:nn {#1} {#2} }
       {
 %    \end{macrocode}
-%    First we check if the hook exists.
+%    If no removal is queued, we are free to add.  Start by checking if
+%    the hook exists.
 %    \begin{macrocode}
         \hook_if_exist:nTF {#1}
 %    \end{macrocode}
@@ -1861,6 +1867,9 @@
           }
 %    \end{macrocode}
 %
+%    If the hook does not exist, however, before giving up try to
+%    declare it as a generic hook, if its name matches one of the valid
+%    patterns.
 %    \begin{macrocode}
           { \@@_try_declaring_generic_hook:nnn {#1} {#2} {#3} }
       }
@@ -2132,6 +2141,12 @@
         \hook_if_exist:nT {#1}
           { \@@_update_hook_code:n {#1} }
       }
+%    \end{macrocode}
+%
+%    If the code pool for this hook doesn't exist it means that nothing
+%    tried to add to it before, so we just queue this removal order for
+%    later.
+%    \begin{macrocode}
       { \@@_mark_removal:nn {#1} {#2} }
   }
 %    \end{macrocode}
@@ -2147,7 +2162,10 @@
 %
 % \begin{macro}{\@@_mark_removal:nn}
 %   Marks \meta{label} (\verb=#2=) to be removed from \meta{hook}
-%   (\verb=#1=).
+%   (\verb=#1=).  The number of removals should be fairly small, and
+%   \cs{tl_gremove_once:Nx} is fairly efficient even for longer token
+%   lists, so we use a single global token list, rather than one for
+%   each hook.
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_mark_removal:nn #1 #2
   {
@@ -2186,7 +2204,9 @@
 %
 % \begin{macro}[rEXP]{\@@_removal_tl:nn}
 %   Builds a token list with \verb=#1= and \verb=#2= which can only be
-%   matched by \verb=#1= and \verb=#2=.
+%   matched by \verb=#1= and \verb=#2=.  The |&|$_4$ anchors a removal,
+%   so that \verb=#1= can't be mistaken by \verb=#2= and vice versa, and
+%   the two |$|$_3$ delimit the two arguments
 %    \begin{macrocode}
 \cs_new:Npn \@@_removal_tl:nn #1 #2
   { & \tl_to_str:n {#2} $ \tl_to_str:n {#1} $ }