Merge pull request #1068 from latex3/cmd-args

Cmd hooks with arguments

base/changes.txt

@@ -5,11 +5,17 @@ It is provided for convenience only.  It therefore makes no claims to
 completeness or accuracy and it contains some references to files that
 are not part of the distribution.
 ================================================================================
+
 2023-05-22  Joseph Wright  <Joseph.Wright@latex-project.org>
 
 	* usrguide.tex
 	Ensure url package is always loaded
 
+2023-05-21  Phelype Oleinik  <phelype.oleinik@latex-project.org>
+
+	* lthooks.dtx, ltcmdhooks.dtx:
+	Add support for accessing arguments in 'cmd' hooks.
+
 2023-05-19  Joseph Wright  <Joseph.Wright@latex-project.org>
 
 	* usrguide.tex (section Creating document commands and environments)

base/doc/ltnews37.tex

@@ -254,6 +254,27 @@ \subsection{Extending hooks to take arguments}
 were also added.  The complete documentation can be found in the
 \pkg{lthooks} documentation \cite{37:lthooks-doc}.
 
+\subsubsection{Generic \texttt{cmd} hooks with arguments}
+
+Along with the possibility to pass arguments to a regular hook as
+discussed above, generic \hook{cmd} hooks now can access the arguments
+of the command they are patched into using the interface described in
+the previous section.
+
+For example, if you were to add some code to the \cs{title} command
+using hooks, you could access the actual title given in the argument.
+For example, to write the title of the document in the terminal you
+could use:
+\begin{verbatim}
+  \AddToHookWithArguments{cmd/title/before}
+    {\typeout{Document title: #1}}
+\end{verbatim}
+
+As with regular hooks, code added to a \hook{cmd} hook using
+\cs{AddToHook} will not be able to access the command's arguments.  This
+means that, as with regular hooks, this change is completely backwards
+compatible, so previous usages of \hook{cmd} hooks will work exactly as
+they did before.
 
 \subsection{Providing copy and show functions for environments}