Add documentation suggestions to lthooks

Author: PhelypeOleinik

base/lthooks.dtx

@@ -31,8 +31,8 @@
 %%% From File: lthooks.dtx
 %
 %    \begin{macrocode}
-\def\lthooksversion{v1.0c}
-\def\lthooksdate{2020/10/04}
+\def\lthooksversion{v1.0d}
+\def\lthooksdate{2020/10/09}
 %    \end{macrocode}
 %
 %<*driver>
@@ -256,6 +256,11 @@
 %    is used in a package/class, then the current
 %    package/class name is used, otherwise \hook{top-level} is used.
 %
+%    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 the optional 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!
@@ -648,10 +653,72 @@
 %
 %   \cs{LogHook} prints the information to the |.log| file, and
 %   \cs{ShowHook} prints them to the terminal/command window and starts
-%   \TeX's prompt (only if \cs{errorstopmode}) to wait for user action.
+%   \TeX's prompt (only in \cs{errorstopmode}) to wait for user action.
 %
 %    The \meta{hook} can be specified using the dot-syntax to denote
 %    the current package name. See section~\ref{sec:default-label}.
+%
+%^^A   % Code for the listing below:
+%^^A   \NewHook{example-hook}
+%^^A   \AddToHook{example-hook}[foo]{[code from package 'foo']}
+%^^A   \AddToHook{example-hook}[bar]{[from package 'bar']}
+%^^A   \AddToHook{example-hook}[baz]{[package 'baz' is here]}
+%^^A   \AddToHookNext{example-hook}{[one-time code]}
+%^^A   \DeclareHookRule{example-hook}{baz}{before}{foo}
+%^^A   \DeclareDefaultHookRule{bar}{after}{baz}
+%^^A   \ShowHook{example-hook}
+%
+%   \def\theFancyVerbLine{\textcolor[gray]{0.5}{%^^A
+%     \sffamily\tiny\arabic{FancyVerbLine}}}
+%
+%   \bigskip
+%   Suppose a hook \texttt{example-hook} whose output of
+%   \cs{ShowHook}|{example-hook}| is:
+%   \begin{verbatim}[numbers=left]
+%   -> The hook 'example-hook':
+%   > Code chunks:
+%   >     foo -> [code from package 'foo']
+%   >     bar -> [from package 'bar']
+%   >     baz -> [package 'baz' is here]
+%   > Extra code for next invocation:
+%   >     -> [one-time code]
+%   > Rules:
+%   >     foo|baz with relation >
+%   >     baz|bar with default relation <
+%   > Execution order (after applying rules):
+%   >     bar, baz, foo.
+%   \end{verbatim}
+%
+%   In the listing above, lines~3 to~5 show the three code chunks added
+%   to the hook and their respective labels in the format
+%   \begin{quote}
+%   \quad \meta{label}\verb| -> |\meta{code}
+%   \end{quote}
+%
+%   Line~7 shows the code chunk for the next execution of the hook in
+%   the format
+%   \begin{quote}
+%   \quad \verb|-> |\meta{next-code}
+%   \end{quote}
+%   This code will be used and disappear at the next
+%   \verb|\UseHook{example-hook}|, in contrast to the chunks mentioned
+%   earlier, which can only be removed from that hook by doing
+%   \verb|\RemoveFromHook{|\meta{label}|}[example-hook]|.
+%
+%   Lines~9 and~10 show the rules declared that affect this hook in the
+%   format
+%   \begin{quote}
+%   \quad \meta{label-1}\verb+|+\meta{label-2}| with |%^^A
+%         \meta{\texttt{default}?}| relation |\meta{relation}
+%   \end{quote}
+%   which means that the \meta{relation} applies to \meta{label-1} and
+%   \meta{label-2}, in that order, as detailed in \cs{DeclareHookRule}.
+%   If the relation is \texttt{default} it means that that rule applies
+%   to \meta{label-1} and \meta{label-2} in \emph{all} hooks, (unless
+%   overrided by a non-default relation).
+%
+%   Finally, line~12 lists the labels in the hook after sorting;
+%   that is, in the order they will be executed when the hook is used.
 % \end{function}
 %
 %