[latex3-commits] [latex3/latex2e] ltcmd-verb: Document details of v-type ltcmd argument (8d9bc2ae)

[github at latex-project.org]

Repository : https://github.com/latex3/latex2e
On branch  : ltcmd-verb
Link       : https://github.com/latex3/latex2e/commit/8d9bc2ae9fc9771131a768a641d42a8f008aaf9e

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

commit 8d9bc2ae9fc9771131a768a641d42a8f008aaf9e
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed Jun 14 21:20:23 2023 +0100

    Document details of v-type ltcmd argument
    
    See latex3/latex3#756.


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

8d9bc2ae9fc9771131a768a641d42a8f008aaf9e
 base/changes.txt      |  2 ++
 base/doc/usrguide.tex | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/base/changes.txt b/base/changes.txt
index 77c9a67b..1361c503 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -13,6 +13,8 @@ are not part of the distribution.
 	* ltcmd.dtx
 	Collect spaces and tabs as active chars
 	Collect \endlinechar as \par
+	* usrguide.tex
+	Add more details of ltcmd v-type arguments
 
 2023-06-09  Joseph Wright  <Joseph.Wright at latex-project.org>
 
diff --git a/base/doc/usrguide.tex b/base/doc/usrguide.tex
index 5577be9f..1dc0166c 100644
--- a/base/doc/usrguide.tex
+++ b/base/doc/usrguide.tex
@@ -794,6 +794,42 @@ a & b & c \\
 \end{tabular}
 \end{verbatim}
 
+\subsection{Using the verbatim argument types}
+
+As described about, the \texttt{v}-type argument may be viewed as similar to
+\cs{verb}. Before looking at exactly what that means, it is important to
+highlight some key differences. Note that using the \texttt{v}-type argument
+does require knowledge of underlying \TeX{} concepts, in particular
+category codes.
+
+In contrast to \cs{verb}, the \texttt{v}-type argument is only about
+\emph{grabbing} the argument, not \emph{typesetting} it. As such, features that
+users often associate with \enquote{verbatim} are not automatically activated,
+e.g.~a monospaced font. Material grabbed by the \texttt{v}-type argument does
+not automatically suppress ligatures: with modern \TeX{} engines, this largely
+can be done without the token manipulation which \cs{verb} uses.
+
+When grabbing a \texttt{v}-type argument, \LaTeX{} first uses the kernel
+command \cs{dospecials} to change the category code of special characters to
+\enquote{other}. It then makes both spaces and tabs active, and leaves the
+category code of other characters unchanged. Tokens are then grabbed between
+two identical delimiters: in contract to \cs{verb}, the characters
+\texttt{\textbackslash}, |{|, |}| and |%| \emph{cannot be used}. If any of the
+grabbed tokens do not have category code space~(10), letter~(11),
+\enquote{other}~(12) or active~(13), an error will be issued: as such, any
+non-standard character tokens must be listed in \cs{dospecials}.
+
+After grabbing, all non-active character tokens are converted to
+\enquote{other} tokens. Spaces and tabs \emph{are stored as
+active tokens}, as are other document-level active characters. This
+allows the use of UTF-8 material in \texttt{v}-type arguments with
+pdf\TeX{}.
+
+For the \texttt{+v}-type argument, which allows line breaks in input,
+newline characters are converted into \cs{par} tokens. This means that
+the grabbed tokens can be used directly in typesetting, while a local
+redefinition of \cs{par} can be used to achieve other outputs.
+
 \subsection{Details about argument delimiters}
 
 In normal (non-expandable) commands, the delimited types look for the