Skip to content

Commit

Permalink
Doc. improvements from Chris
Browse files Browse the repository at this point in the history
I've re-written the part about catcodes entirely.
  • Loading branch information
josephwright committed Mar 27, 2024
1 parent 774b5c2 commit d154216
Showing 1 changed file with 18 additions and 14 deletions.
32 changes: 18 additions & 14 deletions base/doc/usrguide.tex
Original file line number Diff line number Diff line change
Expand Up @@ -804,45 +804,49 @@ \subsection{Using the verbatim argument types}

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
It then makes both spaces and tabs \enquote{active}, so that 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 between two identical delimiters: in contrast to \cs{verb}, the
characters \texttt{\textbackslash}, |{|, |}| and |%| \emph{cannot be used}. If
The characters that are grabbed as the argument are all those between two identical:
in contrast to \cs{verb}, the
characters \texttt{\textbackslash}, |{|, |}| and |%| \emph{cannot} be used as the
delimiter character. 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{obeyedline} commands. This means that
the grabbed tokens can be used directly in typesetting, while a local
For the \texttt{+v}-type argument, which allows line breaks within the argument,
newline characters are converted into \cs{obeyedline} commands. The standard
definition of \cs{obeyedline} is simple |\par|, thus allowing the grabbed tokens
to be used directly in typesetting. A local
redefinition of \cs{obeyedline} can be used to achieve other outputs. For
example, to retain blank lines whilst typesetting, one could use
\begin{verbatim}
\renewcommand*\obeyedline{\mbox{}\par}
\end{verbatim}
along with other setting that may be appropriate (e.g., using a monospaced
font).
More information about using these arguments in typesetting is in the following
subsection.

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
knowledge: do not worry if this does not make sense to you! Spaces and tabs are
stored as active characters. In Unicode engines, all other characters are of
type \enquote{other}. In $8$-bit engines, the ASCII characters other than tab
and space are of type \enquote{other}, and non-ASCII characters are active. 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
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
e.g., selecting 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. (In \cs{verb},
ligatures are suppressed by making characters active and inserting a zero-width
kern before the character itself.)

The \cs{verb} command also selects a monotype font: this is not intrinsic
The \cs{verb} command also selects a monospaced 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.
Expand Down

0 comments on commit d154216

Please sign in to comment.