summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/usrguide3.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/base/usrguide3.tex')
-rw-r--r--macros/latex-dev/base/usrguide3.tex1112
1 files changed, 0 insertions, 1112 deletions
diff --git a/macros/latex-dev/base/usrguide3.tex b/macros/latex-dev/base/usrguide3.tex
deleted file mode 100644
index a148c77ed5..0000000000
--- a/macros/latex-dev/base/usrguide3.tex
+++ /dev/null
@@ -1,1112 +0,0 @@
-% \iffalse meta-comment
-%
-% Copyright (C) 2020-2022
-% The LaTeX Project and any individual authors listed elsewhere
-% in this file.
-%
-% This file is part of the LaTeX base system.
-% -------------------------------------------
-%
-% It may be distributed and/or modified under the
-% conditions of the LaTeX Project Public License, either version 1.3c
-% of this license or (at your option) any later version.
-% The latest version of this license is in
-% http://www.latex-project.org/lppl.txt
-% and version 1.3c or later is part of all distributions of LaTeX
-% version 2008 or later.
-%
-% This file has the LPPL maintenance status "maintained".
-%
-% The list of all files belonging to the LaTeX base distribution is
-% given in the file `manifest.txt'. See also `legal.txt' for additional
-% information.
-%
-% The list of derived (unpacked) files belonging to the distribution
-% and covered by LPPL is defined by the unpacking scripts (with
-% extension .ins) which are part of the distribution.
-%
-% \fi
-% Filename: usrguide3.tex
-
-\documentclass{ltxguide}
-
-\usepackage[T1]{fontenc} % needed for \textbackslash in tt
-\usepackage{csquotes}
-
-\title{New \LaTeX\ methods for authors (starting 2020)}
-\author{\copyright~Copyright 2020-2022, \LaTeX\ Project Team.\\
- All rights reserved.}
-
-\date{2022-07-05}
-
-\NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
-\NewDocumentCommand\marg{m}{\arg{#1}}
-\NewDocumentCommand\meta{m}{\ensuremath{\langle}\textit{#1}\ensuremath{\rangle}}
-\NewDocumentCommand\pkg{m}{\textsf{#1}}
-\NewDocumentCommand\text{m}{\ifmmode\mbox{#1}\else#1\fi}
-% Fix a 'feature'
-\makeatletter
-\renewcommand \verbatim@font {\normalfont \ttfamily}
-\makeatother
-
-
-% for fpeval documentation
-
-\providecommand\fpop[1]{\mathop{\texttt{#1}}}
-\providecommand\fpbin[1]{\mathbin{\texttt{#1}}}
-\providecommand\fprel[1]{\mathrel{\texttt{#1}}}
-\providecommand\nan{\texttt{NaN}}
-
-\ExplSyntaxOn
-\ProvideExpandableDocumentCommand \fpeval { m } { \fp_eval:n {#1} }
-\ExplSyntaxOff
-
-\begin{document}
-
-\maketitle
-
-\tableofcontents
-
-\section{Introduction}
-
-\LaTeXe{} was released in 1994 and added a number of then-new concepts to
-\LaTeX{}. These are described in \texttt{usrguide}, which has largely remained
-unchanged. Since then, the \LaTeX{} team have worked on a number of ideas,
-firstly a programming language for \LaTeX{} (\pkg{expl3}) and then a range of
-tools for document authors which build on that language. Here, we describe
-\emph{stable} and \emph{widely-usable} concepts that have resulted from that
-work. These `new' ideas have been transferred from development packages
-into the \LaTeXe{} kernel. As such, they are now available to \emph{all}
-\LaTeX{} users and have the \emph{same stability} as any other part of the
-kernel. The fact that `behind the scenes' they are built on \pkg{expl3}
-is useful for the development team, but is not directly important to users.
-
-\section{Creating document commands and environments}
-
-\subsection{Overview}
-
-Creating document commands and environments using the \LaTeX3 toolset is based
-around the idea that a common set of descriptions can be used to cover almost
-all argument types used in real documents. Thus parsing is reduced to a simple
-description of which arguments a command takes: this description provides the
-`glue' between the document syntax and the implementation of the
-command.
-
-First, we will describe the argument types, then move on to explain how these
-can be used to create both document commands and environments. Various more
-specialized features are then described, which allow an even richer application
-of a simple interface set up.
-
-The details here are intended to help users create document commands in
-general. More technical detail, suitable for \TeX{} programmers, is included
-in \texttt{interface3}.
-
-\subsection{Describing argument types}
-
-In order to allow each argument to be defined independently, the parser does
-not simply need to know the number of arguments for a function, but also the
-nature of each one. This is done by constructing an \emph{argument
-specification}, which defines the number of arguments, the type of each
-argument and any additional information needed for the parser to read the user
-input and properly pass it through to internal functions.
-
-The basic form of the argument specifier is a list of letters, where each
-letter defines a type of argument. As will be described below, some of the
-types need additional information, such as default values. The argument types
-can be divided into two, those which define arguments that are mandatory
-(potentially raising an error if not found) and those which define optional
-arguments. The mandatory types
-\begin{itemize}
- \item[\texttt{m}] A standard mandatory argument, which can either be a single token
- alone or multiple tokens surrounded by curly braces |{}|. Regardless of the
- input, the argument will be passed to the internal code without the outer
- braces. This is the type specifier for a normal \TeX{} argument.
- \item[\texttt{r}] Given as \texttt{r}\meta{token1}\meta{token2}, this denotes a
- `required' delimited argument, where the delimiters are
- \meta{token1} and \meta{token2}. If the opening delimiter \meta{token1} is
- missing, the default marker |-NoValue-| will be inserted after a suitable
- error.
- \item[\texttt{R}] Given as \texttt{R}\meta{token1}\meta{token2}\marg{default},
- this is a `required' delimited argument as for~\texttt{r},
- but it has a user-definable recovery \meta{default} instead of
- |-NoValue-|.
- \item[\texttt{v}] Reads an argument `verbatim', between the following
- character and its next occurrence, in a way similar to the argument
- of the \LaTeXe{} command \cs{verb}. Thus a \texttt{v}-type argument
- is read between two identical characters, which cannot be any of |%|, |\|,
- |#|, |{|, |}| or \verb*| |. The verbatim argument can also be enclosed
- between braces, |{| and |}|. A command with a verbatim argument will
- produce an error when it appears within an argument of another function.
- \item[\texttt{b}] Only suitable in the argument specification of an
- environment, it denotes the body of the environment, between
- |\begin|\marg{environment} and |\end|\marg{environment}. See
- Section~\ref{sec:cmd:body} for details.
-\end{itemize}
-The types which define optional arguments are:
-\begin{itemize}
- \item[\texttt{o}] A standard \LaTeX{} optional argument, surrounded with square
- brackets, which will supply the special |-NoValue-| marker if not given
- (as described later).
- \item[\texttt{d}] Given as \texttt{d}\meta{token1}\meta{token2}, an optional
- argument which is delimited by \meta{token1} and \meta{token2}. As with
- \texttt{o}, if no value is given the special marker |-NoValue-| is
- returned.
- \item[\texttt{O}] Given as \texttt{O}\marg{default}, is like \texttt{o}, but returns
- \meta{default} if no value is given.
- \item[\texttt{D}] Given as \texttt{D}\meta{token1}\meta{token2}\marg{default}, it is
- as for \texttt{d}, but returns \meta{default} if no value is given.
- Internally, the \texttt{o}, \texttt{d} and \texttt{O} types are
- short-cuts to an appropriated-constructed \texttt{D} type argument.
- \item[\texttt{s}] An optional star, which will result in a value
- \cs{BooleanTrue} if a star is present and \cs{BooleanFalse}
- otherwise (as described later).
- \item[\texttt{t}] An optional \meta{token}, which will result in a value
- \cs{BooleanTrue} if \meta{token} is present and \cs{BooleanFalse}
- otherwise. Given as \texttt{t}\meta{token}.
- \item[\texttt{e}] Given as \texttt{e}\marg{tokens}, a set of optional
- \emph{embellishments}, each of which requires a \emph{value}.
- If an embellishment is not present, |-NoValue-| is returned. Each
- embellishment gives one argument, ordered as for the list of
- \meta{tokens} in the argument specification. All \meta{tokens}
- must be distinct.
- \item[\texttt{E}] As for \texttt{e} but returns one or more \meta{defaults}
- if values are not given: \texttt{E}\marg{tokens}\marg{defaults}. See
- Section~\ref{sec:cmd:embellishment} for more details.
-\end{itemize}
-
-\subsection{Modifying argument descriptions}
-
-In addition to the argument \emph{types} discussed above, the argument
-description also gives special meaning to three other characters.
-
-First, \texttt{+} is used to make an argument long (to accept paragraph
-tokens). In contrast to \cs{newcommand}, this applies on an
-argument-by-argument basis. So modifying the example to `|s o o +m O{default}|'
-means that the mandatory argument is now \cs{long}, whereas the optional
-arguments are not.
-
-Secondly, \texttt{!} is used to control whether spaces are allowed before
-optional arguments. There are some subtleties to this, as \TeX{} itself
-has some restrictions on where spaces can be `detected': more detail
-is given in Section~\ref{sec:cmd:opt-space}.
-
-Finally, the character \texttt{>} is used to declare so-called
-`argument processors', which can be used to modify the contents of an
-argument before it is passed to the macro definition. The use of argument
-processors is a somewhat advanced topic, (or at least a less commonly used
-feature) and is covered in Section~\ref{sec:cmd:processors}.
-
-\subsection{Creating document commands and environments}
-
-\begin{decl}
- |\NewDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\
- |\RenewDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\
- |\ProvideDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\
- |\DeclareDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code}
-\end{decl}
-This family of commands are used to create a \meta{cmd}. The argument
-specification for the function is given by \meta{arg spec}, and the command
-uses the \meta{code} with |#1|, |#2|, etc.\ replaced by the arguments found
-by the parser.
-
-An example:
-\begin{verbatim}
- \NewDocumentCommand\chapter{s o m}
- {%
- \IfBooleanTF{#1}%
- {\typesetstarchapter{#3}}%
- {\typesetnormalchapter{#2}{#3}}%
- }
-\end{verbatim}
-would be a way to define a \cs{chapter} command which would essentially behave
-like the current \LaTeXe{} command (except that it would accept an optional
-argument even when a \texttt{*} was parsed). The \cs{typesetnormalchapter}
-could test its first argument for being |-NoValue-| to see if an optional
-argument was present. (See Section~\ref{sec:cmd:special} for details of
-\cs{IfBooleanTF} and testing for |-NoValue-|.)
-
-The difference between the \cs{New...} \cs{Renew...}, \cs{Provide...}
-and \cs{Declare...} versions is the behavior if \meta{cmd} is already
-defined.
-\begin{itemize}
- \item \cs{NewDocumentCommand} will issue an error if \meta{cmd}
- has already been defined.
- \item \cs{RenewDocumentCommand} will issue an error if \meta{cmd}
- has not previously been defined.
- \item \cs{ProvideDocumentCommand} creates a new definition for
- \meta{function} only if one has not already been given.
- \item \cs{DeclareDocumentCommand} will always create the new
- definition, irrespective of any existing \meta{cmd} with the
- same name. This should be used sparingly.
-\end{itemize}
-
-If the \meta{cmd} can't be provided as a single token but needs
-\enquote{constructing}, you can use \cs{ExpandArgs} as explained in
-Section~\ref{sec:preconstructing-csnames} which also gives an example
-in which this is needed.
-
-\begin{decl}
- |\NewDocumentEnvironment| \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\
- |\RenewDocumentEnvironment| \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\
- |\ProvideDocumentEnvironment| \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code} \\
- |\DeclareDocumentEnvironment| \arg{env} \arg{arg spec} \arg{beg-code} \arg{end-code}
-\end{decl}
-These commands work in the same way as \cs{NewDocumentCommand}, etc.\@, but
-create environments (\cs{begin}\arg{env} \ldots{}
-\cs{end}\arg{env}). Both the \meta{beg-code} and \meta{end-code}
-may access the arguments as defined by \meta{arg spec}. The arguments will be
-given following \cs{begin}\arg{env}.
-
-\subsection{Optional arguments}
-\label{sec:cmd:opt}
-
-In contrast to commands created using \LaTeXe{}'s \cs{newcommand}, optional
-arguments created using \cs{NewDocumentCommand} may safely be nested. Thus for
-example, following
-\begin{verbatim}
-\NewDocumentCommand\foo{om}{I grabbed `#1' and `#2'}
-\NewDocumentCommand\baz{o}{#1-#1}
-\end{verbatim}
-using the command as
-\begin{verbatim}
-\foo[\baz[stuff]]{more stuff}
-\end{verbatim}
-will print
-\begin{quote}
-I grabbed `stuff-stuff' and `more stuff'
-\end{quote}
-This is particularly useful when placing a command with an optional argument
-\emph{inside} the optional argument of a second command.
-
-When an optional argument is followed by a mandatory argument with the same
-delimiter, the parser issues a warning because the optional argument could not
-be omitted by the user, thus becoming in effect mandatory. This can apply to
-\texttt{o}, \texttt{d}, \texttt{O}, \texttt{D}, \texttt{s}, \texttt{t},
-\texttt{e}, and \texttt{E} type arguments followed by \texttt{r} or
-\texttt{R}-type required arguments.
-
-The default for \texttt{O}, \texttt{D} and \texttt{E} arguments can be
-the result of grabbing another argument. Thus for example
-\begin{verbatim}
- \NewDocumentCommand\foo{O{#2} m}
-\end{verbatim}
-would use the mandatory argument as the default for the leading optional
-one.
-
-\subsection{Spacing and optional arguments}
-\label{sec:cmd:opt-space}
-
-\TeX{} will find the first argument after a function name irrespective of any
-intervening spaces. This is true for both mandatory and optional arguments. So
-|\foo[arg]| and \verb*|\foo [arg]| are equivalent. Spaces are also ignored when
-collecting arguments up to the last mandatory argument to be collected (as it
-must exist). So after
-\begin{verbatim}
- \NewDocumentCommand\foo{m o m}{ ... }
-\end{verbatim}
-the user input |\foo{arg1}[arg2]{arg3}| and \verb*|\foo{arg1} [arg2] {arg3}|
-will both be parsed in the same way.
-
-The behavior of optional arguments \emph{after} any mandatory arguments is
-selectable. The standard settings will allow spaces here, and thus with
-\begin{verbatim}
- \NewDocumentCommand\foobar{m o}{ ... }
-\end{verbatim}
-both |\foobar{arg1}[arg2]| and \verb*|\foobar{arg1} [arg2]| will find an
-optional argument. This can be changed by giving the modified |!| in the
-argument specification:
-\begin{verbatim}
- \NewDocumentCommand\foobar{m !o}{ ... }
-\end{verbatim}
-where \verb*|\foobar{arg1} [arg2]| will not find an optional argument.
-
-There is one subtlety here due to the difference in handling by \TeX{} of
-`control symbols', where the command name is made up of a single
-character, such as `\texttt{\textbackslash\textbackslash}'.
-Spaces are not ignored by \TeX{} here,
-and thus it is possible to require an optional argument directly follow such a
-command. The most common example is the use of \texttt{\textbackslash\textbackslash}
-in \pkg{amsmath} environments, which in the terms here would be defined as
-\begin{verbatim}
- \NewDocumentCommand\\{!s !o}{ ... }
-\end{verbatim}
-
-\subsection{`Embellishments'}
-\label{sec:cmd:embellishment}
-
-The \texttt{E}-type argument allows one default value per test token. This is
-achieved by giving a list of defaults for each entry in the list, for example:
-\begin{verbatim}
- E{^_}{{UP}{DOWN}}
-\end{verbatim}
-If the list of default values is \emph{shorter} than the list of test tokens,
-the special |-NoValue-| marker will be returned (as for the \texttt{e}-type
-argument). Thus for example
-\begin{verbatim}
- E{^_}{{UP}}
-\end{verbatim}
-has default \texttt{UP} for the |^| test character, but will return the
-|-NoValue-| marker as a default for |_|. This allows mixing of explicit
-defaults with testing for missing values.
-
-
-\subsection{Testing special values}
-\label{sec:cmd:special}
-
-Optional arguments make use of dedicated variables to return information about
-the nature of the argument received.
-
-
-
-\begin{decl}
- |\IfNoValueTF| \arg{arg} \arg{true code} \arg{false code} \\
- |\IfNoValueT| \arg{arg} \arg{true code} \\
- |\IfNoValueF| \arg{arg} \arg{false code}
-\end{decl}
-The \cs{IfNoValue(TF)} tests are used to check if \meta{argument} (|#1|,
-|#2|, \emph{etc.}) is the special |-NoValue-| marker. For example
-\begin{verbatim}
- \NewDocumentCommand\foo{o m}
- {%
- \IfNoValueTF {#1}%
- {\DoSomethingJustWithMandatoryArgument{#2}}%
- {\DoSomethingWithBothArguments{#1}{#2}}%
- }
-\end{verbatim}
-will use a different internal function if the optional argument
-is given than if it is not present.
-
-Note that three tests are available, depending on which outcome
-branches are required: \cs{IfNoValueTF}, \cs{IfNoValueT} and
-\cs{IfNoValueF}.
-
-As the \cs{IfNoValue(TF)} tests are expandable, it is possible to
-test these values later, for example at the point of typesetting or
-in an expansion context.
-
-It is important to note that |-NoValue-| is constructed such that it
-will \emph{not} match the simple text input |-NoValue-|, i.e.~that
-\begin{verbatim}
- \IfNoValueTF{-NoValue-}
-\end{verbatim}
-will be logically \texttt{false}.
-When two optional arguments follow each other (a syntax we typically
-discourage), it can make sense to allow users of the command to
-specify only the second argument by providing an empty first
-argument.
-\NEWdescription{2022/06/01}
-Rather than testing separately for emptiness and for
-|-NoValue-| it is then best to use the argument type~|O| with an
-empty default value, and then test for emptiness using the
-conditional \cs{IfBlankTF} (described below) instead.
-
-\begin{decl}
- |\IfValueTF| \arg{arg} \arg{true code} \arg{false code} \\
- |\IfValueT| \arg{arg} \arg{true code} \\
- |\IfValueF| \arg{arg} \arg{false code}
-\end{decl}
-The reverse form of the \cs{IfNoValue(TF)} tests are also available
-as \cs{IfValue(TF)}. The context will determine which logical
-form makes the most sense for a given code scenario.
-
-
-
-
-
-\begin{decl}[2022/06/01]
- |\IfBlankTF| \arg{arg} \arg{true code} \arg{false code} \\
- |\IfBlankT| \arg{arg} \arg{true code} \\
- |\IfBlankF| \arg{arg} \arg{false code}
-\end{decl}
-
-
-The \cs{IfNoValueTF} command chooses the \meta{true code} if the optional argument has not
-been used at all (and it returns the special \texttt{-NoValue-}
-marker), but not if it has been given an empty value. In contrast
-\cs{IfBlankTF} returns true if its argument is either truly empty or
-only contains one or more normal blanks.
-For example
-\begin{verbatim}
-\NewDocumentCommand\foo{m!o}{\par #1:
- \IfNoValueTF{#2}{No optional}%
- {\IfBlankTF{#2}{Blanks in or empty}%
- {Real content in}}%
- \space argument!}
-\foo{1}[bar] \foo{2}[ ] \foo{3}[] \foo{4}[\space] \foo{5} [x]
-\end{verbatim}
-results
-in the following output:
-\begin{quote}
- \NewDocumentCommand\foo{m!o}{\par #1:
- \IfNoValueTF{#2}{No optional}%
- {\IfBlankTF{#2}{Blanks in or empty}%
- {Real content in}}%
- \space argument!}
- \foo{1}[bar] \foo{2}[ ] \foo{3}[] \foo{4}[\space] \foo{5} [x]
-\end{quote}
-
-Note that the \cs{space} in (4) is considered real content---because it is
-a command and not a \enquote{space} character---even though it results
-in producing a space. You can also observe in (5) the effect of the
-\texttt{!} specifier, preventing the last \cs{foo}
-from interpreting \texttt{[x]} as its optional argument.
-
-
-
-
-\begin{decl}
- |\BooleanFalse| \\
- |\BooleanTrue|
-\end{decl}
-The \texttt{true} and \texttt{false} flags set when searching for
-an optional character (using \texttt{s} or \texttt{t\meta{char}}) have
-names which are accessible outside of code blocks.
-
-\begin{decl}
- |\IfBooleanTF| \arg{arg} \arg{true code} \arg{false code} \\
- |\IfBooleanT| \arg{arg} \arg{true code} \\
- |\IfBooleanF| \arg{arg} \arg{false code}
-\end{decl}
-Used to test if \meta{argument} (|#1|, |#2|, \emph{etc.}) is
-\cs{BooleanTrue} or \cs{BooleanFalse}. For example
-\begin{verbatim}
- \NewDocumentCommand\foo{sm}
- {%
- \IfBooleanTF {#1}%
- {\DoSomethingWithStar{#2}}%
- {\DoSomethingWithoutStar{#2}}%
- }
-\end{verbatim}
-checks for a star as the first argument, then chooses the action to
-take based on this information.
-
-\subsection{Argument processors}
-\label{sec:cmd:processors}
-
-Argument processor are applied to an argument \emph{after} it has been grabbed
-by the underlying system but before it is passed to \meta{code}. An argument
-processor can therefore be used to regularize input at an early stage, allowing
-the internal functions to be completely independent of input form. Processors
-are applied to user input and to default values for optional arguments, but
-\emph{not} to the special |-NoValue-| marker.
-
-Each argument processor is specified by the syntax \texttt{>}\marg{processor}
-in the argument specification. Processors are applied from right to left, so
-that
-\begin{verbatim}
- >{\ProcessorB} >{\ProcessorA} m
-\end{verbatim}
-would apply \cs{ProcessorA} followed by \cs{ProcessorB} to the tokens grabbed
-by the \texttt{m} argument.
-
-\begin{decl}
- |\SplitArgument| \arg{number} \arg{token(s)}
-\end{decl}
-This processor splits the argument given at each occurrence of the
-\meta{tokens} up to a maximum of \meta{number} tokens (thus
-dividing the input into $\text{\meta{number}} + 1$ parts).
-An error is given if too many \meta{tokens} are present in the
-input. The processed input is placed inside
-$\text{\meta{number}} + 1$ sets of braces for further use.
-If there are fewer than \arg{number} of \arg{tokens} in the argument
-then |-NoValue-| markers are added at the end of the processed
-argument.
-\begin{verbatim}
- \NewDocumentCommand \foo {>{\SplitArgument{2}{;}} m}
- {\InternalFunctionOfThreeArguments#1}
-\end{verbatim}
-If only a single character \meta{token} is used for the split, any
-category code $13$ (active) character matching the \meta{token} will
-be replaced before the split takes place.
-Spaces are trimmed at each end of each item parsed.
-
-The \texttt{E} argument type is somewhat special, because with a single
-\texttt{E} in the command declaration you may end up with several
-arguments in a command (one formal argument per embellishment token).
-Therefore, when an argument processor is applied to an \texttt{E}-type
-argument, all the arguments pass through that processor before being fed
-to the \meta{code}. For example, this command
-\begin{verbatim}
- \NewDocumentCommand \foo { >{\TrimSpaces} e{_^} }
- { [#1](#2) }
-\end{verbatim}
-applies \cs{TrimSpaces} to both arguments.
-
-\begin{decl}
- |\SplitList| \arg{token(s)}
-\end{decl}
-This processor splits the argument given at each occurrence of the
-\meta{token(s)} where the number of items is not fixed. Each item is
-then wrapped in braces within |#1|. The result is that the
-processed argument can be further processed using a mapping function
-(see below).
-\begin{verbatim}
- \NewDocumentCommand \foo {>{\SplitList{;}} m}
- {\MappingFunction#1}
-\end{verbatim}
-If only a single character \meta{token} is used for the split, any
-category code $13$ (active) character matching the \meta{token} will
-be replaced before the split takes place.
-Spaces are trimmed at each end of each item parsed.
-
-\begin{decl}
- |\ProcessList| \arg{list} \arg{function}
-\end{decl}
-To support \cs{SplitList}, the function \cs{ProcessList} is available
-to apply a \meta{function} to every entry in a \meta{list}. The
-\meta{function} should absorb one argument: the list entry. For example
-\begin{verbatim}
- \NewDocumentCommand \foo {>{\SplitList{;}} m}
- {\ProcessList{#1}{\SomeDocumentCommand}}
-\end{verbatim}
-
-\begin{decl}
- |\ReverseBoolean|
-\end{decl}
-This processor reverses the logic of \cs{BooleanTrue} and
-\cs{BooleanFalse}, so that the example from earlier would become
-\begin{verbatim}
- \NewDocumentCommand\foo{>{\ReverseBoolean} s m}
- {%
- \IfBooleanTF#1%
- {\DoSomethingWithoutStar{#2}}%
- {\DoSomethingWithStar{#2}}%
- }
-\end{verbatim}
-
-\begin{decl}
- |\TrimSpaces|
-\end{decl}
-Removes any leading and trailing spaces (tokens with character code~$32$
-and category code~$10$) for the ends of the argument. Thus for example
-declaring a function
-\begin{verbatim}
- \NewDocumentCommand\foo {>{\TrimSpaces} m}
- {\showtokens{#1}}
-\end{verbatim}
-and using it in a document as
-\begin{flushleft}
- \verb= =\verb*=\foo{ hello world }=
-\end{flushleft}
-will show `\verb*=hello world=' at the terminal, with the space at each
-end removed. \cs{TrimSpaces} will remove multiple spaces from the ends of
-the input in cases where these have been included such that the standard
-\TeX{} conversion of multiple spaces to a single space does not apply.
-
-\subsection{Body of an environment}
-\label{sec:cmd:body}
-
-While environments |\begin|\marg{environment}\ \dots{}\,|\end|\marg{environment}
-are typically used in cases where the code implementing the \meta{environment}
-does not need to access the contents of the environment (its `body'),
-it is sometimes useful to have the body as a standard argument.
-
-This is achieved by ending the argument specification with~\texttt{b}, which is
-a dedicated argument type for this situation. For instance
-\begin{verbatim}
- \NewDocumentEnvironment{twice} {O{\ttfamily} +b}
- {#2#1#2} {}
-\end{verbatim}
-\begin{verbatim}
- \begin{twice}[\itshape]
- Hello world!
- \end{twice}
-\end{verbatim}
-typesets `Hello world!{\itshape Hello world!}'.
-
-The prefix |+| is used to allow multiple paragraphs in the environment's body.
-Argument processors can also be applied to \texttt{b}~arguments. By default,
-spaces are trimmed at both ends of the body: in the example there would
-otherwise be spaces coming from the ends the lines after |[\itshape]| and
-|world!|. Putting the prefix |!| before \texttt{b} suppresses space-trimming.
-
-When \texttt{b} is used in the argument specification, the last
-argument of the environment declaration (e.g.,
-\cs{NewDocumentEnvironment}), which consists of an \meta{end code} to
-insert at |\end|\marg{environment}, is redundant since one can simply
-put that code at the end of the \meta{start code}. Nevertheless this
-(empty) \meta{end code} must be provided.
-
-Environments that use this feature can be nested.
-
-\subsection{Fully-expandable document commands}
-
-Document commands created using \cs{NewDocumentCommand}, etc.\@, are normally
-created so that they do not expand unexpectedly. This is done using engine
-features, so is more powerful than \LaTeXe{}'s \cs{protect} mechanism. There
-are \emph{very rare} occasion when it may be useful to create functions using a
-expansion-only grabber. This imposes a number of restrictions on the
-nature of the arguments accepted by a function, and the code it implements.
-This facility should only be used when \emph{absolutely necessary}.
-
-\begin{decl}
- |\NewExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\
- |\RenewExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\
- |\ProvideExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\
- |\DeclareExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code}
-\end{decl}
-This family of commands is used to create a document-level \meta{function},
-which will grab its arguments in a fully-expandable manner. The
-argument specification for the function is given by \meta{arg spec},
-and the function will execute \meta{code}. In general, \meta{code} will
-also be fully expandable, although it is possible that this will
-not be the case (for example, a function for use in a table might
-expand so that \cs{omit} is the first non-expandable non-space token).
-
-Parsing arguments by pure expansion imposes a number of restrictions on
-both the type of arguments that can be read and the error checking
-available:
-\begin{itemize}
- \item The last argument (if any are present) must be one of the
- mandatory types \texttt{m}, \texttt{r} or \texttt{R}.
- \item The `verbatim' argument type \texttt{v} is not available.
- \item Argument processors (using \texttt{>}) are not available.
- \item It is not possible to differentiate between, for example
- |\foo[| and |\foo{[}|: in both cases the \texttt{[} will be
- interpreted as the start of an optional argument. As a
- result, checking for optional arguments is less robust than
- in the standard version.
-\end{itemize}
-
-\subsection{Details about argument delimiters}
-
-In normal (non-expandable) commands, the delimited types look for the
-initial delimiter by peeking ahead (using \pkg{expl3}'s |\peek_...|
-functions) looking for the delimiter token. The token has to have the
-same meaning and `shape' of the token defined as delimiter.
-There are three possible cases of delimiters: character tokens, control
-sequence tokens, and active character tokens. For all practical purposes
-of this description, active character tokens will behave exactly as
-control sequence tokens.
-
-\subsubsection{Character tokens}
-
-A character token is characterized by its character code, and its meaning
-is the category code~(|\catcode|). When a command is defined, the meaning
-of the character token is fixed into the definition of the command and
-cannot change. A command will correctly see an argument delimiter if
-the open delimiter has the same character and category codes as at the
-time of the definition. For example in:
-\begin{verbatim}
- \NewDocumentCommand { \foobar } { D<>{default} } {(#1)}
-\end{verbatim}
-\begin{verbatim}
- \foobar <hello> \par
- \char_set_catcode_letter:N <
- \foobar <hello>
-\end{verbatim}
-the output would be:
-\begin{verbatim}
- (hello)
- (default)<hello>
-\end{verbatim}
-as the open-delimiter |<| changed in meaning between the two calls to
-|\foobar|, so the second one doesn't see the |<| as a valid delimiter.
-Commands assume that if a valid open-delimiter was found, a matching
-close-delimiter will also be there. If it is not (either by being
-omitted or by changing in meaning), a low-level \TeX{} error is raised
-and the command call is aborted.
-
-\subsubsection{Control sequence tokens}
-
-A control sequence (or control character) token is characterized by is
-its name, and its meaning is its definition.
-A token cannot have two different meanings at the same time.
-When a control sequence is defined as delimiter in a command,
-it will be detected as delimiter whenever the control sequence name
-is found in the document regardless of its current definition.
-For example in:
-\begin{verbatim}
- \cs_set:Npn \x { abc }
- \NewDocumentCommand { \foobar } { D\x\y{default} } {(#1)}
- \foobar \x hello\y \par
- \cs_set:Npn \x { def }
- \foobar \x hello\y
-\end{verbatim}
-the output would be:
-\begin{verbatim}
- (hello)
- (hello)
-\end{verbatim}
-with both calls to the command seeing the delimiter |\x|.
-
-\subsection{Creating new argument processors}
-
-\begin{decl}
- |\ProcessedArgument|
-\end{decl}
-Argument processors allow manipulation of a grabbed argument before it is
-passed to the underlying code. New processor implementations may be created
-as functions which take one trailing argument, and which leave their result in
-the \cs{ProcessedArgument} variable. For example, \cs{ReverseBoolean} is
-defined as
-\begin{verbatim}
-\ExplSyntaxOn
- \cs_new_protected:Npn \ReverseBoolean #1
- {
- \bool_if:NTF #1
- { \tl_set:Nn \ProcessedArgument { \c_false_bool } }
- { \tl_set:Nn \ProcessedArgument { \c_true_bool } }
- }
-\ExplSyntaxOff
-\end{verbatim}
-[As an aside: the code is written in \pkg{expl3}, so we don't have to
- worry about spaces creeping into the definition.]
-
-\subsection{Access to the argument specification}
-
-The argument specifications for document commands and environments are
-available for examination and use.
-
-\begin{decl}
- |\GetDocumentCommandArgSpec| \arg{function} \\
- |\GetDocumentEnvironmentArgSpec| \arg{environment}
-\end{decl}
-These functions transfer the current argument specification for the
-requested \meta{function} or \meta{environment} into the token list
-variable \cs{ArgumentSpecification}. If the \meta{function} or
-\meta{environment} has no known argument specification then an error
-is issued. The assignment to \cs{ArgumentSpecification} is local to
-the current \TeX{} group.
-
-\begin{decl}
- |\ShowDocumentCommandArgSpec| \arg{function} \\
- |\ShowDocumentEnvironmentArgSpec| \arg{environment}
-\end{decl}
-These functions show the current argument specification for the
-requested \meta{function} or \meta{environment} at the terminal. If
-the \meta{function} or \meta{environment} has no known argument
-specification then an error is issued.
-
-
-
-\section{Copying and showing (robust) commands}
-
-If you want to (slightly) alter an existing command you may want to
-save the current definition under a new name and then use that in a
-new definition. If the existing command is robust, then the old trick of
-using the low-level \cs{let} for this doesn't work, because it only
-copies the top-level definition, but not the part that actually does
-the work. As most \LaTeX{} commands are nowadays robust, \LaTeX{}
-now offers some high-level declarations for this instead.
-
-However, please note that it is usually better to make use of
-available hooks (e.g., the generic command or environment hooks),
-instead of copying the current definition and thereby freezing it; see
-the hook management documentation \texttt{lthooks-doc.pdf} for
-details.
-
-\begin{decl}
- |\NewCommandCopy| \arg{cmd} \arg{existing-cmd} \\
- |\RenewCommandCopy| \arg{cmd} \arg{existing-cmd} \\
- |\DeclareCommandCopy| \arg{cmd} \arg{existing-cmd}
-\end{decl}
-
-This copies the definition of \meta{existing-cmd} to \meta{cmd}. After
-this \meta{existing-cmd} can be redefined and \meta{cmd}
-still works! This allows you to then provide a new definition for
-\meta{existing-cmd} that makes use of \meta{cmd} (i.e., of its old
-definition). For example, after
-\begin{verbatim}
- \NewCommandCopy\LaTeXorig\LaTeX
- \RenewDocumentCommand\LaTeX{}{\textcolor{blue}{\LaTeXorig}}
-\end{verbatim}
-all \LaTeX{} logos generated with \cs{LaTeX} will come out in blue
-(assuming you have a color package loaded).
-
-The differences between \cs{New...} and \cs{Renew...} are as
-elsewhere: i.e., you get an error depending on whether or not
-\meta{cmd} already exists, or in case of \cs{Declare...} it is copied
-regardless. Note that there is no \cs{Provide...} declaration, because
-that would be of limited value.
-
-
-If the \meta{cmd} or \meta{existing-cmd} can't be provided as a single
-token but need \enquote{constructing}, you can use \cs{ExpandArgs}
-as explained in
-Section~\ref{sec:preconstructing-csnames}.
-
-
-
-
-\begin{decl}
- |\ShowCommand| \arg{cmd}
-\end{decl}
-
-This displays the meaning of the \meta{cmd} on the terminal and then
-stops (just like the primitive \cs{show}). The difference is that it
-correctly shows the meaning of more complex commands, e.g., in case of
-robust commands it displays not only the top-level definition but
-also the actual payload code and in case of commands declared with
-\cs{NewDocumentCommand}, etc.\ it also gives you detailed information
-about the argument signature.
-
-
-\section[Preconstructing command names \\ (or otherwise expanding arguments)]
- {Preconstructing command names (or otherwise expanding arguments)}
-\label{sec:preconstructing-csnames}
-
-When declaring new commands with \cs{NewDocumentCommand} or
-\cs{NewCommandCopy} or similar, it is sometimes necessary to
-``construct'' the csname. As a general mechanism the L3 programming
-layer has \cs{exp_args:N...} for this, but there is no mechanism for
-it if \cs{ExplSyntaxOn} is not active (and mixing programming and user
-interface level commands is not a good approach anyhow). We therefore
-offer a mechanism to access this ability using CamelCase naming.
-
-\begin{decl}
- |\UseName| \arg{string} \\
- |\ExpandArgs| \arg{spec} \arg{cmd} \arg{arg1} \dots
-\end{decl}
-
-\cs{UseName} turns the \meta{string} directly into a csname and
-then executes it: this is equivalent to the long-standing
-\LaTeXe{} internal command \cs{@nameuse}, or the L3 programming
-equivalent \cs{use:c}. \cs{ExpandArgs} takes a \meta{spec} which
-describes how to expand the \meta{arguments}, carries out these
-operations then executes the \meta{cmd}. The \meta{spec} uses
-the descriptions offered by the L3 programming layer, and the
-relevant \cs{exp_args:N...} function must exist. Common cases will
-have a \meta{spec} of \texttt{c}, \texttt{cc} or \texttt{Nc}: see below.
-
-As an example, the following declaration provides a method to generate
-copyedit commands:
-\begin{verbatim}
-\NewDocumentCommand\newcopyedit{mO{red}}
- {\newcounter{todo#1}%
- \ExpandArgs{c}\NewDocumentCommand{#1}{s m}%
- {\stepcounter{todo#1}%
- \IfBooleanTF {##1}%
- {\todo[color=#2!10]{\UseName{thetodo#1}: ##2}}%
- {\todo[inline,color=#2!10]{\UseName{thetodo#1}: ##2}}%
- }%
- }
-\end{verbatim}
-Given that declaration you can then write
-\verb/\newcopyedit{note}[blue]/ which defines the command \cs{note}
-and the corresponding counter for you.
-
-A second example is to copy a command by string name using
-\cs{NewCommandCopy}: here we might need to construct both command
-names.
-\begin{verbatim}
-\NewDocumentCommand\savebyname{m}
- {\ExpandArgs{cc}\NewCommandCopy{saved#1}{#1}}
-\end{verbatim}
-
-In the \meta{spec} each \texttt{c} stands for one argument that is
-turned into a `\texttt{c}'ommand. An \texttt{n} represents a
-`\texttt{n}'ormal argument that is not altered and \texttt{N} stands for
-a `\texttt{N}'ormal argument which is also left unchanged, but one
-consisting only of a single token (and usually unbraced). Thus, to
-construct a command from a string only for the second argument of
-\cs{NewCommandCopy} you would write
-\begin{verbatim}
-\ExpandArgs{Nc}\NewCommandCopy\mysectionctr{c@section}
-\end{verbatim}
-There are several other single letters supported in the L3 programming
-layer that \emph{could} be used in the \meta{spec} to manipulate
-arguments in other ways. If you are interested, take a look at the
-\enquote{Argument expansion} section in the L3 programming layer
-documentation in \texttt{interface3.pdf}.
-
-
-
-\section{Expandable floating point (and other) calculations}
-
-The \LaTeX3 programming layer which is part of the format offers a
-rich interface to manipulate floating point variables and values. To
-allow for (simpler) applications to use this on document-level or in
-packages otherwise not making use of the L3 programming layer a few
-interface commands are made available.
-
-
-\begin{decl}
- |\fpeval| \arg{floating point expression}
-\end{decl}
-
-The expandable command \cs{fpeval} takes as its argument a floating
-point expression and produces a result using the normal rules of
-mathematics. As this command is expandable it can be used where \TeX{}
-requires a number and for example within a low-level \cs{edef} operation
-to give a purely numerical result.
-
-
-
-Briefly, the floating point expressions may comprise:
-\begin{itemize}
- \item Basic arithmetic: addition $x\fpbin{+}y$, subtraction $x\fpbin{-}y$,
- multiplication $x\fpbin{*}y$, division $x\fpbin{/}y$, square root~$\sqrt{x}$,
- and parentheses.
- \item Comparison operators: $x\fprel{<}y$,
- $x\fprel{<=}y$, $x\fprel{>?}y$,
- $x\fprel{!=}y$ \emph{etc.}
- \item Boolean logic: sign $\fpop{sign} x$,
- negation $\fpop{!}x$, conjunction
- $x\fprel{\&\&}y$, disjunction $x\fprel{\string|\string|}y$, ternary
- operator $x\fprel{?}y\fprel{:}z$.
- \item Exponentials: $\fpop{exp} x$, $\fpop{ln} x$, $x\mathord{\texttt{\^{}}}y$.
- \item Integer factorial: $\fpop{fact} x$.
- \item Trigonometry: $\fpop{sin} x$, $\fpop{cos} x$, $\fpop{tan} x$, $\fpop{cot} x$, $\fpop{sec}
- x$, $\fpop{csc} x$ expecting their arguments in radians, and
- $\fpop{sind} x$, $\fpop{cosd} x$,
- $\fpop{tand} x$, $\fpop{cotd} x$,
- $\fpop{secd} x$, $\fpop{cscd} x$ expecting their
- arguments in degrees.
- \item Inverse trigonometric functions: $\fpop{asin} x$,
- $\fpop{acos} x$, $\fpop{atan} x$,
- $\fpop{acot} x$, $\fpop{asec} x$,
- $\fpop{acsc} x$ giving a result in radians, and
- $\fpop{asind} x$, $\fpop{acosd} x$,
- $\fpop{atand} x$, $\fpop{acotd} x$,
- $\fpop{asecd} x$, $\fpop{acscd} x$ giving a result
- in degrees.
- \item Extrema: $\fpop{max}(x_{1},x_{2},\ldots)$, $\fpop{min}(x_{1},x_{2},\ldots)$,
- $\fpop{abs}(x)$.
- \item Rounding functions, controlled by two optional
- values, $n$ (number of places, $0$ by default) and
- $t$ (behavior on a tie, $\nan$ by default):
- \begin{itemize}
- \item $\fpop{trunc}(x,n)$ rounds towards zero,
- \item $\fpop{floor}(x,n)$ rounds towards~$-\infty$,
- \item $\fpop{ceil}(x,n)$ rounds towards~$+\infty$,
- \item $\fpop{round}(x,n,t)$ rounds to the closest value, with
- ties rounded to an even value by default, towards zero if $t=0$,
- towards $+\infty$ if $t>0$ and towards $-\infty$ if $t<0$.
- \end{itemize}
- \item Random numbers: $\fpop{rand}()$, $\fpop{randint}(m,n)$.
- \item Constants: \texttt{pi}, \texttt{deg} (one degree in radians).
- \item Dimensions, automatically expressed in points, \emph{e.g.},
- \texttt{pc} is~$12$.
- \item Automatic conversion (no need for \cs{number}) of
- integer, dimension, and skip variables to floating points numbers,
- expressing dimensions in points and ignoring the stretch and
- shrink components of skips.
- \item Tuples: $(x_1,\ldots{},x_n)$ that can be added together,
- multiplied or divided by a floating point number, and nested.
-\end{itemize}
-
-An example of use could be the following:
-\begin{verbatim}
- \LaTeX{} can now compute: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3}
- = \fpeval{sin(3.5)/2 + 2e-3} $.
-\end{verbatim}
-which produces the following output:
-\begin{quote}
- \LaTeX{} can now compute: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3}
- = \fpeval{sin(3.5)/2 + 2e-3} $.
-\end{quote}
-
-\begin{decl}
- |\inteval| \arg{integer expression}
-\end{decl}
-
- The expandable command \cs{inteval} takes as its argument an integer
- expression and produces a result using the normal rules of
- mathematics with some restrictions, see below. The operations
- recognized are |+|, |-|, |*| and |/| plus parentheses. As this
- command is expandable it can be used where \TeX{} requires a number
- and for example within a low-level \cs{edef} operation to give a
- purely numerical result.
-
- This is basically a thin wrapper for the primitive \cs{numexpr}
- command and therefore has some syntax restrictions. These are:
- \begin{itemize}
- \item \texttt{/} denotes division rounded to the closest integer with
- ties rounded away from zero;
- \item there is an error and the overall expression evaluates to zero
- whenever the absolute value of any intermediate result exceeds
- $2^{31}-1$, except in the case of scaling operations
- $a$\texttt{*}$b$\texttt{/}$c$, for which $a$\texttt{*}$b$ may be
- arbitrarily large;
- \item parentheses may not appear after unary \texttt{+} or
- \texttt{-}, namely placing \texttt{+(} or \texttt{-(} at the start
- of an expression or after \texttt{+}, \texttt{-}, \texttt{*},
- \texttt{/} or~\texttt{(} leads to an error.
- \end{itemize}
-
-An example of use could be the following.
-\begin{verbatim}
-\LaTeX{} can now compute: The sum of the numbers is $\inteval{1 + 2 + 3}$.
-\end{verbatim}
-which results in
-\enquote{\LaTeX{} can now compute: The sum of the numbers is $\inteval{1 + 2 + 3}$.}
-
-
-\begin{decl}
- |\dimeval| \arg{dimen expression} \qquad
- |\skipeval| \arg{skip expression}
-\end{decl}
-
-Similar to \cs{inteval} but computing a length (\texttt{dimen}) or a
-rubber length (\texttt{skip}) value. Both are thin wrappers around
-the corresponding engine primitives, which makes them fast, but
-therefore shows the same syntax peculiars as discussed
-above. Nevertheless, in practice they are usually sufficient. For
-example
-\begin{verbatim}
-\newcommand\calulateheight[1]{%
- \setlength\textheight{\dimeval{\topskip+\baselineskip*\inteval{#1-1}}}}
-\end{verbatim}
-sets the \cs{textheight} to the appropriate value if a page should
-hold a specific number of text lines. Thus after |\calulateheight{40}|
-it is set to \dimeval{\topskip+\baselineskip*\inteval{40-1}}, given
-the values \cs{topskip} (\dimeval{\topskip}) and \cs{baselineskip}
-(\dimeval{\baselineskip}) in the current document.
-
-\section{Case changing}
-
-\TeX{} provides two primitives \cs{uppercase} and \cs{lowercase} for changing
-the case of text. However, these have a range of limitations: they only change
-the case of explicit characters, do not account for the surrounding context, do
-not support UTF-8 input with 8-bit engines, etc. To overcome this problem,
-\LaTeX{} provides the commands \cs{MakeUppercase}, \cs{MakeLowercase} and
-\cs{MakeTitlecase}: these offer significant enhancement over the \TeX{}
-primitives. These commands are engine-robust (\cs{protected}), and so
-can be used in moving arguments.
-
-Upper- and lower-casing are well-understood in general conversation.
-Titlecasing here follows the definition given by the Unicode Consortium: the
-first character of the input will be converted to (broadly) uppercase, and the
-rest of the input to lowercase. The full range of Unicode UTF-8 input can be
-supported, with the proviso that at present the characters set up with 8-bit
-engines match those available in standard input encodings (|T1|, |T2|, |LGR|).
-\begin{quotation}
- \begin{tabular}{rl}
- |\MakeUppercase{hello WORLD ßüé}| & \MakeUppercase{hello WORLD ßüé} \\
- |\MakeLowercase{hello WORLD ßüé}| & \MakeLowercase{hello WORLD ßüé} \\
- |\MakeTitlecase{hello WORLD ßüé}| & \MakeTitlecase{hello WORLD ßüé} \\
- \end{tabular}
-\end{quotation}
-
-The input given to these commands is `expanded' before case changing is
-applied. This means that any commands within the input that convert to pure
-text will be case changed. Mathematical content is automatically excluded, as
-are the arguments to the commands \cs{label}, \cs{ref}, \cs{cite}, \cs{begin}
-and \cs{end}. Additional exclusions can be added using the command
-\cs{AddToNoCaseChangeList}. Input can be excluded from case changing using the
-command \cs{NoCaseChange}.
-\begin{quotation}
- \begin{tabular}{rl}
- |\MakeUppercase{Some text $y = mx + c$}|
- & \MakeUppercase{Some text $y = mx + c$} \\
- |\MakeUppercase{\NoCaseChange{iPhone}}|
- & \MakeLowercase{\NoCaseChange{iPhone}} \\
- \end{tabular}
-\end{quotation}
-
-To allow robust commands to be used within case changing \emph{and} to produce
-the expected output, two additional control commands are available.
-\cs{CaseSwitch} allows the user to specify the result for the four possible
-cases
-\begin{itemize}
- \item No case changing
- \item Uppercasing
- \item Lowercasing
- \item Titlecasing (only applies for the start of the input)
-\end{itemize}
-The command \cs{DeclareCaseChangeEquivalent} provides a way to substitute a
-command by an alternative version when it is found inside a case changing
-situation.
-
-\end{document}