[latex3-commits] [git/LaTeX3-latex3-latex2e] gh625: Document new behaviour of \RemoveFromHook (bcec792b)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex2e
On branch  : gh625
Link       : https://github.com/latex3/latex2e/commit/bcec792b7d835eb0150e7b2125f2a1df75ada93c

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

commit bcec792b7d835eb0150e7b2125f2a1df75ada93c
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Mon Jul 26 23:40:37 2021 -0300

    Document new behaviour of \RemoveFromHook


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

bcec792b7d835eb0150e7b2125f2a1df75ada93c
 base/lthooks.dtx | 32 +++++++++++++++++---------------
 1 file changed, 17 insertions(+), 15 deletions(-)

diff --git a/base/lthooks.dtx b/base/lthooks.dtx
index 247aaab6..0f719bf6 100644
--- a/base/lthooks.dtx
+++ b/base/lthooks.dtx
@@ -321,14 +321,17 @@
 %    When the optional argument \meta{label} is not provided, the
 %    \meta{default label} is used (see section~\ref{sec:default-label}).
 %
-%    If the code for that \meta{label} wasn't yet added to the
-%    \meta{hook}, an order is set so that when some code attempts to add
-%    that label, the removal order takes action and the code is not
-%    added.
+%    If there is no code under the \meta{label} in the \meta{hook},
+%    or if the \meta{hook} does not exist, an error is raised when
+%    you attempt to \cs{RemoveFromHook}.
+%    \cs{RemoveFromHook} should be used when you know exactly what
+%    labels are in a hook, usually added and removed within the 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 by used
+%    packages one may not know about and should therefore not be used
 %    by packages but only in document preambles!
 %
 %    The \meta{hook} and \meta{label} can be specified using the
@@ -588,6 +591,7 @@
 % with that label from a package results in an error.
 %
 % \subsubsection{Defining relations between hook code}
+% \label{sec:rules}
 %
 % The default assumption is that code added to hooks by different
 % packages are independent and the order in which they are executed is
@@ -1020,10 +1024,9 @@
 %   \end{syntax}
 %    Removes any code for \meta{hook} labeled \meta{label}.
 %
-%    If the code for that \meta{label} wasn't yet added to the
-%    \meta{hook}, an order is set so that when some code attempts to add
-%    that label, the removal order takes action and the code is not
-%    added.
+%    If there is no code under the \meta{label} in the \meta{hook},
+%    or if the \meta{hook} does not exist, an error is raised when
+%    you attempt to \cs{RemoveFromHook}.
 %
 %    If the second argument is \texttt{*}, then all code chunks are
 %    removed. This is rather dangerous as it drops code from other
@@ -1138,7 +1141,7 @@
 %    which key-value pairs got added. However, that is only true if
 %    nothing other than adding happens!
 %
-%    Suppose, or example, you want to replace the code chunk for
+%    Suppose, for example, you want to replace the code chunk for
 %    \texttt{packageA}, e.g.,
 %\begin{verbatim}
 %    \RemoveFromHook{myhook}[packageA]
@@ -3152,9 +3155,7 @@
       }
 %    \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.
+%    If the code pool for this hook doesn't exist, raise an error:
 %    \begin{macrocode}
       { \msg_error:nnnn { hooks } { cannot-remove } {#1} {#2} }
   }
@@ -3562,8 +3563,9 @@
 %
 %    When sorting, some relations (namely \verb|voids|) need to
 %    act destructively on the code property lists to remove code that
-%    shouldn't appear in the sorted hook token list, so we temporarily
-%    save the old code property list so that it can be restored later.
+%    shouldn't appear in the sorted hook token list, so we make a copy
+%    of the code property list that we can safely work on without
+%    changing the main one.
 %    \begin{macrocode}
             \prop_set_eq:Nc \l_@@_work_prop { g_@@_#1_code_prop }
             \@@_initialize_single:ccn