Debian Codegraph @

texmf-dist/doc/latex/base/usrguide.tex

raw
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}