summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/usrguide.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2024-03-28 03:01:34 +0000
committerNorbert Preining <norbert@preining.info>2024-03-28 03:01:34 +0000
commit79e9e48f9496fe82b7e76b2b318d24e9aab1ca8a (patch)
tree5c7e66ed056f7855cb4caee718c5406c947e3af8 /macros/latex-dev/base/usrguide.tex
parent31fa8cd73bab8480d38dae3a89ca578f337d6bbd (diff)
CTAN sync 202403280301
Diffstat (limited to 'macros/latex-dev/base/usrguide.tex')
-rw-r--r--macros/latex-dev/base/usrguide.tex101
1 files changed, 81 insertions, 20 deletions
diff --git a/macros/latex-dev/base/usrguide.tex b/macros/latex-dev/base/usrguide.tex
index 9f5cfb181a..cf0a01e836 100644
--- a/macros/latex-dev/base/usrguide.tex
+++ b/macros/latex-dev/base/usrguide.tex
@@ -34,8 +34,8 @@
\usepackage{csquotes}
\usepackage{url}
-\title{\LaTeX\ for authors --- current version}
-\author{\copyright~Copyright 2020-2023, \LaTeX\ Project Team.\\
+\title{\LaTeX\ for authors\\ current version}
+\author{\copyright~Copyright 2020--2024, \LaTeX\ Project Team.\\
All rights reserved.%
\footnote{This file may be distributed and/or modified under the
conditions of the \LaTeX{} Project Public License, either version 1.3c
@@ -43,7 +43,7 @@
\texttt{usrguide.tex} for full details.}%
}
-\date{2023-12-02}
+\date{2024-03-17}
\NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
\NewDocumentCommand\marg{m}{\arg{#1}}
@@ -794,6 +794,61 @@ a & b & c \\
\end{tabular}
\end{verbatim}
+\subsection{Using the verbatim argument types}
+
+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. 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 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).
+
+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 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}
+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! 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
+\emph{grabbing} the argument, not \emph{typesetting} it. As such, features that
+users often associate with \enquote{verbatim} are not automatically activated,
+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 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.
+
\subsection{Performance}
For document commands where the argument specification is entirely
@@ -801,7 +856,7 @@ comprised of |m| or |+m| entries (or is entirely empty), the internal structure
created by \cs{NewDocumentCommand} is essentially as efficient
as provided by |\newcommand(*)|. As such, document commands may replace
constructs arising from \cs{newcommand}, etc., without a need to be concerned
-about performance. Note that \cs{newcommand(*)} produces expandable
+about performance. It should be noted that \cs{newcommand(*)} produces expandable
results, so the direct replacement is \cs{NewExpandableDocumentCommand};
in most cases, however, it is better to use \cs{NewDocumentCommand} to
give more robust structures.
@@ -1064,11 +1119,17 @@ to give a purely numerical result.
Briefly, the floating point expressions may comprise:
\begin{itemize}
\item Basic arithmetic: addition $x\fpbin{+}y$, subtraction $x\fpbin{-}y$,
- multiplication $x\fpbin{*}y$, division $x\fpbin{/}y$, square root~$\sqrt{x}$,
+ multiplication $x\fpbin{*}y$, division $x\fpbin{/}y$, square root~$\fpop{sqrt}{x}$,
and parentheses.
\item Comparison operators: $x\fprel{<}y$,
$x\fprel{<=}y$, $x\fprel{>?}y$,
$x\fprel{!=}y$ \emph{etc.}
+
+ The relation $x\fprel{?}y$ is true exactly if one or both operands is~\nan{} or is
+ a tuple, unless they are equal tuples. Each \meta{relation}
+ can be any (non-empty) combination of |<|, |=|, |>|, and~|?|, plus
+ an optional leading~|!| (which negates the \meta{relation}), with
+ the restriction that the negated \meta{relation} may not start with~|?|.
\item Boolean logic: sign $\fpop{sign} x$,
negation $\fpop{!}x$, conjunction
$x\fprel{\&\&}y$, disjunction $x\fprel{\string|\string|}y$, ternary
@@ -1198,13 +1259,13 @@ Titlecasing here follows the definition given by the Unicode Consortium: the
first character of the input will be converted to (broadly) uppercase, and the
rest of the input to lowercase. The full range of Unicode UTF-8 input can be
supported.
-\begin{quote}
- \begin{tabular}{rl}
+\begin{flushleft}
+ \begin{tabular}{@{}ll}
|\MakeUppercase{hello WORLD ßüé}| & \MakeUppercase{hello WORLD ßüé} \\
|\MakeLowercase{hello WORLD ßüé}| & \MakeLowercase{hello WORLD ßüé} \\
|\MakeTitlecase{hello WORLD ßüé}| & \MakeTitlecase{hello WORLD ßüé} \\
\end{tabular}
-\end{quote}
+\end{flushleft}
The case-changing commands take an optional argument which can be used to
tailor the output. This optional argument accepts the key \texttt{locale},
@@ -1220,14 +1281,14 @@ are the arguments to the commands \cs{label}, \cs{ref}, \cs{cite}, \cs{begin}
and \cs{end}. Additional exclusions can be added using the command
\cs{AddToNoCaseChangeList}. Input can be excluded from case changing using the
command \cs{NoCaseChange}.
-\begin{quote}
- \begin{tabular}{rl}
+\begin{flushleft}
+ \begin{tabular}{@{}ll}
|\MakeUppercase{Some text $y = mx + c$}|
& \MakeUppercase{Some text $y = mx + c$} \\
|\MakeUppercase{\NoCaseChange{iPhone}}|
& \MakeLowercase{\NoCaseChange{iPhone}} \\
\end{tabular}
-\end{quote}
+\end{flushleft}
To allow robust commands to be used within case changing \emph{and} to produce
the expected output, two additional control commands are available.
@@ -1256,19 +1317,19 @@ apply to a specific one: this is given in BCP-47 format
(\url{https://en.wikipedia.org/wiki/IETF_language_tag}). For example,
the kernel customises the mapping for U+01F0 (\v{j}) when uppercasing in
8-bit engines:
-\begin{quote}
- |\DeclareUppercaseMapping{"01F0}{\v{J}}|
-\end{quote}
+\begin{verbatim}
+\DeclareUppercaseMapping{"01F0}{\v{J}}
+\end{verbatim}
as there is no pre-composed \v{J} character, and this is problematic if
the engine does not support Unicode natively. Similarly, to set a locale
\texttt{xx} to behave in the same way as Turkish and retain the difference
between dotted- and dotless-i, one could use for example
-\begin{quote}
- |\DeclareLowercaseMapping[xx]{"0049}{\i}|\\
- |\DeclareLowercaseMapping[xx]{"0130}{i}|\\
- |\DeclareUppercaseMapping[xx]{"0069}{\.{I}}|\\
- |\DeclareUppercaseMapping[xx]{"0131}{I}|
-\end{quote}
+\begin{verbatim}
+\DeclareLowercaseMapping[xx]{"0049}{\i}
+\DeclareLowercaseMapping[xx]{"0130}{i}
+\DeclareUppercaseMapping[xx]{"0069}{\.{I}}
+\DeclareUppercaseMapping[xx]{"0131}{I}
+\end{verbatim}
\section{Support for problem solving}