[latex3-commits] [git/LaTeX3-latex3-latex3] master: Docs [ci skip] (a2817e8)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/a2817e811d892d4120b422eae92d3430bff61f74

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

commit a2817e811d892d4120b422eae92d3430bff61f74
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Fri Jun 7 10:09:54 2019 +0100

    Docs [ci skip]


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

a2817e811d892d4120b422eae92d3430bff61f74
 l3trial/l3hooks/l3hooks.dtx |   43 +++++++++++++++++++++++++------------------
 1 file changed, 25 insertions(+), 18 deletions(-)

diff --git a/l3trial/l3hooks/l3hooks.dtx b/l3trial/l3hooks/l3hooks.dtx
index 0e4ded7..8912065 100644
--- a/l3trial/l3hooks/l3hooks.dtx
+++ b/l3trial/l3hooks/l3hooks.dtx
@@ -54,24 +54,28 @@
 %
 % \section{\pkg{l3hooks} documentation}
 %
-% \subsection{Standard hooks}
+% Hooks are points in a code path where material may be injected by
+% \enquote{user} modules. In \pkg{l3hooks}, each hook entry is given a
+% description made up of the \meta{user} module and an optional sub-description.
+% Hook entries are managed on a global basis.
+%
+% \subsection{Repeated hooks}
 %
-% Standard hooks may be used repeatedly throughout a document. They are
-% sub-divided by the module \emph{providing} the hook. These hooks may have
-% content added just to the next use of the hook or to all future uses.
+% Repeated hooks may be inserted at multiple positions in a document run, for
+% example at the start of every section. These hooks are created on a per-module
+% basis, allowing multiple \enquote{provider} modules to use simple names for
+% their hooks.
 %
-% Hook entries are created with name and attached code. The name will be
-% the module providing the code plus an optional description. In most cases,
-% the \enquote{user} module will be sufficient information, but where a module
-% uses the same hook repeatedly it will also need the description.
+% Entries may be added to all uses of a hook or strictly to the next use only.
+% This allows one-off effects to be achieved without having to test within
+% the \enquote{user} code.
 %
 % \begin{function}[added = 2019-06-06]
 %   {\hook_new:nn}
 %   \begin{syntax}
 %     \cs{hook_new:nn} \Arg{module} \Arg{hook}
 %   \end{syntax}
-%   Creates a new \meta{hook} for the \meta{module} specified. The hook may
-%   be used repeatedly.
+%   Creates a new \meta{hook} for the \meta{module} specified.
 % \end{function}
 %
 % \begin{function}[added = 2019-06-07]
@@ -80,12 +84,13 @@
 %     \hook_gadd_all:nnnnn, \hook_gadd_next:nnnnn,
 %   }
 %   \begin{syntax}
-%     \cs{hook_gadd_all:nnnn} \Arg{module-a} \Arg{hook} \Arg{module-b} \Arg{code}
-%     \cs{hook_gadd_all:nnnnn} \Arg{module-a} \Arg{hook} \Arg{module-b} \Arg{desc} \Arg{code}
+%     \cs{hook_gadd_all:nnnn} \Arg{provider} \Arg{hook} \Arg{user} \Arg{code}
+%     \cs{hook_gadd_all:nnnnn} \Arg{provider} \Arg{hook} \Arg{user} \Arg{desc} \Arg{code}
 %   \end{syntax}
-%   Adds an entry to the \meta{hook} which will execute the \meta{code} from
-%   \meta{module-b}. Each entry must be unique, and thus repeated use of the
-%   same \meta{module-b} (or \meta{module-b}/\meta{desc}) will overwrite older
+%   Adds an entry to the \meta{hook} of the \meta{provider} module. At point
+%   of use, this which will execute the \meta{code} from \meta{user} module. Each
+%   entry must be unique, and thus repeated use of the
+%   same \meta{user} (or \meta{user}/\meta{desc}) will overwrite older
 %   entries. Entries are added at the \emph{end} of the hook.
 % \end{function}
 %
@@ -117,10 +122,12 @@
 % \begin{function}[added = 2019-06-06]
 %   {\hook_document_gadd:nnn, \hook_document_gadd:nnnn}
 %   \begin{syntax}
-%     \cs{hook_document_gadd:nnn} \Arg{hook} \Arg{module} \Arg{code}
-%     \cs{hook_document_gadd:nnnn} \Arg{hook} \Arg{module} \Arg{desc} \Arg{code}
+%     \cs{hook_document_gadd:nnn} \Arg{hook} \Arg{user} \Arg{code}
+%     \cs{hook_document_gadd:nnnn} \Arg{hook} \Arg{user} \Arg{desc} \Arg{code}
 %   \end{syntax}
-%   Pushes an entry to the document-wide \meta{hook}.
+%   Pushes an entry to the document-wide \meta{hook}. As for repeated hooks,
+%   the code may be named using just the \meta{user} module name or the
+%   \meta{user}/\meta{desc} combination.
 % \end{function}
 %
 % \begin{function}[added = 2019-06-06]{\hook_document_use:n}