[latex3-commits] [latex3/latex2e] ltcmd-verb: Some doc updates (e8b36256)

[github at latex-project.org]

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

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

commit e8b3625638e2d2b141b8985451adc8c319cb5a6c
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Mon Jul 24 22:41:10 2023 +0100

    Some doc updates


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

e8b3625638e2d2b141b8985451adc8c319cb5a6c
 base/doc/usrguide.tex | 55 ++++++++++++++++++++++++++++++---------------------
 1 file changed, 32 insertions(+), 23 deletions(-)

diff --git a/base/doc/usrguide.tex b/base/doc/usrguide.tex
index 301a04d9..ad6f1d85 100644
--- a/base/doc/usrguide.tex
+++ b/base/doc/usrguide.tex
@@ -798,9 +798,34 @@ a & b & c \\
 
 As described above, 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.
+highlight some key differences. Most notably, \emph{grabbing} a verbatim-like
+argument is separate from \emph{typesetting} it: the latter is covered in the
+next section.
+
+When grabbing a \texttt{v}-type argument, \LaTeX{} first uses the kernel
+command \cs{dospecials} to turn off the \enquote{special} nature of characters.
+It then makes both spaces and tabs \enquote{active}, so they can be given a
+custom definition. Any other characters are grabbed as-is: this means that if
+any characters have been made \enquote{special} and are not listed in
+\cs{dospecials}, an error will arise (see below).
+
+Characters are grabbed two identical delimiters: in contrast to \cs{verb}, the
+characters \texttt{\textbackslash}, |{|, |}| and |%| \emph{cannot be used}. If
+any of the grabbed tokens have \enquote{special} meaning, an error will be
+issued.
+
+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.
+
+Some additional details that may be useful for those with more \TeX{}
+knowledge: do not worry if this does not make sense to you! Grabbed tokens are
+all stored as either active or \enquote{other}: spaces, tabs and non-ASCII
+codepoints in $8$-bit engines are active, everything else is detokenized. As
+such, token-based comparisons are likely to fail unless set up properly.
+
+\subsection{Typesetting verbatim-like material}
 
 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
@@ -809,26 +834,10 @@ 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 contrast 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.
+The \cs{verb} command also selects a monotype font: this is not intrinsic
+to verbatim material, so will need to be set up using for example \cs{ttfamily}.
+Similarly, the \texttt{verbatim} environment sets up the meaning of \cs{par}
+suitable for breaking lines.
 
 \subsection{Details about argument delimiters}