| 1 |
% \iffalse meta-comment |
| 2 |
% |
| 3 |
% Copyright (C) 2020-2025 |
| 4 |
% The LaTeX Project and any individual authors listed elsewhere |
| 5 |
% in this file. |
| 6 |
% |
| 7 |
% This file is part of the LaTeX base system. |
| 8 |
% ------------------------------------------- |
| 9 |
% |
| 10 |
% It may be distributed and/or modified under the |
| 11 |
% conditions of the LaTeX Project Public License, either version 1.3c |
| 12 |
% of this license or (at your option) any later version. |
| 13 |
% The latest version of this license is in |
| 14 |
% http://www.latex-project.org/lppl.txt |
| 15 |
% and version 1.3c or later is part of all distributions of LaTeX |
| 16 |
% version 2008 or later. |
| 17 |
% |
| 18 |
% This file has the LPPL maintenance status "maintained". |
| 19 |
% |
| 20 |
% The list of all files belonging to the LaTeX base distribution is |
| 21 |
% given in the file `manifest.txt'. See also `legal.txt' for additional |
| 22 |
% information. |
| 23 |
% |
| 24 |
% The list of derived (unpacked) files belonging to the distribution |
| 25 |
% and covered by LPPL is defined by the unpacking scripts (with |
| 26 |
% extension .ins) which are part of the distribution. |
| 27 |
% |
| 28 |
% \fi |
| 29 |
% Filename: usrguide.tex |
| 30 |
|
| 31 |
\documentclass{ltxguide} |
| 32 |
|
| 33 |
\usepackage[T1]{fontenc} % needed for \textbackslash in tt |
| 34 |
\usepackage{csquotes} |
| 35 |
\usepackage{url} |
| 36 |
|
| 37 |
\title{\LaTeX\ for authors\\ current version} |
| 38 |
\author{\copyright~Copyright 2020--2025, \LaTeX\ Project Team.\\ |
| 39 |
All rights reserved.% |
| 40 |
\footnote{This file may be distributed and/or modified under the |
| 41 |
conditions of the \LaTeX{} Project Public License, either version 1.3c |
| 42 |
of this license or (at your option) any later version. See the source |
| 43 |
\texttt{usrguide.tex} for full details.}% |
| 44 |
} |
| 45 |
|
| 46 |
\date{2025-06-26} |
| 47 |
|
| 48 |
\NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}} |
| 49 |
\NewDocumentCommand\marg{m}{\arg{#1}} |
| 50 |
\NewDocumentCommand\meta{m}{\ensuremath{\langle}\textit{#1}\ensuremath{\rangle}} |
| 51 |
\NewDocumentCommand\pkg{m}{\textsf{#1}} |
| 52 |
\NewDocumentCommand\text{m}{\ifmmode\mbox{#1}\else#1\fi} |
| 53 |
% Fix a 'feature' |
| 54 |
\makeatletter |
| 55 |
\renewcommand \verbatim@font {\normalfont \ttfamily} |
| 56 |
\makeatother |
| 57 |
|
| 58 |
|
| 59 |
% for fpeval documentation |
| 60 |
|
| 61 |
\providecommand\fpop[1]{\mathop{\texttt{#1}}} |
| 62 |
\providecommand\fpbin[1]{\mathbin{\texttt{#1}}} |
| 63 |
\providecommand\fprel[1]{\mathrel{\texttt{#1}}} |
| 64 |
\providecommand\nan{\texttt{NaN}} |
| 65 |
|
| 66 |
\ExplSyntaxOn |
| 67 |
\ProvideExpandableDocumentCommand \fpeval { m } { \fp_eval:n {#1} } |
| 68 |
\ExplSyntaxOff |
| 69 |
|
| 70 |
\begin{document} |
| 71 |
|
| 72 |
\maketitle |
| 73 |
|
| 74 |
\tableofcontents |
| 75 |
|
| 76 |
\section{Introduction} |
| 77 |
|
| 78 |
\LaTeXe{} was released in 1994 and added a number of then-new concepts to |
| 79 |
\LaTeX{}. These are described in \texttt{usrguide-historic}, which has largely remained |
| 80 |
unchanged. Since then, the \LaTeX{} team have worked on a number of ideas, |
| 81 |
firstly a programming language for \LaTeX{} (\pkg{expl3}) and then a range of |
| 82 |
tools for document authors which build on that language. Here, we describe |
| 83 |
\emph{stable} and \emph{widely-usable} concepts that have resulted from that |
| 84 |
work. These `new' ideas have been transferred from development packages |
| 85 |
into the \LaTeXe{} kernel. As such, they are now available to \emph{all} |
| 86 |
\LaTeX{} users and have the \emph{same stability} as any other part of the |
| 87 |
kernel. The fact that `behind the scenes' they are built on \pkg{expl3} |
| 88 |
is useful for the development team, but is not directly important to users. |
| 89 |
|
| 90 |
\section{Creating document commands and environments} |
| 91 |
|
| 92 |
\subsection{Overview} |
| 93 |
|
| 94 |
Creating document commands and environments using the \LaTeX3 toolset is based |
| 95 |
around the idea that a common set of descriptions can be used to cover almost |
| 96 |
all argument types used in real documents. Thus parsing is reduced to a simple |
| 97 |
description of which arguments a command takes: this description provides the |
| 98 |
`glue' between the document syntax and the implementation of the |
| 99 |
command. |
| 100 |
|
| 101 |
First, we will describe the argument types, then move on to explain how these |
| 102 |
can be used to create both document commands and environments. Various more |
| 103 |
specialized features are then described, which allow an even richer application |
| 104 |
of a simple interface set up. |
| 105 |
|
| 106 |
The details here are intended to help users create document commands in |
| 107 |
general. More technical detail, suitable for \TeX{} programmers, is included |
| 108 |
in \texttt{interface3}. |
| 109 |
|
| 110 |
\subsection{Describing argument types} |
| 111 |
|
| 112 |
In order to allow each argument to be defined independently, the parser does |
| 113 |
not simply need to know the number of arguments for a function, but also the |
| 114 |
nature of each one. This is done by constructing an \emph{argument |
| 115 |
specification}, which defines the number of arguments, the type of each |
| 116 |
argument and any additional information needed for the parser to read the user |
| 117 |
input and properly pass it through to internal functions. |
| 118 |
|
| 119 |
The basic form of the argument specifier is a list of letters, where each |
| 120 |
letter defines a type of argument. As will be described below, some of the |
| 121 |
types need additional information, such as default values. The argument types |
| 122 |
can be divided into two, those which define arguments that are mandatory |
| 123 |
(potentially raising an error if not found) and those which define optional |
| 124 |
arguments. The mandatory types |
| 125 |
\begin{itemize} |
| 126 |
\item[\texttt{m}] A standard mandatory argument, which can either be a single token |
| 127 |
alone or multiple tokens surrounded by curly braces |{}|. Regardless of the |
| 128 |
input, the argument will be passed to the internal code without the outer |
| 129 |
braces. This is the type specifier for a normal \TeX{} argument. |
| 130 |
\item[\texttt{r}] Given as \texttt{r}\meta{token1}\meta{token2}, this denotes a |
| 131 |
`required' delimited argument, where the delimiters are |
| 132 |
\meta{token1} and \meta{token2}. If the opening delimiter \meta{token1} is |
| 133 |
missing, the default marker |-NoValue-| will be inserted after a suitable |
| 134 |
error. |
| 135 |
\item[\texttt{R}] Given as \texttt{R}\meta{token1}\meta{token2}\marg{default}, |
| 136 |
this is a `required' delimited argument as for~\texttt{r}, |
| 137 |
but it has a user-definable recovery \meta{default} instead of |
| 138 |
|-NoValue-|. |
| 139 |
\item[\texttt{v}] Reads an argument `verbatim', between the following |
| 140 |
character and its next occurrence, in a way similar to the argument |
| 141 |
of the \LaTeXe{} command \cs{verb}. Thus a \texttt{v}-type argument |
| 142 |
is read between two identical characters, which cannot be any of |%|, |\|, |
| 143 |
|#|, |{|, |}| or \verb*| |. The verbatim argument can also be enclosed |
| 144 |
between braces, |{| and |}|. A command with a verbatim argument will |
| 145 |
produce an error when it appears within an argument of another command. |
| 146 |
\item[\texttt{b}] Only suitable in the argument specification of an |
| 147 |
environment, it denotes the body of the environment, between |
| 148 |
|\begin|\marg{environment} and |\end|\marg{environment}. See |
| 149 |
Section~\ref{sec:cmd:body} for details. |
| 150 |
\item[\texttt{c}] Only suitable in the argument specification of an |
| 151 |
environment, it denotes collection of the environment verbatim, between |
| 152 |
|\begin|\marg{environment} and |\end|\marg{environment}. See |
| 153 |
Section~\ref{sec:cmd:verbenv} for details. |
| 154 |
\end{itemize} |
| 155 |
The types which define optional arguments are: |
| 156 |
\begin{itemize} |
| 157 |
\item[\texttt{o}] A standard \LaTeX{} optional argument, surrounded with square |
| 158 |
brackets, which will supply the special |-NoValue-| marker if not given |
| 159 |
(as described later). |
| 160 |
\item[\texttt{d}] Given as \texttt{d}\meta{token1}\meta{token2}, an optional |
| 161 |
argument which is delimited by \meta{token1} and \meta{token2}. As with |
| 162 |
\texttt{o}, if no value is given the special marker |-NoValue-| is |
| 163 |
returned. |
| 164 |
\item[\texttt{O}] Given as \texttt{O}\marg{default}, is like \texttt{o}, but returns |
| 165 |
\meta{default} if no value is given. |
| 166 |
\item[\texttt{D}] Given as \texttt{D}\meta{token1}\meta{token2}\marg{default}, it is |
| 167 |
as for \texttt{d}, but returns \meta{default} if no value is given. |
| 168 |
Internally, the \texttt{o}, \texttt{d} and \texttt{O} types are |
| 169 |
short-cuts to an appropriated-constructed \texttt{D} type argument. |
| 170 |
\item[\texttt{s}] An optional star, which will result in a value |
| 171 |
\cs{BooleanTrue} if a star is present and \cs{BooleanFalse} |
| 172 |
otherwise (as described later). |
| 173 |
\item[\texttt{t}] An optional \meta{token}, which will result in a value |
| 174 |
\cs{BooleanTrue} if \meta{token} is present and \cs{BooleanFalse} |
| 175 |
otherwise. Given as \texttt{t}\meta{token}. |
| 176 |
\item[\texttt{e}] Given as \texttt{e}\marg{tokens}, a set of optional |
| 177 |
\emph{embellishments}, each of which requires a \emph{value}. |
| 178 |
If an embellishment is not present, |-NoValue-| is returned. Each |
| 179 |
embellishment gives one argument, ordered as for the list of |
| 180 |
\meta{tokens} in the argument specification. All \meta{tokens} |
| 181 |
must be distinct. |
| 182 |
\item[\texttt{E}] As for \texttt{e} but returns one or more \meta{defaults} |
| 183 |
if values are not given: \texttt{E}\marg{tokens}\marg{defaults}. See |
| 184 |
Section~\ref{sec:cmd:embellishment} for more details. |
| 185 |
\end{itemize} |
| 186 |
|
| 187 |
\subsection{Modifying argument descriptions} |
| 188 |
|
| 189 |
In addition to the argument \emph{types} discussed above, the argument |
| 190 |
description also gives special meaning to three other characters. |
| 191 |
|
| 192 |
First, \texttt{+} is used to make an argument long (to accept paragraph |
| 193 |
tokens). In contrast to \cs{newcommand}, this applies on an |
| 194 |
argument-by-argument basis. So modifying the example to `|s o o +m O{default}|' |
| 195 |
means that the mandatory argument is now \cs{long}, whereas the optional |
| 196 |
arguments are not. |
| 197 |
|
| 198 |
Secondly, \texttt{!} is used to control whether spaces are allowed before |
| 199 |
optional arguments. There are some subtleties to this, as \TeX{} itself |
| 200 |
has some restrictions on where spaces can be `detected': more detail |
| 201 |
is given in Section~\ref{sec:cmd:opt-space}. |
| 202 |
|
| 203 |
Thirdly, \texttt{=} is used to declare that the following argument should |
| 204 |
be interpreted as a series of keyvals. See Section~\ref{sec:cmd:keyval} |
| 205 |
for more details. |
| 206 |
|
| 207 |
Finally, the character \texttt{>} is used to declare so-called |
| 208 |
`argument processors', which can be used to modify the contents of an |
| 209 |
argument before it is passed to the macro definition. The use of argument |
| 210 |
processors is a somewhat advanced topic, (or at least a less commonly used |
| 211 |
feature) and is covered in Section~\ref{sec:cmd:processors}. |
| 212 |
|
| 213 |
\subsection{Creating document commands and environments} |
| 214 |
|
| 215 |
\begin{decl} |
| 216 |
|\NewDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\ |
| 217 |
|\RenewDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\ |
| 218 |
|\ProvideDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\ |
| 219 |
|\DeclareDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} |
| 220 |
\end{decl} |
| 221 |
This family of commands are used to create a \meta{cmd}. The argument |
| 222 |
specification for the function is given by \meta{arg spec}, and the command |
| 223 |
uses the \meta{code} with |#1|, |#2|, etc.\ replaced by the arguments found |
| 224 |
by the parser. |
| 225 |
|
| 226 |
An example: |
| 227 |
\begin{verbatim} |
| 228 |
\NewDocumentCommand\chapter{s o m} |
| 229 |
{% |
| 230 |
\IfBooleanTF{#1}% |
| 231 |
{\typesetstarchapter{#3}}% |
| 232 |
{\typesetnormalchapter{#2}{#3}}% |
| 233 |
} |
| 234 |
\end{verbatim} |
| 235 |
would be a way to define a \cs{chapter} command which would essentially behave |
| 236 |
like the current \LaTeXe{} command (except that it would accept an optional |
| 237 |
argument even when a \texttt{*} was parsed). The \cs{typesetnormalchapter} |
| 238 |
could test its first argument for being |-NoValue-| to see if an optional |
| 239 |
argument was present. (See Section~\ref{sec:cmd:special} for details of |
| 240 |
\cs{IfBooleanTF} and testing for |-NoValue-|.) |
| 241 |
|
| 242 |
The difference between the \cs{New...} \cs{Renew...}, \cs{Provide...} |
| 243 |
and \cs{Declare...} versions is the behavior if \meta{cmd} is already |
| 244 |
defined. |
| 245 |
\begin{itemize} |
| 246 |
\item \cs{NewDocumentCommand} will issue an error if \meta{cmd} |
| 247 |
has already been defined. |
| 248 |
\item \cs{RenewDocumentCommand} will issue an error if \meta{cmd} |
| 249 |
has not previously been defined. |
| 250 |
\item \cs{ProvideDocumentCommand} creates a new definition for |
| 251 |
\meta{cmd} only if one has not already been given. |
| 252 |
\item \cs{DeclareDocumentCommand} will always create the new |
| 253 |
definition, irrespective of any existing \meta{cmd} with the |
| 254 |
same name. This should be used sparingly. |
| 255 |
\end{itemize} |
| 256 |
|
| 257 |
If the \meta{cmd} can't be provided as a single token but needs |
| 258 |
\enquote{constructing}, you can use \cs{ExpandArgs} as explained in |
| 259 |
Section~\ref{sec:preconstructing-csnames} which also gives an example |
| 260 |
in which this is needed. |
| 261 |
|
| 262 |
\begin{decl} |
| 263 |
|\NewDocumentEnvironment| \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\ |
| 264 |
|\RenewDocumentEnvironment| \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\ |
| 265 |
|\ProvideDocumentEnvironment| \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\ |
| 266 |
|\DeclareDocumentEnvironment| \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} |
| 267 |
\end{decl} |
| 268 |
These commands work in the same way as \cs{NewDocumentCommand}, etc.\@, but |
| 269 |
create environments (\cs{begin}\arg{env} \ldots{} |
| 270 |
\cs{end}\arg{env}). Both the \meta{beg-code} and \meta{end-code} |
| 271 |
may access the arguments as defined by \meta{arg spec}. The arguments will be |
| 272 |
given following \cs{begin}\arg{env}. Any spaces at the start and end of the |
| 273 |
\arg{env} are removed before the definition takes place, thus |
| 274 |
\begin{verbatim} |
| 275 |
\NewDocumentEnvironment{foo} |
| 276 |
\end{verbatim} |
| 277 |
and |
| 278 |
\begin{verbatim} |
| 279 |
\NewDocumentEnvironment{ foo } |
| 280 |
\end{verbatim} |
| 281 |
both create the same \enquote{\texttt{foo}} environment. |
| 282 |
|
| 283 |
\subsection{Optional arguments} |
| 284 |
\label{sec:cmd:opt} |
| 285 |
|
| 286 |
In contrast to commands created using \LaTeXe{}'s \cs{newcommand}, optional |
| 287 |
arguments created using \cs{NewDocumentCommand} may safely be nested. Thus for |
| 288 |
example, following |
| 289 |
\begin{verbatim} |
| 290 |
\NewDocumentCommand\foo{om}{I grabbed `#1' and `#2'} |
| 291 |
\NewDocumentCommand\baz{o}{#1-#1} |
| 292 |
\end{verbatim} |
| 293 |
using the command as |
| 294 |
\begin{verbatim} |
| 295 |
\foo[\baz[stuff]]{more stuff} |
| 296 |
\end{verbatim} |
| 297 |
will print |
| 298 |
\begin{quote} |
| 299 |
I grabbed `stuff-stuff' and `more stuff' |
| 300 |
\end{quote} |
| 301 |
This is particularly useful when placing a command with an optional argument |
| 302 |
\emph{inside} the optional argument of a second command. |
| 303 |
|
| 304 |
When an optional argument is followed by a mandatory argument with the same |
| 305 |
delimiter, the parser issues a warning because the optional argument could not |
| 306 |
be omitted by the user, thus becoming in effect mandatory. This can apply to |
| 307 |
\texttt{o}, \texttt{d}, \texttt{O}, \texttt{D}, \texttt{s}, \texttt{t}, |
| 308 |
\texttt{e}, and \texttt{E} type arguments followed by \texttt{r} or |
| 309 |
\texttt{R}-type required arguments. |
| 310 |
|
| 311 |
The default for \texttt{O}, \texttt{D} and \texttt{E} arguments can be |
| 312 |
the result of grabbing another argument. Thus for example |
| 313 |
\begin{verbatim} |
| 314 |
\NewDocumentCommand\foo{O{#2} m} |
| 315 |
\end{verbatim} |
| 316 |
would use the mandatory argument as the default for the leading optional |
| 317 |
one. |
| 318 |
|
| 319 |
\subsection{Spacing and optional arguments} |
| 320 |
\label{sec:cmd:opt-space} |
| 321 |
|
| 322 |
\TeX{} will find the first argument after a function name irrespective of any |
| 323 |
intervening spaces. This is true for both mandatory and optional arguments. So |
| 324 |
|\foo[arg]| and \verb*|\foo [arg]| are equivalent. Spaces are also ignored when |
| 325 |
collecting arguments up to the last mandatory argument to be collected (as it |
| 326 |
must exist). So after |
| 327 |
\begin{verbatim} |
| 328 |
\NewDocumentCommand\foo{m o m}{ ... } |
| 329 |
\end{verbatim} |
| 330 |
the user input |\foo{arg1}[arg2]{arg3}| and \verb*|\foo{arg1} [arg2] {arg3}| |
| 331 |
will both be parsed in the same way. |
| 332 |
|
| 333 |
The behavior of optional arguments \emph{after} any mandatory arguments is |
| 334 |
selectable. The standard settings will allow spaces here, and thus with |
| 335 |
\begin{verbatim} |
| 336 |
\NewDocumentCommand\foobar{m o}{ ... } |
| 337 |
\end{verbatim} |
| 338 |
both |\foobar{arg1}[arg2]| and \verb*|\foobar{arg1} [arg2]| will find an |
| 339 |
optional argument. This can be changed by giving the modified |!| in the |
| 340 |
argument specification: |
| 341 |
\begin{verbatim} |
| 342 |
\NewDocumentCommand\foobar{m !o}{ ... } |
| 343 |
\end{verbatim} |
| 344 |
where \verb*|\foobar{arg1} [arg2]| will not find an optional argument. |
| 345 |
|
| 346 |
There is one subtlety here due to the difference in handling by \TeX{} of |
| 347 |
`control symbols', where the command name is made up of a single |
| 348 |
character, such as `\texttt{\textbackslash\textbackslash}'. |
| 349 |
Spaces are not ignored by \TeX{} here, |
| 350 |
and thus it is possible to require an optional argument directly follow such a |
| 351 |
command. The most common example is the use of \texttt{\textbackslash\textbackslash} |
| 352 |
in \pkg{amsmath} environments, which in the terms here would be defined as |
| 353 |
\begin{verbatim} |
| 354 |
\NewDocumentCommand\\{!s !o}{ ... } |
| 355 |
\end{verbatim} |
| 356 |
|
| 357 |
Also notable when using optional arguments in the last position is that \TeX{} |
| 358 |
will necessarily look ahead for the argument opening token. This means that |
| 359 |
the value of |\inputlineno| will be `out by one' if such a trailing optional |
| 360 |
argument is \emph{not} present and the command ends a line; it will be one |
| 361 |
greater than the line number containing the last mandatory argument. |
| 362 |
|
| 363 |
\subsection{`Embellishments'} |
| 364 |
\label{sec:cmd:embellishment} |
| 365 |
|
| 366 |
The \texttt{E}-type argument allows one default value per test token. This is |
| 367 |
achieved by giving a list of defaults for each entry in the list, for example: |
| 368 |
\begin{verbatim} |
| 369 |
E{^_}{{UP}{DOWN}} |
| 370 |
\end{verbatim} |
| 371 |
If the list of default values is \emph{shorter} than the list of test tokens, |
| 372 |
the special |-NoValue-| marker will be returned (as for the \texttt{e}-type |
| 373 |
argument). Thus for example |
| 374 |
\begin{verbatim} |
| 375 |
E{^_}{{UP}} |
| 376 |
\end{verbatim} |
| 377 |
has default \texttt{UP} for the |^| test character, but will return the |
| 378 |
|-NoValue-| marker as a default for |_|. This allows mixing of explicit |
| 379 |
defaults with testing for missing values. |
| 380 |
|
| 381 |
|
| 382 |
\subsection{Testing special values} |
| 383 |
\label{sec:cmd:special} |
| 384 |
|
| 385 |
Optional arguments make use of dedicated variables to return information about |
| 386 |
the nature of the argument received. |
| 387 |
|
| 388 |
|
| 389 |
|
| 390 |
\begin{decl} |
| 391 |
|\IfNoValueTF| \arg{arg} \arg{true code} \arg{false code} \\ |
| 392 |
|\IfNoValueT| \arg{arg} \arg{true code} \\ |
| 393 |
|\IfNoValueF| \arg{arg} \arg{false code} |
| 394 |
\end{decl} |
| 395 |
The \cs{IfNoValue(TF)} tests are used to check if \meta{argument} (|#1|, |
| 396 |
|#2|, \emph{etc.}) is the special |-NoValue-| marker. For example |
| 397 |
\begin{verbatim} |
| 398 |
\NewDocumentCommand\foo{o m} |
| 399 |
{% |
| 400 |
\IfNoValueTF {#1}% |
| 401 |
{\DoSomethingJustWithMandatoryArgument{#2}}% |
| 402 |
{\DoSomethingWithBothArguments{#1}{#2}}% |
| 403 |
} |
| 404 |
\end{verbatim} |
| 405 |
will use a different internal function if the optional argument |
| 406 |
is given than if it is not present. |
| 407 |
|
| 408 |
Note that three tests are available, depending on which outcome |
| 409 |
branches are required: \cs{IfNoValueTF}, \cs{IfNoValueT} and |
| 410 |
\cs{IfNoValueF}. |
| 411 |
|
| 412 |
As the \cs{IfNoValue(TF)} tests are expandable, it is possible to |
| 413 |
test these values later, for example at the point of typesetting or |
| 414 |
in an expansion context. |
| 415 |
|
| 416 |
It is important to note that |-NoValue-| is constructed such that it |
| 417 |
will \emph{not} match the simple text input |-NoValue-|, i.e.~that |
| 418 |
\begin{verbatim} |
| 419 |
\IfNoValueTF{-NoValue-} |
| 420 |
\end{verbatim} |
| 421 |
will be logically \texttt{false}. |
| 422 |
When two optional arguments follow each other (a syntax we typically |
| 423 |
discourage), it can make sense to allow users of the command to |
| 424 |
specify only the second argument by providing an empty first |
| 425 |
argument. |
| 426 |
\NEWdescription{2022/06/01} |
| 427 |
Rather than testing separately for emptiness and for |
| 428 |
|-NoValue-| it is then best to use the argument type~|O| with an |
| 429 |
empty default value, and then test for emptiness using the |
| 430 |
conditional \cs{IfBlankTF} (described below) instead. |
| 431 |
|
| 432 |
\begin{decl} |
| 433 |
|\IfValueTF| \arg{arg} \arg{true code} \arg{false code} \\ |
| 434 |
|\IfValueT| \arg{arg} \arg{true code} \\ |
| 435 |
|\IfValueF| \arg{arg} \arg{false code} |
| 436 |
\end{decl} |
| 437 |
The reverse form of the \cs{IfNoValue(TF)} tests are also available |
| 438 |
as \cs{IfValue(TF)}. The context will determine which logical |
| 439 |
form makes the most sense for a given code scenario. |
| 440 |
|
| 441 |
|
| 442 |
|
| 443 |
|
| 444 |
|
| 445 |
\begin{decl}[2022/06/01] |
| 446 |
|\IfBlankTF| \arg{arg} \arg{true code} \arg{false code} \\ |
| 447 |
|\IfBlankT| \arg{arg} \arg{true code} \\ |
| 448 |
|\IfBlankF| \arg{arg} \arg{false code} |
| 449 |
\end{decl} |
| 450 |
|
| 451 |
|
| 452 |
The \cs{IfNoValueTF} command chooses the \meta{true code} if the optional argument has not |
| 453 |
been used at all (and it returns the special \texttt{-NoValue-} |
| 454 |
marker), but not if it has been given an empty value. In contrast |
| 455 |
\cs{IfBlankTF} returns true if its argument is either truly empty or |
| 456 |
only contains one or more normal blanks. |
| 457 |
For example |
| 458 |
\begin{verbatim} |
| 459 |
\NewDocumentCommand\foo{m!o}{\par #1: |
| 460 |
\IfNoValueTF{#2} |
| 461 |
{No optional}% |
| 462 |
{% |
| 463 |
\IfBlankTF{#2} |
| 464 |
{Blanks in or empty}% |
| 465 |
{Real content in}% |
| 466 |
}% |
| 467 |
\space argument!} |
| 468 |
\foo{1}[bar] \foo{2}[ ] \foo{3}[] \foo{4}[\space] \foo{5} [x] |
| 469 |
\end{verbatim} |
| 470 |
results |
| 471 |
in the following output: |
| 472 |
\begin{quote} |
| 473 |
\NewDocumentCommand\foo{m!o}{\par #1: |
| 474 |
\IfNoValueTF{#2}{No optional}% |
| 475 |
{\IfBlankTF{#2}{Blanks in or empty}% |
| 476 |
{Real content in}}% |
| 477 |
\space argument!} |
| 478 |
\foo{1}[bar] \foo{2}[ ] \foo{3}[] \foo{4}[\space] \foo{5} [x] |
| 479 |
\end{quote} |
| 480 |
|
| 481 |
Note that the \cs{space} in (4) is considered real content---because it is |
| 482 |
a command and not a \enquote{space} character---even though it results |
| 483 |
in producing a space. You can also observe in (5) the effect of the |
| 484 |
\texttt{!} specifier, preventing the last \cs{foo} |
| 485 |
from interpreting \texttt{[x]} as its optional argument. |
| 486 |
|
| 487 |
|
| 488 |
|
| 489 |
|
| 490 |
\begin{decl} |
| 491 |
|\BooleanFalse| \\ |
| 492 |
|\BooleanTrue| |
| 493 |
\end{decl} |
| 494 |
The \texttt{true} and \texttt{false} flags set when searching for |
| 495 |
an optional character (using \texttt{s} or \texttt{t\meta{char}}) have |
| 496 |
names which are accessible outside of code blocks. |
| 497 |
|
| 498 |
\begin{decl} |
| 499 |
|\IfBooleanTF| \arg{arg} \arg{true code} \arg{false code} \\ |
| 500 |
|\IfBooleanT| \arg{arg} \arg{true code} \\ |
| 501 |
|\IfBooleanF| \arg{arg} \arg{false code} |
| 502 |
\end{decl} |
| 503 |
Used to test if \meta{argument} (|#1|, |#2|, \emph{etc.}) is |
| 504 |
\cs{BooleanTrue} or \cs{BooleanFalse}. For example |
| 505 |
\begin{verbatim} |
| 506 |
\NewDocumentCommand\foo{sm} |
| 507 |
{% |
| 508 |
\IfBooleanTF {#1}% |
| 509 |
{\DoSomethingWithStar{#2}}% |
| 510 |
{\DoSomethingWithoutStar{#2}}% |
| 511 |
} |
| 512 |
\end{verbatim} |
| 513 |
checks for a star as the first argument, then chooses the action to |
| 514 |
take based on this information. |
| 515 |
|
| 516 |
\subsection{Auto-converting to key--value format} |
| 517 |
\label{sec:cmd:keyval} |
| 518 |
|
| 519 |
Some document commands have a long history of accepting a `free text' optional |
| 520 |
argument, for example \cs{caption} and the sectioning commands \cs{section}, |
| 521 |
etc. Introducing more sophisticated (keyval) options to these commands |
| 522 |
therefore needs a method to interpret the optional argument \emph{either} as |
| 523 |
free text \emph{or} as a series of keyvals. This needs to take place |
| 524 |
during argument grabbing as there is a need for careful treatment of |
| 525 |
braces to obtain the correct result. |
| 526 |
|
| 527 |
The \texttt{=} modifier is available to allow \pkg{ltcmd} to correctly |
| 528 |
implement this process. The modifier guarantees that the argument will be |
| 529 |
passed to further code as a series of keyvals. To do that, the \texttt{=} |
| 530 |
should be followed by an argument containing the default key name. This is used |
| 531 |
as the key in a key--value pair \emph{if} the `raw' argument does \emph{not} |
| 532 |
have the correct form to be interpreted as a set of keyvals. |
| 533 |
|
| 534 |
Taking \cs{caption} as an example, with the demonstration implementation |
| 535 |
\begin{verbatim} |
| 536 |
\DeclareDocumentCommand\caption{s ={short-text} +O{#3} +m} |
| 537 |
{% |
| 538 |
\showtokens{Grabbed arguments:^^J(#2)^^Jand^^J(#3)}% |
| 539 |
} |
| 540 |
\end{verbatim} |
| 541 |
the default key name is \texttt{short-text}. When the command \cs{caption} is |
| 542 |
then used, if the optional argument is free text such as |
| 543 |
\begin{verbatim} |
| 544 |
\caption[Some short text]{A much longer and more detailed text for |
| 545 |
demonstration purposes} |
| 546 |
\end{verbatim} |
| 547 |
then the output will be |
| 548 |
\begin{verbatim} |
| 549 |
Grabbed arguments: |
| 550 |
(short-text={Some short text}) |
| 551 |
and |
| 552 |
(A much longer and more detailed text for demonstration purposes) |
| 553 |
\end{verbatim} |
| 554 |
On the other hand, if the caption is given with a keyval-form argument |
| 555 |
\begin{verbatim} |
| 556 |
\caption[label = cap:demo]% |
| 557 |
{A much longer and more detailed text for demonstration purposes} |
| 558 |
\end{verbatim} |
| 559 |
then this will be respected |
| 560 |
\begin{verbatim} |
| 561 |
Grabbed arguments: |
| 562 |
(label = cap:demo) |
| 563 |
and |
| 564 |
(A much longer and more detailed text for demonstration purposes) |
| 565 |
\end{verbatim} |
| 566 |
|
| 567 |
Interpretation as keyval form is determined by the presence of \texttt{=} |
| 568 |
characters within the argument. Those in inline math mode (enclosed within |
| 569 |
\verb|$...$| or \verb|\(...\)|) are ignored. An argument can be forced to be |
| 570 |
read as keyvals by including an empty entry at the start |
| 571 |
\begin{verbatim} |
| 572 |
\caption[=,This is now a keyval]% |
| 573 |
% ... |
| 574 |
\caption[This is not $=$ keyval]% |
| 575 |
\end{verbatim} |
| 576 |
|
| 577 |
This empty entry is \emph{not} passed to the underlying code, so will not lead |
| 578 |
to issues with keyval parsers that do not allow an empty key name. Any text-mode |
| 579 |
\texttt{=} signs will need to be braced to avoid being misinterpreted: this |
| 580 |
is likely most conveniently handled by bracing the entire argument |
| 581 |
\begin{verbatim} |
| 582 |
\caption[{Not = to a keyval!}]% |
| 583 |
\end{verbatim} |
| 584 |
which will be passed correctly as |
| 585 |
\begin{verbatim} |
| 586 |
Grabbed arguments: |
| 587 |
(short-text = {Not = to a keyval!}) |
| 588 |
\end{verbatim} |
| 589 |
|
| 590 |
\subsection{Argument processors} |
| 591 |
\label{sec:cmd:processors} |
| 592 |
|
| 593 |
Argument processor are applied to an argument \emph{after} it has been grabbed |
| 594 |
by the underlying system but before it is passed to \meta{code}. An argument |
| 595 |
processor can therefore be used to regularize input at an early stage, allowing |
| 596 |
the internal functions to be completely independent of input form. Processors |
| 597 |
are applied to user input and to default values for optional arguments, but |
| 598 |
\emph{not} to the special |-NoValue-| marker. |
| 599 |
|
| 600 |
Each argument processor is specified by the syntax \texttt{>}\marg{processor} |
| 601 |
in the argument specification. Processors are applied from right to left, so |
| 602 |
that |
| 603 |
\begin{verbatim} |
| 604 |
>{\ProcessorB} >{\ProcessorA} m |
| 605 |
\end{verbatim} |
| 606 |
would apply \cs{ProcessorA} followed by \cs{ProcessorB} to the tokens grabbed |
| 607 |
by the \texttt{m} argument. |
| 608 |
|
| 609 |
\begin{decl} |
| 610 |
|\SplitArgument| \arg{number} \arg{token(s)} |
| 611 |
\end{decl} |
| 612 |
This processor splits the argument given at each occurrence of the |
| 613 |
\meta{tokens} up to a maximum of \meta{number} tokens (thus |
| 614 |
dividing the input into $\text{\meta{number}} + 1$ parts). |
| 615 |
An error is given if too many \meta{tokens} are present in the |
| 616 |
input. The processed input is placed inside |
| 617 |
$\text{\meta{number}} + 1$ sets of braces for further use. |
| 618 |
If there are fewer than \arg{number} of \arg{tokens} in the argument |
| 619 |
then |-NoValue-| markers are added at the end of the processed |
| 620 |
argument. |
| 621 |
\begin{verbatim} |
| 622 |
\NewDocumentCommand\foo{>{\SplitArgument{2}{;}} m} |
| 623 |
{\InternalFunctionOfThreeArguments#1} |
| 624 |
\end{verbatim} |
| 625 |
If only a single character \meta{token} is used for the split, any |
| 626 |
category code $13$ (active) character matching the \meta{token} will |
| 627 |
be replaced before the split takes place. |
| 628 |
Spaces are trimmed at each end of each item parsed. |
| 629 |
|
| 630 |
The \texttt{E} argument type is somewhat special, because with a single |
| 631 |
\texttt{E} in the command declaration you may end up with several |
| 632 |
arguments in a command (one formal argument per embellishment token). |
| 633 |
Therefore, when an argument processor is applied to an |
| 634 |
\texttt{e}/\texttt{E}-type |
| 635 |
argument, all the arguments pass through that processor before being fed |
| 636 |
to the \meta{code}. For example, this command |
| 637 |
\begin{verbatim} |
| 638 |
\NewDocumentCommand\foo{ >{\TrimSpaces} e{_^} } |
| 639 |
{ [#1](#2) } |
| 640 |
\end{verbatim} |
| 641 |
applies \cs{TrimSpaces} to both arguments. |
| 642 |
|
| 643 |
\begin{decl} |
| 644 |
|\SplitList| \arg{token(s)} |
| 645 |
\end{decl} |
| 646 |
This processor splits the argument given at each occurrence of the |
| 647 |
\meta{token(s)} where the number of items is not fixed. Each item is |
| 648 |
then wrapped in braces within |#1|. The result is that the |
| 649 |
processed argument can be further processed using a mapping function |
| 650 |
(see below). |
| 651 |
\begin{verbatim} |
| 652 |
\NewDocumentCommand\foo{>{\SplitList{;}} m} |
| 653 |
{\MappingFunction#1} |
| 654 |
\end{verbatim} |
| 655 |
If only a single character \meta{token} is used for the split, it will |
| 656 |
take account of the possibility that the \meta{token} has been made active |
| 657 |
(category code~$13$) and will split at such tokens. |
| 658 |
Spaces are trimmed at each end of each item parsed. Exactly one set |
| 659 |
of braces will be stripped if an entire item is surrounded by them, |
| 660 |
i.e.~the following inputs and outputs result (each separate item as |
| 661 |
a brace group). |
| 662 |
\begin{verbatim} |
| 663 |
a ==> {a} |
| 664 |
{a} ==> {a} |
| 665 |
{a}b ==> {{a}b} |
| 666 |
a,b ==> {a}{b} |
| 667 |
{a},b ==> {a}{b} |
| 668 |
a,{b} ==> {a}{b} |
| 669 |
a,{b}c ==> {a}{{b}c} |
| 670 |
\end{verbatim} |
| 671 |
|
| 672 |
\begin{decl} |
| 673 |
|\ProcessList| \arg{list} \arg{tokens} |
| 674 |
\end{decl} |
| 675 |
To support \cs{SplitList}, the function \cs{ProcessList} is available |
| 676 |
to apply \meta{tokens} to every entry in a \meta{list}. The |
| 677 |
\meta{tokens} can be arbitrary contents that should expect one argument |
| 678 |
after it: the list entry. For example |
| 679 |
\begin{verbatim} |
| 680 |
\NewDocumentCommand\foo{>{\SplitList{;}} m} |
| 681 |
{\ProcessList{#1}{\SomeDocumentCommand}} |
| 682 |
\end{verbatim} |
| 683 |
or |
| 684 |
\begin{verbatim} |
| 685 |
\NewDocumentCommand\foo{>{\SplitList{;}} m} |
| 686 |
{\ProcessList{#1}{Abc \SomeDocumentCommand}} |
| 687 |
\end{verbatim} |
| 688 |
|
| 689 |
\begin{decl} |
| 690 |
|\ReverseBoolean| |
| 691 |
\end{decl} |
| 692 |
This processor reverses the logic of \cs{BooleanTrue} and |
| 693 |
\cs{BooleanFalse}, so that the example from earlier would become |
| 694 |
\begin{verbatim} |
| 695 |
\NewDocumentCommand\foo{>{\ReverseBoolean} s m} |
| 696 |
{% |
| 697 |
\IfBooleanTF#1% |
| 698 |
{\DoSomethingWithoutStar{#2}}% |
| 699 |
{\DoSomethingWithStar{#2}}% |
| 700 |
} |
| 701 |
\end{verbatim} |
| 702 |
|
| 703 |
\begin{decl} |
| 704 |
|\TrimSpaces| |
| 705 |
\end{decl} |
| 706 |
Removes any leading and trailing spaces (tokens with character code~$32$ |
| 707 |
and category code~$10$) for the ends of the argument. Thus for example |
| 708 |
declaring a function |
| 709 |
\begin{verbatim} |
| 710 |
\NewDocumentCommand\foo{>{\TrimSpaces} m} |
| 711 |
{\showtokens{#1}} |
| 712 |
\end{verbatim} |
| 713 |
and using it in a document as |
| 714 |
\begin{flushleft} |
| 715 |
\verb= =\verb*=\foo{ hello world }= |
| 716 |
\end{flushleft} |
| 717 |
will show `\verb*=hello world=' at the terminal, with the space at each |
| 718 |
end removed. \cs{TrimSpaces} will remove multiple spaces from the ends of |
| 719 |
the input in cases where these have been included such that the standard |
| 720 |
\TeX{} conversion of multiple spaces to a single space does not apply. |
| 721 |
|
| 722 |
\subsection{Body of an environment} |
| 723 |
\label{sec:cmd:body} |
| 724 |
|
| 725 |
While environments |\begin|\marg{environment}\ \dots{}\,|\end|\marg{environment} |
| 726 |
are typically used in cases where the code implementing the \meta{environment} |
| 727 |
does not need to access the contents of the environment (its `body'), |
| 728 |
it is sometimes useful to have the body as a standard argument. |
| 729 |
|
| 730 |
This is achieved by ending the argument specification with~\texttt{b}, which is |
| 731 |
a dedicated argument type for this situation. For instance |
| 732 |
\begin{verbatim} |
| 733 |
\NewDocumentEnvironment{twice}{O{\ttfamily} +b} |
| 734 |
{#2#1#2} {} |
| 735 |
\begin{twice}[\itshape] |
| 736 |
Hello world! |
| 737 |
\end{twice} |
| 738 |
\end{verbatim} |
| 739 |
typesets `Hello world!{\itshape Hello world!}'. |
| 740 |
|
| 741 |
The prefix |+| is used to allow multiple paragraphs in the environment's body. |
| 742 |
Argument processors can also be applied to \texttt{b}~arguments. By default, |
| 743 |
spaces are trimmed at both ends of the body: in the example there would |
| 744 |
otherwise be spaces coming from the ends the lines after |[\itshape]| and |
| 745 |
|world!|. Putting the prefix |!| before \texttt{b} suppresses space-trimming. |
| 746 |
|
| 747 |
When \texttt{b} is used in the argument specification, the last |
| 748 |
argument of the environment declaration (e.g., |
| 749 |
\cs{NewDocumentEnvironment}), which consists of an \meta{end code} to |
| 750 |
insert at |\end|\marg{environment}, is redundant since one can simply |
| 751 |
put that code at the end of the \meta{start code}. Nevertheless this |
| 752 |
(empty) \meta{end code} must be provided. |
| 753 |
|
| 754 |
Environments that use this feature can be nested. |
| 755 |
|
| 756 |
\subsection{Fully-expandable document commands\label{sec:ltcmd:expandable}} |
| 757 |
|
| 758 |
Document commands created using \cs{NewDocumentCommand}, etc.\@, are normally |
| 759 |
created so that they do not expand unexpectedly. This is done using engine |
| 760 |
features, so is more powerful than \LaTeXe{}'s \cs{protect} mechanism. There |
| 761 |
are \emph{very rare} occasion when it may be useful to create functions using a |
| 762 |
expansion-only grabber. This imposes a number of restrictions on the |
| 763 |
nature of the arguments accepted by a function, and the code it implements. |
| 764 |
This facility should only be used when \emph{necessary}. |
| 765 |
|
| 766 |
\begin{decl} |
| 767 |
|\NewExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\ |
| 768 |
|\RenewExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\ |
| 769 |
|\ProvideExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\ |
| 770 |
|\DeclareExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} |
| 771 |
\end{decl} |
| 772 |
This family of commands is used to create a document-level \meta{cmd}, |
| 773 |
which will grab its arguments in a fully-expandable manner. The |
| 774 |
argument specification for the function is given by \meta{arg spec}, |
| 775 |
and the \meta{cmd} will execute \meta{code}. In general, \meta{code} will |
| 776 |
also be fully expandable, although it is possible that this will |
| 777 |
not be the case (for example, a function for use in a table might |
| 778 |
expand so that \cs{omit} is the first non-expandable non-space token). |
| 779 |
|
| 780 |
Parsing arguments by pure expansion imposes a number of restrictions on |
| 781 |
both the type of arguments that can be read and the error checking |
| 782 |
available: |
| 783 |
\begin{itemize} |
| 784 |
\item The last argument (if any are present) must be one of the |
| 785 |
mandatory types \texttt{m}, \texttt{r} or \texttt{R}. |
| 786 |
\item The `verbatim' argument type \texttt{v} is not available. |
| 787 |
\item Argument processors (using \texttt{>}) are not available. |
| 788 |
\item It is not possible to differentiate between, for example |
| 789 |
|\foo[| and |\foo{[}|: in both cases the \texttt{[} will be |
| 790 |
interpreted as the start of an optional argument. As a |
| 791 |
result, checking for optional arguments is less robust than |
| 792 |
in the standard version. |
| 793 |
\end{itemize} |
| 794 |
|
| 795 |
\subsection{Commands at the start of tabular cells} |
| 796 |
|
| 797 |
Creating commands that are used at the start of tabular cells imposes |
| 798 |
some restrictions on the underlying implementation. The standard \LaTeX{} |
| 799 |
tabular environments (\texttt{tabular}, etc.) use a mechanism which requires |
| 800 |
that any command wrapping \cs{multicolumn} or similar must be |
| 801 |
`expandable'. This is \emph{not} the case for commands created using |
| 802 |
\cs{NewDocumentCommand}, etc., which as detailed in |
| 803 |
Section~\ref{sec:ltcmd:expandable} use an engine feature which prevents |
| 804 |
such `expansion'. Therefore, to create such wrappers for use at the start |
| 805 |
of tabular cells, you must use \cs{NewExpandableDocumentCommand}, for example |
| 806 |
\begin{verbatim} |
| 807 |
\NewExpandableDocumentCommand\MyMultiCol{m}{\multicolumn{3}{c}{#1}} |
| 808 |
\begin{tabular}{lcr} |
| 809 |
a & b & c \\ |
| 810 |
\MyMultiCol{stuff} \\ |
| 811 |
\end{tabular} |
| 812 |
\end{verbatim} |
| 813 |
|
| 814 |
\subsection{Using the verbatim argument types} |
| 815 |
|
| 816 |
As described above, the \texttt{v}-type argument may be viewed as similar to |
| 817 |
\cs{verb}. Before looking at exactly what that means, it is important to |
| 818 |
highlight some key differences. Most notably, \emph{grabbing} a verbatim-like |
| 819 |
argument is separate from \emph{typesetting} it: the latter is covered in the |
| 820 |
next section. |
| 821 |
|
| 822 |
When grabbing a \texttt{v}-type argument, \LaTeX{} first uses the kernel |
| 823 |
command \cs{dospecials} to turn off the \enquote{special} nature of characters. |
| 824 |
It then makes both spaces and tabs \enquote{active}, so that they can be given |
| 825 |
a custom definition. Any other characters are grabbed as-is: this means that if |
| 826 |
any characters have been made \enquote{special} and are not listed in |
| 827 |
\cs{dospecials}, an error will arise (see below). |
| 828 |
|
| 829 |
The characters that are grabbed as the argument are all those between two |
| 830 |
identical: in contrast to \cs{verb}, the characters \texttt{\textbackslash}, |
| 831 |
|{|, |}| and |%| \emph{cannot} be used as the delimiter character. If any of |
| 832 |
the grabbed tokens have \enquote{special} meaning, an error will be issued. |
| 833 |
|
| 834 |
For the \texttt{+v}-type argument, which allows line breaks within the |
| 835 |
argument, newline characters are converted into \cs{obeyedline} commands. The |
| 836 |
standard definition of \cs{obeyedline} is simple |\par|, thus allowing the |
| 837 |
grabbed tokens to be used directly in typesetting. A local redefinition of |
| 838 |
\cs{obeyedline} can be used to achieve other outputs. For example, to retain |
| 839 |
blank lines whilst typesetting, one could use |
| 840 |
\begin{verbatim} |
| 841 |
\renewcommand*\obeyedline{\mbox{}\par} |
| 842 |
\end{verbatim} |
| 843 |
More information about using these arguments in typesetting is in the following |
| 844 |
subsection. |
| 845 |
|
| 846 |
Some additional details that may be useful for those with more \TeX{} |
| 847 |
knowledge: do not worry if this does not make sense to you! Spaces and tabs are |
| 848 |
stored as active characters. In $8$-bit engines, non-ASCII characters are |
| 849 |
\enquote{active}, whilst other than the letters a--zA--Z, ASCII characters are |
| 850 |
\enquote{other}. In Unicode engines, non-ASCII codepoints will be either |
| 851 |
letters or \enquote{other}, based on the standard \LaTeX{} settings derived |
| 852 |
from Unicode data. For token-based comparisons, it is likely that the active |
| 853 |
spaces and tabs should be replaced: this can be done conveniently by expansion. |
| 854 |
|
| 855 |
\subsection{Typesetting verbatim-like material} |
| 856 |
|
| 857 |
In contrast to \cs{verb}, the \texttt{(+)v}-type argument is only about |
| 858 |
\emph{grabbing} the argument, not \emph{typesetting} it. As such, features that |
| 859 |
users often associate with \enquote{verbatim} are not automatically activated, |
| 860 |
e.g., selecting a monospaced font. Material grabbed by the \texttt{v}-type |
| 861 |
argument does not automatically suppress ligatures: with modern \TeX{} engines, |
| 862 |
this largely can be done without the token manipulation which \cs{verb} uses. |
| 863 |
(In \cs{verb}, ligatures are suppressed by making characters active and |
| 864 |
inserting a zero-width kern before the character itself.) |
| 865 |
|
| 866 |
The \cs{verb} command also selects a monospaced font: this is not intrinsic to |
| 867 |
verbatim material, so will need to be set up using for example \cs{ttfamily}. |
| 868 |
Similarly, the \texttt{verbatim} environment sets up the meaning of \cs{par} |
| 869 |
suitable for breaking lines. |
| 870 |
|
| 871 |
\subsection{Verbatim environments} |
| 872 |
\label{sec:cmd:verbenv} |
| 873 |
|
| 874 |
In some cases, when grabbing the body of an environment you will want the |
| 875 |
contents to be treated verbatim. This is available using the argument |
| 876 |
specification~\texttt{c}. Like the \texttt{b} specification, this has to be the |
| 877 |
last one. Thus for example |
| 878 |
\begin{verbatim} |
| 879 |
\NewDocumentEnvironment{MyVerbatim}{!O{\ttfamily} c} |
| 880 |
{\begin{center} #1 #2\end{center}} {} |
| 881 |
\begin{MyVerbatim}[\ttfamily\itshape] |
| 882 |
% Some code is shown here |
| 883 |
$y = mx + c$ |
| 884 |
\end{MyVerbatim} |
| 885 |
\end{verbatim} |
| 886 |
will typeset verbatim the content, thus: |
| 887 |
\NewDocumentEnvironment{MyVerbatim}{!O{\ttfamily} c} |
| 888 |
{\begin{center} #1 #2\end{center}} {} |
| 889 |
\begin{MyVerbatim}[\ttfamily\itshape] |
| 890 |
% Some code is shown here |
| 891 |
$y = mx + c$ |
| 892 |
\end{MyVerbatim} |
| 893 |
|
| 894 |
Since grabbing the entire contents verbatim will result in there being no |
| 895 |
\cs{par} tokens, newlines are always permitted: there is no need for a |
| 896 |
|+|~modifier here. As for the \texttt{v} specification, newlines are stored as |
| 897 |
\cs{obeyedline}. In a similar fashion to the \texttt{b}~specification, by |
| 898 |
default \emph{newlines} are trimmed at both ends of the body. Putting the |
| 899 |
prefix |!| before \texttt{c} suppresses this trimming. |
| 900 |
|
| 901 |
Collection of the body takes place on a line-by-line basis: content is |
| 902 |
collected up to the end-of-line in the source, then examined before storage. |
| 903 |
This means that the line ending the environment (containing in the example |
| 904 |
above |\end{MyVerbatim}|) cannot have any text \emph{after} the end of the |
| 905 |
environment. Text \emph{before} the end of environment is treated normally, |
| 906 |
but note that there is no trailing \cs{obeyedline} added if there is text here. |
| 907 |
Other than optional arguments, no text is allowed on the opening line of the |
| 908 |
environment. |
| 909 |
|
| 910 |
Special handling is applied to a \texttt{o}, \texttt{O}, \texttt{d} or |
| 911 |
\texttt{D}~specification argument immediately before an |
| 912 |
\texttt{c}~specification. This means that when the optional argument is absent, |
| 913 |
the first character of the next line will be read with the correctly applied |
| 914 |
verbatim category code. Issues may arise if \emph{multiple} optional arguments |
| 915 |
are used before a \texttt{c}~specification: this will only work reliably where |
| 916 |
the optional tokens are \enquote{other} characters. |
| 917 |
|
| 918 |
For technical reasons, we recommend that spaces are \emph{not} ignored when |
| 919 |
searching for an optional argument before an \texttt{c} specification: this can |
| 920 |
be achieved by adding the \texttt{!} modifier as shown in the example. |
| 921 |
However, this is left as a choice for the user. |
| 922 |
|
| 923 |
\subsection{Performance} |
| 924 |
|
| 925 |
For document commands where the argument specification is entirely |
| 926 |
comprised of |m| or |+m| entries (or is entirely empty), the internal structure |
| 927 |
created by \cs{NewDocumentCommand} is essentially as efficient |
| 928 |
as provided by |\newcommand(*)|. As such, document commands may replace |
| 929 |
constructs arising from \cs{newcommand}, etc., without a need to be concerned |
| 930 |
about performance. It should be noted that \cs{newcommand(*)} produces expandable |
| 931 |
results, so the direct replacement is \cs{NewExpandableDocumentCommand}; |
| 932 |
in most cases, however, it is better to use \cs{NewDocumentCommand} to |
| 933 |
give more robust structures. |
| 934 |
|
| 935 |
\subsection{Details about argument delimiters} |
| 936 |
|
| 937 |
In normal (non-expandable) commands, the delimited types look for the |
| 938 |
initial delimiter by peeking ahead (using \pkg{expl3}'s |\peek_...| |
| 939 |
functions) looking for the delimiter token. The token has to have the |
| 940 |
same meaning and `shape' of the token defined as delimiter. |
| 941 |
There are three possible cases of delimiters: character tokens, control |
| 942 |
sequence tokens, and active character tokens. For all practical purposes |
| 943 |
of this description, active character tokens will behave exactly as |
| 944 |
control sequence tokens. |
| 945 |
|
| 946 |
\subsubsection{Character tokens} |
| 947 |
|
| 948 |
A character token is characterized by its character code, and its meaning |
| 949 |
is the category code~(|\catcode|). When a command is defined, the meaning |
| 950 |
of the character token is fixed into the definition of the command and |
| 951 |
cannot change. A command will correctly see an argument delimiter if |
| 952 |
the open delimiter has the same character and category codes as at the |
| 953 |
time of the definition. For example in: |
| 954 |
\begin{verbatim} |
| 955 |
\NewDocumentCommand { \foobar } { D<>{default} } {(#1)} |
| 956 |
\foobar <hello> \par |
| 957 |
\char_set_catcode_letter:N < |
| 958 |
\foobar <hello> |
| 959 |
\end{verbatim} |
| 960 |
the output would be: |
| 961 |
\begin{verbatim} |
| 962 |
(hello) |
| 963 |
(default)<hello> |
| 964 |
\end{verbatim} |
| 965 |
as the open-delimiter |<| changed in meaning between the two calls to |
| 966 |
|\foobar|, so the second one doesn't see the |<| as a valid delimiter. |
| 967 |
Commands assume that if a valid open-delimiter was found, a matching |
| 968 |
close-delimiter will also be there. If it is not (either by being |
| 969 |
omitted or by changing in meaning), a low-level \TeX{} error is raised |
| 970 |
and the command call is aborted. |
| 971 |
|
| 972 |
\subsubsection{Control sequence tokens} |
| 973 |
|
| 974 |
A control sequence (or control character) token is characterized by |
| 975 |
its name, and its meaning is its definition. |
| 976 |
A token cannot have two different meanings at the same time. |
| 977 |
When a control sequence is defined as delimiter in a command, |
| 978 |
it will be detected as delimiter whenever the control sequence name |
| 979 |
is found in the document regardless of its current definition. |
| 980 |
For example in: |
| 981 |
\begin{verbatim} |
| 982 |
\cs_set:Npn \x { abc } |
| 983 |
\NewDocumentCommand { \foobar } { D\x\y{default} } {(#1)} |
| 984 |
\foobar \x hello\y \par |
| 985 |
\cs_set:Npn \x { def } |
| 986 |
\foobar \x hello\y |
| 987 |
\end{verbatim} |
| 988 |
the output would be: |
| 989 |
\begin{verbatim} |
| 990 |
(hello) |
| 991 |
(hello) |
| 992 |
\end{verbatim} |
| 993 |
with both calls to the command seeing the delimiter |\x|. |
| 994 |
|
| 995 |
\subsection{Creating new argument processors} |
| 996 |
|
| 997 |
\begin{decl} |
| 998 |
|\ProcessedArgument| |
| 999 |
\end{decl} |
| 1000 |
Argument processors allow manipulation of a grabbed argument before it is |
| 1001 |
passed to the underlying code. New processor implementations may be created |
| 1002 |
as functions which take one trailing argument, and which leave their result in |
| 1003 |
the \cs{ProcessedArgument} variable. For example, \cs{ReverseBoolean} is |
| 1004 |
defined as |
| 1005 |
\begin{verbatim} |
| 1006 |
\ExplSyntaxOn |
| 1007 |
\cs_new_protected:Npn \ReverseBoolean #1 |
| 1008 |
{ |
| 1009 |
\bool_if:NTF #1 |
| 1010 |
{ \tl_set:Nn \ProcessedArgument { \c_false_bool } } |
| 1011 |
{ \tl_set:Nn \ProcessedArgument { \c_true_bool } } |
| 1012 |
} |
| 1013 |
\ExplSyntaxOff |
| 1014 |
\end{verbatim} |
| 1015 |
[As an aside: the code is written in \pkg{expl3}, so we don't have to |
| 1016 |
worry about spaces creeping into the definition.] |
| 1017 |
|
| 1018 |
\section{Copying and showing (robust) commands and environments} |
| 1019 |
|
| 1020 |
If you want to (slightly) alter an existing command you may want to |
| 1021 |
save the current definition under a new name and then use that in a |
| 1022 |
new definition. If the existing command is robust, then the old trick of |
| 1023 |
using the low-level \cs{let} for this doesn't work, because it only |
| 1024 |
copies the top-level definition, but not the part that actually does |
| 1025 |
the work. As most \LaTeX{} commands are nowadays robust, \LaTeX{} |
| 1026 |
now offers some high-level declarations for this instead. |
| 1027 |
|
| 1028 |
However, please note that it is usually better to make use of |
| 1029 |
available hooks (e.g., the generic command or environment hooks), |
| 1030 |
instead of copying the current definition and thereby freezing it; see |
| 1031 |
the hook management documentation \texttt{lthooks-doc.pdf} for |
| 1032 |
details. |
| 1033 |
|
| 1034 |
\begin{decl} |
| 1035 |
|\NewCommandCopy| \arg{cmd} \arg{existing-cmd} \\ |
| 1036 |
|\RenewCommandCopy| \arg{cmd} \arg{existing-cmd} \\ |
| 1037 |
|\DeclareCommandCopy| \arg{cmd} \arg{existing-cmd} |
| 1038 |
\end{decl} |
| 1039 |
|
| 1040 |
This copies the definition of \meta{existing-cmd} to \meta{cmd}. After |
| 1041 |
this \meta{existing-cmd} can be redefined and \meta{cmd} |
| 1042 |
still works! This allows you to then provide a new definition for |
| 1043 |
\meta{existing-cmd} that makes use of \meta{cmd} (i.e., of its old |
| 1044 |
definition). For example, after |
| 1045 |
\begin{verbatim} |
| 1046 |
\NewCommandCopy\LaTeXorig\LaTeX |
| 1047 |
\RenewDocumentCommand\LaTeX{}{\textcolor{blue}{\LaTeXorig}} |
| 1048 |
\end{verbatim} |
| 1049 |
all \LaTeX{} logos generated with \cs{LaTeX} will come out in blue |
| 1050 |
(assuming you have a color package loaded). |
| 1051 |
|
| 1052 |
The differences between \cs{New...} and \cs{Renew...} are as |
| 1053 |
elsewhere: i.e., you get an error depending on whether or not |
| 1054 |
\meta{cmd} already exists, or in case of \cs{Declare...} it is copied |
| 1055 |
regardless. Note that there is no \cs{Provide...} declaration, because |
| 1056 |
that would be of limited value. |
| 1057 |
|
| 1058 |
|
| 1059 |
If the \meta{cmd} or \meta{existing-cmd} can't be provided as a single |
| 1060 |
token but need \enquote{constructing}, you can use \cs{ExpandArgs} |
| 1061 |
as explained in |
| 1062 |
Section~\ref{sec:preconstructing-csnames}. |
| 1063 |
|
| 1064 |
\begin{decl} |
| 1065 |
|\ShowCommand| \arg{cmd} |
| 1066 |
\end{decl} |
| 1067 |
|
| 1068 |
This displays the meaning of the \meta{cmd} on the terminal and then |
| 1069 |
stops (just like the primitive \cs{show}). The difference is that it |
| 1070 |
correctly shows the meaning of more complex commands, e.g., in case of |
| 1071 |
robust commands it displays not only the top-level definition but |
| 1072 |
also the actual payload code and in case of commands declared with |
| 1073 |
\cs{NewDocumentCommand}, etc.\ it also gives you detailed information |
| 1074 |
about the argument signature. |
| 1075 |
|
| 1076 |
\begin{decl} |
| 1077 |
|\NewEnvironmentCopy| \arg{env} \arg{existing-env} \\ |
| 1078 |
|\RenewEnvironmentCopy| \arg{env} \arg{existing-env} \\ |
| 1079 |
|\DeclareEnvironmentCopy| \arg{env} \arg{existing-env} |
| 1080 |
\end{decl} |
| 1081 |
|
| 1082 |
This copies the definition for environment \meta{existing-env} to |
| 1083 |
\meta{env} (both the beginning and end code), i.e., it is simply |
| 1084 |
applying \cs{NewCommandCopy} twice to the internal commands that |
| 1085 |
define an environment, i.e., \cs{}\meta{env} and \cs{end}\meta{env}. |
| 1086 |
The differences between \cs{New...}, \cs{Renew...}, and |
| 1087 |
\cs{Declare...} are the usual ones. |
| 1088 |
|
| 1089 |
\begin{decl} |
| 1090 |
|\ShowEnvironment| \arg{env} |
| 1091 |
\end{decl} |
| 1092 |
This displays the meaning of the begin and end code for environment \meta{env}. |
| 1093 |
|
| 1094 |
|
| 1095 |
|
| 1096 |
|
| 1097 |
\section[Preconstructing command names \\ (or otherwise expanding arguments)] |
| 1098 |
{Preconstructing command names (or otherwise expanding arguments)} |
| 1099 |
\label{sec:preconstructing-csnames} |
| 1100 |
|
| 1101 |
When declaring new commands with \cs{NewDocumentCommand} or |
| 1102 |
\cs{NewCommandCopy} or similar, it is sometimes necessary to |
| 1103 |
``construct'' the csname. As a general mechanism the L3 programming |
| 1104 |
layer has \cs{exp_args:N...} for this, but there is no mechanism for |
| 1105 |
it if \cs{ExplSyntaxOn} is not active (and mixing programming and user |
| 1106 |
interface level commands is not a good approach anyhow). We therefore |
| 1107 |
offer a mechanism to access this ability using CamelCase naming. |
| 1108 |
|
| 1109 |
\begin{decl} |
| 1110 |
|\UseName| \arg{string} \\ |
| 1111 |
|\ExpandArgs| \arg{spec} \arg{cmd} \arg{arg1} \dots |
| 1112 |
\end{decl} |
| 1113 |
|
| 1114 |
\cs{UseName} turns the \meta{string} directly into a csname and |
| 1115 |
then executes it: this is equivalent to the long-standing |
| 1116 |
\LaTeXe{} internal command \cs{@nameuse}, or the L3 programming |
| 1117 |
equivalent \cs{use:c}. \cs{ExpandArgs} takes a \meta{spec} which |
| 1118 |
describes how to expand the \meta{arguments}, carries out these |
| 1119 |
operations then executes the \meta{cmd}. The \meta{spec} uses |
| 1120 |
the descriptions offered by the L3 programming layer, and the |
| 1121 |
relevant \cs{exp_args:N...} function must exist. Common cases will |
| 1122 |
have a \meta{spec} of \texttt{c}, \texttt{cc} or \texttt{Nc}: see below. |
| 1123 |
|
| 1124 |
As an example, the following declaration provides a method to generate |
| 1125 |
copyedit commands: |
| 1126 |
\begin{verbatim} |
| 1127 |
\NewDocumentCommand\newcopyedit{mO{red}} |
| 1128 |
{% |
| 1129 |
\newcounter{todo#1}% |
| 1130 |
\ExpandArgs{c}\NewDocumentCommand{#1}{s m}% |
| 1131 |
{% |
| 1132 |
\stepcounter{todo#1}% |
| 1133 |
\IfBooleanTF {##1}% |
| 1134 |
{\todo[color=#2!10]{\UseName{thetodo#1}: ##2}}% |
| 1135 |
{\todo[inline,color=#2!10]{\UseName{thetodo#1}: ##2}}% |
| 1136 |
}% |
| 1137 |
} |
| 1138 |
\end{verbatim} |
| 1139 |
Given that declaration you can then write |
| 1140 |
\verb/\newcopyedit{note}[blue]/ which defines the command \cs{note} |
| 1141 |
and the corresponding counter for you. |
| 1142 |
|
| 1143 |
A second example is to copy a command by string name using |
| 1144 |
\cs{NewCommandCopy}: here we might need to construct both command |
| 1145 |
names. |
| 1146 |
\begin{verbatim} |
| 1147 |
\NewDocumentCommand\savebyname{m} |
| 1148 |
{\ExpandArgs{cc}\NewCommandCopy{saved#1}{#1}} |
| 1149 |
\end{verbatim} |
| 1150 |
|
| 1151 |
In the \meta{spec} each \texttt{c} stands for one argument that is |
| 1152 |
turned into a `\texttt{c}'ommand. An \texttt{n} represents a |
| 1153 |
`\texttt{n}'ormal argument that is not altered and \texttt{N} stands for |
| 1154 |
a `\texttt{N}'ormal argument which is also left unchanged, but one |
| 1155 |
consisting only of a single token (and usually unbraced). Thus, to |
| 1156 |
construct a command from a string only for the second argument of |
| 1157 |
\cs{NewCommandCopy} you would write |
| 1158 |
\begin{verbatim} |
| 1159 |
\ExpandArgs{Nc}\NewCommandCopy\mysectionctr{c@section} |
| 1160 |
\end{verbatim} |
| 1161 |
There are several other single letters supported in the L3 programming |
| 1162 |
layer that \emph{could} be used in the \meta{spec} to manipulate |
| 1163 |
arguments in other ways. If you are interested, take a look at the |
| 1164 |
\enquote{Argument expansion} section in the L3 programming layer |
| 1165 |
documentation in \texttt{interface3.pdf}. |
| 1166 |
|
| 1167 |
|
| 1168 |
|
| 1169 |
\section{Expandable floating point (and other) calculations} |
| 1170 |
|
| 1171 |
The \LaTeX3 programming layer which is part of the format offers a |
| 1172 |
rich interface to manipulate floating point variables and values. To |
| 1173 |
allow for (simpler) applications to use this on document-level or in |
| 1174 |
packages otherwise not making use of the L3 programming layer a few |
| 1175 |
interface commands are made available. |
| 1176 |
|
| 1177 |
|
| 1178 |
\begin{decl} |
| 1179 |
|\fpeval| \arg{floating point expression} |
| 1180 |
\end{decl} |
| 1181 |
|
| 1182 |
The expandable command \cs{fpeval} takes as its argument a floating |
| 1183 |
point expression and produces a result using the normal rules of |
| 1184 |
mathematics. As this command is expandable it can be used where \TeX{} |
| 1185 |
requires a number and for example within a low-level \cs{edef} operation |
| 1186 |
to give a purely numerical result. |
| 1187 |
|
| 1188 |
|
| 1189 |
|
| 1190 |
Briefly, the floating point expressions may comprise: |
| 1191 |
\begin{itemize} |
| 1192 |
\item Basic arithmetic: addition $x\fpbin{+}y$, subtraction $x\fpbin{-}y$, |
| 1193 |
multiplication $x\fpbin{*}y$, division $x\fpbin{/}y$, square root~$\fpop{sqrt}{x}$, |
| 1194 |
and parentheses. |
| 1195 |
\item Comparison operators: $x\fprel{<}y$, |
| 1196 |
$x\fprel{<=}y$, $x\fprel{>?}y$, |
| 1197 |
$x\fprel{!=}y$ \emph{etc.} |
| 1198 |
|
| 1199 |
The relation $x\fprel{?}y$ is true exactly if one or both operands is~\nan{} or is |
| 1200 |
a tuple, unless they are equal tuples. Each \meta{relation} |
| 1201 |
can be any (non-empty) combination of |<|, |=|, |>|, and~|?|, plus |
| 1202 |
an optional leading~|!| (which negates the \meta{relation}), with |
| 1203 |
the restriction that the negated \meta{relation} may not start with~|?|. |
| 1204 |
\item Boolean logic: sign $\fpop{sign} x$, |
| 1205 |
negation $\fpop{!}x$, conjunction |
| 1206 |
$x\fprel{\&\&}y$, disjunction $x\fprel{\string|\string|}y$, ternary |
| 1207 |
operator $x\fprel{?}y\fprel{:}z$. |
| 1208 |
\item Exponentials: $\fpop{exp} x$, $\fpop{ln} x$, $x\mathord{\texttt{\^{}}}y$. |
| 1209 |
\item Integer factorial: $\fpop{fact} x$. |
| 1210 |
\item Trigonometry: $\fpop{sin} x$, $\fpop{cos} x$, $\fpop{tan} x$, $\fpop{cot} x$, $\fpop{sec} |
| 1211 |
x$, $\fpop{csc} x$ expecting their arguments in radians, and |
| 1212 |
$\fpop{sind} x$, $\fpop{cosd} x$, |
| 1213 |
$\fpop{tand} x$, $\fpop{cotd} x$, |
| 1214 |
$\fpop{secd} x$, $\fpop{cscd} x$ expecting their |
| 1215 |
arguments in degrees. |
| 1216 |
\item Inverse trigonometric functions: $\fpop{asin} x$, |
| 1217 |
$\fpop{acos} x$, $\fpop{atan} x$, |
| 1218 |
$\fpop{acot} x$, $\fpop{asec} x$, |
| 1219 |
$\fpop{acsc} x$ giving a result in radians, and |
| 1220 |
$\fpop{asind} x$, $\fpop{acosd} x$, |
| 1221 |
$\fpop{atand} x$, $\fpop{acotd} x$, |
| 1222 |
$\fpop{asecd} x$, $\fpop{acscd} x$ giving a result |
| 1223 |
in degrees. |
| 1224 |
\item Extrema: $\fpop{max}(x_{1},x_{2},\ldots)$, $\fpop{min}(x_{1},x_{2},\ldots)$, |
| 1225 |
$\fpop{abs}(x)$. |
| 1226 |
\item Rounding functions, controlled by two optional |
| 1227 |
values, $n$ (number of places, $0$ by default) and |
| 1228 |
$t$ (behavior on a tie, $\nan$ by default): |
| 1229 |
\begin{itemize} |
| 1230 |
\item $\fpop{trunc}(x,n)$ rounds towards zero, |
| 1231 |
\item $\fpop{floor}(x,n)$ rounds towards~$-\infty$, |
| 1232 |
\item $\fpop{ceil}(x,n)$ rounds towards~$+\infty$, |
| 1233 |
\item $\fpop{round}(x,n,t)$ rounds to the closest value, with |
| 1234 |
ties rounded to an even value by default, towards zero if $t=0$, |
| 1235 |
towards $+\infty$ if $t>0$ and towards $-\infty$ if $t<0$. |
| 1236 |
\end{itemize} |
| 1237 |
\item Random numbers: $\fpop{rand}()$, $\fpop{randint}(m,n)$. |
| 1238 |
\item Constants: \texttt{pi}, \texttt{deg} (one degree in radians). |
| 1239 |
\item Dimensions, automatically expressed in points, \emph{e.g.}, |
| 1240 |
\texttt{pc} is~$12$. |
| 1241 |
\item Automatic conversion (no need for \cs{number}) of |
| 1242 |
integer, dimension, and skip variables to floating points numbers, |
| 1243 |
expressing dimensions in points and ignoring the stretch and |
| 1244 |
shrink components of skips. |
| 1245 |
\item Tuples: $(x_1,\ldots{},x_n)$ that can be added together, |
| 1246 |
multiplied or divided by a floating point number, and nested. |
| 1247 |
\end{itemize} |
| 1248 |
|
| 1249 |
An example of use could be the following: |
| 1250 |
\begin{verbatim} |
| 1251 |
\LaTeX{} can now compute: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3} |
| 1252 |
= \fpeval{sin(3.5)/2 + 2e-3} $. |
| 1253 |
\end{verbatim} |
| 1254 |
which produces the following output: |
| 1255 |
\begin{quote} |
| 1256 |
\LaTeX{} can now compute: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3} |
| 1257 |
= \fpeval{sin(3.5)/2 + 2e-3} $. |
| 1258 |
\end{quote} |
| 1259 |
|
| 1260 |
\begin{decl} |
| 1261 |
|\inteval| \arg{integer expression} |
| 1262 |
\end{decl} |
| 1263 |
|
| 1264 |
The expandable command \cs{inteval} takes as its argument an integer |
| 1265 |
expression and produces a result using the normal rules of |
| 1266 |
mathematics with some restrictions, see below. The operations |
| 1267 |
recognized are |+|, |-|, |*| and |/| plus parentheses. As this |
| 1268 |
command is expandable it can be used where \TeX{} requires a number |
| 1269 |
and for example within a low-level \cs{edef} operation to give a |
| 1270 |
purely numerical result. |
| 1271 |
|
| 1272 |
This is basically a thin wrapper for the primitive \cs{numexpr} |
| 1273 |
command and therefore has some syntax restrictions. These are: |
| 1274 |
\begin{itemize} |
| 1275 |
\item \texttt{/} denotes division rounded to the closest integer with |
| 1276 |
ties rounded away from zero; |
| 1277 |
\item there is an error and the overall expression evaluates to zero |
| 1278 |
whenever the absolute value of any intermediate result exceeds |
| 1279 |
$2^{31}-1$, except in the case of scaling operations |
| 1280 |
$a$\texttt{*}$b$\texttt{/}$c$, for which $a$\texttt{*}$b$ may be |
| 1281 |
arbitrarily large; |
| 1282 |
\item parentheses may not appear after unary \texttt{+} or |
| 1283 |
\texttt{-}, namely placing \texttt{+(} or \texttt{-(} at the start |
| 1284 |
of an expression or after \texttt{+}, \texttt{-}, \texttt{*}, |
| 1285 |
\texttt{/} or~\texttt{(} leads to an error. |
| 1286 |
\end{itemize} |
| 1287 |
|
| 1288 |
An example of use could be the following. |
| 1289 |
\begin{verbatim} |
| 1290 |
\LaTeX{} can now compute: The sum of the numbers is $\inteval{1 + 2 + 3}$. |
| 1291 |
\end{verbatim} |
| 1292 |
which results in |
| 1293 |
\enquote{\LaTeX{} can now compute: The sum of the numbers is $\inteval{1 + 2 + 3}$.} |
| 1294 |
|
| 1295 |
|
| 1296 |
\begin{decl} |
| 1297 |
|\dimeval| \arg{dimen expression} \qquad |
| 1298 |
|\skipeval| \arg{skip expression} |
| 1299 |
\end{decl} |
| 1300 |
|
| 1301 |
Similar to \cs{inteval} but computing a length (\texttt{dimen}) or a |
| 1302 |
rubber length (\texttt{skip}) value. Both are thin wrappers around |
| 1303 |
the corresponding engine primitives, which makes them fast, but |
| 1304 |
therefore shows the same syntax peculiars as discussed |
| 1305 |
above. Nevertheless, in practice they are usually sufficient. For |
| 1306 |
example |
| 1307 |
\begin{verbatim} |
| 1308 |
\NewDocumentCommand\calculateheight{m}{% |
| 1309 |
\setlength\textheight{\dimeval{\topskip+\baselineskip*\inteval{#1-1}}}} |
| 1310 |
\end{verbatim} |
| 1311 |
sets the \cs{textheight} to the appropriate value if a page should |
| 1312 |
hold a specific number of text lines. Thus after |\calculateheight{40}| |
| 1313 |
it is set to \dimeval{\topskip+\baselineskip*\inteval{40-1}}, given |
| 1314 |
the values \cs{topskip} (\dimeval{\topskip}) and \cs{baselineskip} |
| 1315 |
(\dimeval{\baselineskip}) in the current document. |
| 1316 |
|
| 1317 |
\section{Expandable \cs{input} equivalent} |
| 1318 |
|
| 1319 |
\begin{decl} |
| 1320 |
|\expandableinput| \arg{filename} |
| 1321 |
\end{decl} |
| 1322 |
The \LaTeX{} definition of \cs{input} cannot be used in places where \TeX{} is |
| 1323 |
performing expansion: the classic example is at the start of a tabular cell. |
| 1324 |
There are a number of reasons for this: the key ones are that \cs{input} |
| 1325 |
records which files are read and provides pre- and post-file hooks. |
| 1326 |
|
| 1327 |
To support the need to carry out file input in expansion contexts, the command |
| 1328 |
\cs{expandableinput} is available: this skips recording the file name and does |
| 1329 |
not apply any file hooks, but otherwise behaves like \cs{input}. In particular, |
| 1330 |
it still uses \cs{input@path} when doing file lookup. |
| 1331 |
|
| 1332 |
\section{Case changing} |
| 1333 |
|
| 1334 |
\begin{decl} |
| 1335 |
|\MakeUppercase| \oarg{keyvals} \arg{text} \\ |
| 1336 |
|\MakeLowercaes| \oarg{keyvals} \arg{text} \\ |
| 1337 |
|\MakeTitlecase| \oarg{keyvals} \arg{text} |
| 1338 |
\end{decl} |
| 1339 |
\TeX{} provides two primitives \cs{uppercase} and \cs{lowercase} for changing |
| 1340 |
the case of text. However, these have a range of limitations: they only change |
| 1341 |
the case of explicit characters, do not account for the surrounding context, do |
| 1342 |
not support UTF-8 input with 8-bit engines, etc. To overcome this problem, |
| 1343 |
\LaTeX{} provides the commands \cs{MakeUppercase}, \cs{MakeLowercase} and |
| 1344 |
\cs{MakeTitlecase}: these offer significant enhancement over the \TeX{} |
| 1345 |
primitives. These commands are engine-robust (\cs{protected}), and so |
| 1346 |
can be used in moving arguments. |
| 1347 |
|
| 1348 |
Upper- and lower-casing are well-understood in general conversation. |
| 1349 |
Titlecasing here follows the definition given by the Unicode Consortium: the |
| 1350 |
first character of the input will be converted to (broadly) uppercase, and the |
| 1351 |
rest of the input to lowercase. The full range of Unicode UTF-8 input can be |
| 1352 |
supported. |
| 1353 |
\begin{flushleft} |
| 1354 |
\begin{tabular}{@{}ll} |
| 1355 |
|\MakeUppercase{hello WORLD ßüé}| & \MakeUppercase{hello WORLD ßüé} \\ |
| 1356 |
|\MakeLowercase{hello WORLD ßüé}| & \MakeLowercase{hello WORLD ßüé} \\ |
| 1357 |
|\MakeTitlecase{hello WORLD ßüé}| & \MakeTitlecase{hello WORLD ßüé} \\ |
| 1358 |
\end{tabular} |
| 1359 |
\end{flushleft} |
| 1360 |
|
| 1361 |
The case-changing commands take an optional argument which can be used to |
| 1362 |
tailor the output. This optional argument accepts the key \texttt{locale}, also |
| 1363 |
available under the alias \texttt{lang}, which can be used to give a language |
| 1364 |
identifier in BCP-47 format. This is then applied to select language-specific |
| 1365 |
features during case-changing. |
| 1366 |
|
| 1367 |
For titlecasing, the key \texttt{words} may also be used: this |
| 1368 |
takes a choice of \texttt{first} or \texttt{all}. The standard |
| 1369 |
setting is \texttt{first}, and means that only the very first |
| 1370 |
\enquote{letter} is (broadly) uppercased. The alternative, |
| 1371 |
\texttt{all}, means that the input is divided at each space, and |
| 1372 |
for each word that results, the first letter is uppercased. For |
| 1373 |
example |
| 1374 |
\begin{verbatim} |
| 1375 |
\MakeTitlecase[words = first]{some words} |
| 1376 |
\MakeTitlecase[words = all]{some words} |
| 1377 |
\end{verbatim} |
| 1378 |
gives \enquote{\MakeTitlecase[words = first]{some words} |
| 1379 |
\MakeTitlecase[words = all]{some words}}. |
| 1380 |
|
| 1381 |
The input given to these commands is \enquote{expanded} before case changing is |
| 1382 |
applied. This means that any commands within the input that convert to pure |
| 1383 |
text will be case changed. Mathematical content is automatically excluded, as |
| 1384 |
are the arguments to the commands \cs{label}, \cs{ref}, \cs{cite}, \cs{begin} |
| 1385 |
and \cs{end}. Additional exclusions can be added using the command |
| 1386 |
\cs{AddToNoCaseChangeList}. Input can be excluded from case changing using the |
| 1387 |
command \cs{NoCaseChange}. |
| 1388 |
\begin{flushleft} |
| 1389 |
\begin{tabular}{@{}ll} |
| 1390 |
|\MakeUppercase{Some text $y = mx + c$}| |
| 1391 |
& \MakeUppercase{Some text $y = mx + c$} \\ |
| 1392 |
|\MakeUppercase{\NoCaseChange{iPhone}}| |
| 1393 |
& \MakeLowercase{\NoCaseChange{iPhone}} \\ |
| 1394 |
\end{tabular} |
| 1395 |
\end{flushleft} |
| 1396 |
|
| 1397 |
Individual words can be excluded globally from case changing using the |
| 1398 |
commands \cs{DeclareLowercaseExclusions}, \cs{DeclareTitlecaseExclusions}, |
| 1399 |
and \cs{DeclareUppercaseExclusions}, each of which take a comma-seperated |
| 1400 |
list of words to be excluded. For example, to titlecase in English in the |
| 1401 |
manner often seen for book titles, one might use |
| 1402 |
\begin{verbatim} |
| 1403 |
\DeclareTitlecaseExclusions{a,an,and,on,of,the} |
| 1404 |
\MakeTitlecase[words = all]{Of mice and men} |
| 1405 |
\MakeTitlecase[words = all]{The mill on the floss} |
| 1406 |
\MakeTitlecase[words = all]{The comedy of errors} |
| 1407 |
\end{verbatim} |
| 1408 |
to obtain |
| 1409 |
\begin{flushleft} |
| 1410 |
\DeclareTitlecaseExclusions{a,an,and,on,of,the}% |
| 1411 |
\MakeTitlecase[words = all]{Of mice and men} \\ |
| 1412 |
\MakeTitlecase[words = all]{The mill on the floss} \\ |
| 1413 |
\MakeTitlecase[words = all]{The comedy of errors} |
| 1414 |
\end{flushleft} |
| 1415 |
|
| 1416 |
To allow robust commands to be used within case changing \emph{and} to produce |
| 1417 |
the expected output, two additional control commands are available. |
| 1418 |
\cs{CaseSwitch} allows the user to specify the result for the four possible |
| 1419 |
cases |
| 1420 |
\begin{itemize} |
| 1421 |
\item No case changing |
| 1422 |
\item Uppercasing |
| 1423 |
\item Lowercasing |
| 1424 |
\item Titlecasing (only applies for the start of the input) |
| 1425 |
\end{itemize} |
| 1426 |
|
| 1427 |
The command \cs{DeclareCaseChangeEquivalent} provides a way to substitute a |
| 1428 |
command by an alternative version when it is found inside a case changing |
| 1429 |
situation. There are three commands for customising the case changing of |
| 1430 |
codepoints |
| 1431 |
\begin{decl} |
| 1432 |
|\DeclareLowercaseMapping| \oarg{locale} \arg{codepoint} \arg{output} \\ |
| 1433 |
|\DeclareTitlecaseMapping| \oarg{locale} \arg{codepoint} \arg{output} \\ |
| 1434 |
|\DeclareUppercaseMapping| \oarg{locale} \arg{codepoint} \arg{output} |
| 1435 |
\end{decl} |
| 1436 |
All three take a \meta{codepoint} (as an integer expression) and will |
| 1437 |
result in the \meta{output} being produced under the appropriate case changing |
| 1438 |
operation. The optional \meta{locale} can be given if the mapping should only |
| 1439 |
apply to a specific one: this is given in BCP-47 format |
| 1440 |
(\url{https://en.wikipedia.org/wiki/IETF_language_tag}). For example, |
| 1441 |
the kernel customises the mapping for U+01F0 (\v{j}) when uppercasing in |
| 1442 |
8-bit engines: |
| 1443 |
\begin{verbatim} |
| 1444 |
\DeclareUppercaseMapping{"01F0}{\v{J}} |
| 1445 |
\end{verbatim} |
| 1446 |
as there is no pre-composed \v{J} character, and this is problematic if |
| 1447 |
the engine does not support Unicode natively. Similarly, to set a locale |
| 1448 |
\texttt{xx} to behave in the same way as Turkish and retain the difference |
| 1449 |
between dotted- and dotless-i, one could use for example |
| 1450 |
\begin{verbatim} |
| 1451 |
\DeclareLowercaseMapping[xx]{"0049}{\i} |
| 1452 |
\DeclareLowercaseMapping[xx]{"0130}{i} |
| 1453 |
\DeclareUppercaseMapping[xx]{"0069}{\.{I}} |
| 1454 |
\DeclareUppercaseMapping[xx]{"0131}{I} |
| 1455 |
\end{verbatim} |
| 1456 |
|
| 1457 |
\section{Support for problem solving} |
| 1458 |
|
| 1459 |
\begin{decl} |
| 1460 |
|\listfiles| \oarg{options} |
| 1461 |
\end{decl} |
| 1462 |
|
| 1463 |
If this command is placed in the preamble then a list of the files |
| 1464 |
read in (as a result of processing the document) will be displayed |
| 1465 |
on the terminal (and in the log file) at the end of the run. Where |
| 1466 |
possible, a short description will also be produced. These descriptions |
| 1467 |
will (hopefully) include the descriptions, dates and version numbers |
| 1468 |
for package and class files. |
| 1469 |
|
| 1470 |
Sometimes, it may be that a local edit has been made to a package or |
| 1471 |
class file (or rather a copy of such a file). To allow these cases to |
| 1472 |
be identified, \cs{listfiles} takes an optional argument which allows |
| 1473 |
adjustment of the information printed using a key--value approach |
| 1474 |
\begin{description} |
| 1475 |
\item[\texttt{hashes}] Adds the MD5 hash for each file to the |
| 1476 |
information printed |
| 1477 |
\item[\texttt{sizes}] Adds the file size for each file to the |
| 1478 |
information printed |
| 1479 |
\end{description} |
| 1480 |
Note that as Windows and Unix use different line endings (LF \emph{versus} LF |
| 1481 |
CR), the hashes and file sizes from the two systems will not be the same. As |
| 1482 |
such, you should compare these values between operating systems of the same |
| 1483 |
type. |
| 1484 |
|
| 1485 |
\emph{Warning}: this command will list only files which were read |
| 1486 |
using \LaTeX{} commands such as |\input|\arg{file} or |
| 1487 |
|\include|\arg{file}. If the file was read using the primitive \TeX{} |
| 1488 |
syntax |\input |\emph{file} (without |{ }| braces around the file name) |
| 1489 |
then it will not be listed; failure to use the \LaTeX{} form with the |
| 1490 |
braces can cause more severe problems, possibly leading to overwriting |
| 1491 |
important files, so \textbf{always put in the braces}. |
| 1492 |
|
| 1493 |
\end{document} |