diff options
author | Norbert Preining <norbert@preining.info> | 2024-03-28 03:01:34 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2024-03-28 03:01:34 +0000 |
commit | 79e9e48f9496fe82b7e76b2b318d24e9aab1ca8a (patch) | |
tree | 5c7e66ed056f7855cb4caee718c5406c947e3af8 /macros/latex-dev/base/usrguide.tex | |
parent | 31fa8cd73bab8480d38dae3a89ca578f337d6bbd (diff) |
CTAN sync 202403280301
Diffstat (limited to 'macros/latex-dev/base/usrguide.tex')
-rw-r--r-- | macros/latex-dev/base/usrguide.tex | 101 |
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} |