[latex3-commits] [latex3/latex3] main: Document hash doubling (fixes #951) (a73ba9a95)

[github at latex-project.org]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/a73ba9a95427d768d49e39ce46d2b21db5c4da06

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

commit a73ba9a95427d768d49e39ce46d2b21db5c4da06
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Fri May 19 07:52:12 2023 +0100

    Document hash doubling (fixes #951)


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

a73ba9a95427d768d49e39ce46d2b21db5c4da06
 l3kernel/doc/l3term-glossary.tex | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/l3kernel/doc/l3term-glossary.tex b/l3kernel/doc/l3term-glossary.tex
index 9fae8221b..af204870d 100644
--- a/l3kernel/doc/l3term-glossary.tex
+++ b/l3kernel/doc/l3term-glossary.tex
@@ -146,4 +146,35 @@ removed) becomes the argument.  Note that explicit space characters at
 the start of the argument are \emph{not} ignored in this case (and they
 prevent brace-stripping).
 
+\section{Handling of hash tokens}
+
+\TeX{} uses the hash (octothorpe) character |#| to denote parameters for
+macros: these must be numbered sequentially. To allow handling of nested
+marcos, \TeX{} requires that for each nesting level, hash tokens are doubled.
+For example
+\begin{verbatim}
+\cs_new:Npn \mypkg_outer:N #1
+  {
+    \cs_new:Npn \mypkg_inner:N ##1
+      {
+        #1
+        ##1
+      }
+  }
+\end{verbatim}
+would define both |\mypkg_outer:N| and |\mypkg_inner:N| as taking
+exactly one argument. If we then do
+\begin{verbatim}
+\mypkg_outer:N \foo
+\cs_show:N \mypkg_inner:N
+\end{verbatim}
+\TeX{} will report
+\begin{verbatim}
+> \mypkg_inner:N=\long macro:#1->\foo #1.
+\end{verbatim}
+i.e.~the hash is not doubled, but is now the parameter of this macro.
+
+Exactlt the same concept applies to anywhere that inline code is nested in
+\pkg{expl3}, for example inline mapping code, key definitions, etc.
+
 \end{document}