summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/usrguide.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/base/usrguide.tex')
-rw-r--r--macros/latex-dev/base/usrguide.tex2570
1 files changed, 971 insertions, 1599 deletions
diff --git a/macros/latex-dev/base/usrguide.tex b/macros/latex-dev/base/usrguide.tex
index dfdf9443e6..8069403665 100644
--- a/macros/latex-dev/base/usrguide.tex
+++ b/macros/latex-dev/base/usrguide.tex
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 1993-2022
+% Copyright (C) 2020-2022
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
@@ -28,18 +28,44 @@
% \fi
% Filename: usrguide.tex
-\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\documentclass{ltxguide}
-\documentclass{ltxguide}[2001/05/28]
+\usepackage[T1]{fontenc} % needed for \textbackslash in tt
+\usepackage{csquotes}
-\title{\LaTeXe~for authors}
+\title{\LaTeX\ for authors --- current version}
+\author{\copyright~Copyright 2020-2022, \LaTeX\ Project Team.\\
+ All rights reserved.%
+ \footnote{This file may 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. See the source
+ \texttt{usrguide3.tex} for full details.}%
+}
-\author{\copyright~Copyright 1995--2020, \LaTeX\ Project Team.\\
- All rights reserved.}
+\date{2022-07-05}
-\date{25 May 2020}
+\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
@@ -48,1780 +74,1126 @@
\section{Introduction}
-Welcome to \LaTeXe, the new standard version of the \LaTeX{} Document
-Preparation System.
-
-This document describes how to take advantage of the new features of
-\LaTeX, and how to process your old \LaTeX{} documents with
-\LaTeXe. However, this document is only a brief introduction to the
-new facilities and is intended for authors who are already familiar
-with the old version of \LaTeX{}. It is \emph{not} a reference manual
-for \LaTeXe{} nor is it a complete introduction to \LaTeX.
-
-It is somewhat of an historical document now, since \LaTeXe{} came into
-existence in 1994.
-
-\subsection[\LaTeXe---The new \LaTeX~release]
- {\LaTeXe---The new \LaTeX~release\\ (well, for more than 10 years now)}
-
-The previous version of \LaTeX{} was known as \LaTeX~2.09. Over the
-years many extensions have been developed for \LaTeX. This is, of
-course, a sure sign of its continuing popularity but it has had one
-unfortunate result: incompatible \LaTeX{} formats came into use at
-different sites. This included `standard \LaTeX~2.09', \LaTeX{} built
-with the \emph{New Font Selection Scheme}~(\NFSS), \SLiTeX, \AmSLaTeX,
-and so on. Thus, to process documents from various places, a site
-maintainer was forced to keep multiple versions of the \LaTeX{}
-program. In addition, when looking at a source file it was not always
-clear for which format the document was written.
-
-To put an end to this unsatisfactory situation, \LaTeXe{} has been
-produced; it brings all such extensions back under a single format and
-thus prevents the proliferation of mutually incompatible dialects of
-\LaTeX~2.09. With \LaTeXe{} the `new font selection scheme' is
-standard and, for example, \textsf{amsmath} (formerly the \AmSLaTeX{}
-format) or \textsf{slides} (formerly the \SLiTeX{} format) are simply
-extensions, which may be loaded by documents using the same base format.
-
-The introduction of a new release also made it possible to add a small
-number of often-requested features and to make the task of writing
-packages and classes simpler.
-
-\subsection{\LaTeX3---The long-term future of \LaTeX}
-\label{Sec:ltx3}
-
-\LaTeXe{} is the consolidation step in a comprehensive
-reimplementation of the \LaTeX{} system. The next major release of
-\LaTeX{} will be \LaTeX3, which will include a radical overhaul of the
-document designers' and package writers' interface to \LaTeX.
-
-\LaTeX3 is a long-term research project but, until it is completed,
-the project team are committed to the active maintenance of \LaTeXe{}.
-Thus the experience gained from the production and maintenance of
-\LaTeXe{} will be a major influence on the design of \LaTeX3.
-A brief description of the project can be found in the document
-|ltx3info.tex|.
-
-If you would like to support the project then you are welcome to send
-donations to the \LaTeX\ Project Fund; this has been set up to help
-the research team by financing various expenses associated with this
-voluntary work of maintaining the current \LaTeX{} and developing
-\LaTeX\ further.
-
-The fund is administered by The \TeX{} Users Group and by various
-local user groups. Information about making donations and joining
-these groups is available from:
-\begin{quote}\small\label{addrs}
- \texttt{http://www.tug.org/lugs.html}
-\end{quote}
+\LaTeXe{} was released in 1994 and added a number of then-new concepts to
+\LaTeX{}. These are described in \texttt{usrguide-old}, 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.
-The \LaTeX3{} project has its home page
-on the World Wide Web at:
-\begin{verbatim}
- http://www.latex-project.org/
-\end{verbatim}
-This page describes \LaTeX{} and the \LaTeX3 project, and contains
-pointers to other \LaTeX{} resources, such as the user guides, the
-\TeX{} Frequently Asked Questions, and the \LaTeX{} bugs database.
-
-Older articles covering aspects of the \LaTeX3 project are also
-available for anonymous ftp from the Comprehensive \TeX{} Archive, in
-the directory:
-\begin{verbatim}
- ctan:info/ltx3pub
-\end{verbatim}
-The file |ltx3pub.bib| in that directory contains an abstract of each
-of the files.
+\section{Creating document commands and environments}
\subsection{Overview}
-This document contains an overview of the new structure and features
-of \LaTeX. It is \emph{not} a self-contained document, as it contains
-only the features of \LaTeX{} which have changed since version 2.09.
-You should read this document in conjunction with an introduction to
-\LaTeX{}.
-
-\begin{description}
-
-\item[Section~\ref{Sec:class+packages}]
- contains an overview of the new structure of
- \LaTeX{} documents. It describes how classes and packages work and
- how class and package options can be used. It lists the standard
- packages and classes which come with \LaTeX.
-
-\item[Section~\ref{Sec:commands}] describes the new commands available
- to authors in \LaTeXe.
-
-\item[Section~\ref{Sec:209}] shows how to process old \LaTeX{}
- documents with \LaTeXe.
-
-\item[Section~\ref{Sec:problems}] contains advice on dealing with
- problems you may encounter in running \LaTeXe.
- It lists some error messages which are new in \LaTeXe{} and
- it describes some of the more common problems and how to cure them,
- or where to find further information.
-
-\end{description}
-
-\subsection{Further information}
-
-For a general introduction to \LaTeX, including the new features of
-\LaTeXe, you should read \emph{\LaTeXbook}
-by Leslie Lamport~\cite{A-W:LLa94}.
-
-A more detailed description of the new features of \LaTeX, including an
-overview of more than 200 packages and nearly 1000 ready to run examples, is
-to be found in \emph{\LaTeXcomp second edition} by Frank Mittelbach and
-Michel Goossens~\cite{A-W:MG2004}.
-
-Packages and programs for producing and manipulating graphics are
-discussed at length in \emph{\LaTeXGcomp} by Michel Goossens,
-Sebastian Rahtz and Frank Mittelbach~\cite{A-W:GRM97}.
-
-Solutions for publishing with \LaTeX{} on the World Wide Web are given
-in \emph{\LaTeXWcomp} by Michel Goossens and Sebastian
-Rahtz~\cite{A-W:GR99}.
-
-For more information about the many new \LaTeX{} packages you should
-read the package documentation, which should be available from the
-same source as your copy of \LaTeX.
+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}
-There are a number of documentation files which accompany every copy
-of \LaTeX. A copy of \emph{\LaTeX{} News} will come out with each
-six-monthly release of \LaTeX; it will be found in the files
-|ltnews*.tex|. The class- and package-writer's guide \emph{\clsguide}
-describes the new \LaTeX{} features for writers of document classes
-and packages; it is in |clsguide.tex|. The guide \emph{\fntguide}
-describes the \LaTeX{} font selection scheme for class- and
-package-writers; it is in |fntguide.tex|. Support for Cyrillic languages
-in \LaTeX{} is described in \emph{\cyrguide}.
+\subsection{Modifying argument descriptions}
-The documented source code (from the files used to produce the kernel
-format via |latex.ltx|) is now available as
-\emph{The \LaTeXe\ Sources}. ]
-This very large document also includes an index of
-\LaTeX{} commands. It can be typeset from the \LaTeX{} file
-|source2e.tex| in the |base| directory, using the source files and
-the class file |ltxdoc.cls| from this directory.
+In addition to the argument \emph{types} discussed above, the argument
+description also gives special meaning to three other characters.
-For more information about \TeX{} and \LaTeX{}, please contact your
-local \TeX{} Users Group, or the international \TeX{} Users Group (see
-page \pageref{addrs}).
+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}.
-\section{Classes and packages}
-\label{Sec:class+packages}
+Thirdly, \texttt{=} is used to declare that the following argument should
+be interpreted as a series of keyvals. See Section~\ref{sec:cmd:keyval}
+for more details.
-This section describes the new structure of \LaTeX{} documents and the
-new types of file: \emph{classes} and \emph{packages}.
+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{What are classes and packages?}
+\subsection{Creating document commands and environments}
-The main difference between \LaTeX~2.09 and \LaTeXe{} is in the
-commands before |\begin{document}|.
+\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.
-In \LaTeX~2.09, documents had \emph{styles},
-such as \textsf{article} or \textsf{book}, and \emph{options},
-such as \textsf{twoside} or \textsf{epsfig}.
-These were indicated by the |\documentstyle| command:
-\begin{quote}
- |\documentstyle|\oarg{options}\arg{style}
-\end{quote}
-For example, to specify a two-sided article with encapsulated
-PostScript figures, you said:
+An example:
\begin{verbatim}
- \documentstyle[twoside,epsfig]{article}
+\NewDocumentCommand\chapter{s o m}
+ {%
+ \IfBooleanTF{#1}%
+ {\typesetstarchapter{#3}}%
+ {\typesetnormalchapter{#2}{#3}}%
+ }
\end{verbatim}
-However, there were two different types of document style option:
-\emph{built-in options} such as |twoside|; and \emph{packages} such as
-|epsfig.sty|. These were very different, since any \LaTeX{} document
-style could use the \textsf{epsfig} package but only document styles
-which declared the \textsf{twoside} option could use that option.
-
-To avoid this confusion, \LaTeXe{} differentiates between built-in
-options and packages. These are given by the new |\documentclass| and
-|\usepackage| commands:
-\begin{quote}
- |\documentclass|\oarg{options}\arg{class} \\
- |\usepackage|\oarg{options}\arg{packages}
-\end{quote}
-For example, to specify a two-sided article with encapsulated
-PostScript figures, you now write:
+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}
- \documentclass[twoside]{article}
- \usepackage{epsfig}
+\NewDocumentCommand\foo{om}{I grabbed `#1' and `#2'}
+\NewDocumentCommand\baz{o}{#1-#1}
\end{verbatim}
-You can load more than one package with a single |\usepackage|
-command; for example, rather than writing:
+using the command as
\begin{verbatim}
- \usepackage{epsfig}
- \usepackage{multicol}
+\foo[\baz[stuff]]{more stuff}
\end{verbatim}
-you can specify:
+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}
- \usepackage{epsfig,multicol}
+\NewDocumentCommand\foo{O{#2} m}
\end{verbatim}
-Note that \LaTeXe{} still understands the \LaTeX~2.09 |\documentstyle|
-command. This command causes \LaTeXe{} to enter \emph{\LaTeX~2.09
-compatibility mode}, which is described in Section~\ref{Sec:209}.
+would use the mandatory argument as the default for the leading optional
+one.
-You should not, however, use the |\documentstyle| command for new
-documents because this compatibility mode is very slow and the new
-features of \LaTeXe{} are not available in this mode.
-
-To help differentiate between classes and packages, document classes
-now end with |.cls| rather than |.sty|. Packages still end with
-|.sty|, since most \LaTeX~2.09 packages work well with \LaTeXe.
-
-\subsection{Class and package options}
-
-In \LaTeX~2.09, only document styles could have options such as
-|twoside| or |draft|. In \LaTeXe{}, both classes and packages are
-allowed to have options. For example, to specify a two-sided article
-with graphics using the |dvips| driver, you write:
+\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}
- \documentclass[twoside]{article}
- \usepackage[dvips]{graphics}
+\NewDocumentCommand\foo{m o m}{ ... }
\end{verbatim}
-It is possible for packages to share common options. For example,
-you could, in addition, load the \textsf{color} package by specifying:
+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}
- \documentclass[twoside]{article}
- \usepackage[dvips]{graphics}
- \usepackage[dvips]{color}
+\NewDocumentCommand\foobar{m o}{ ... }
\end{verbatim}
-But because |\usepackage| allows more than one package to be listed,
-this can be shortened to:
+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}
- \documentclass[twoside]{article}
- \usepackage[dvips]{graphics,color}
+\NewDocumentCommand\foobar{m !o}{ ... }
\end{verbatim}
-In addition, packages will also use each option given to
-the |\documentclass| command (if they know what to do with it), so you
-could also write:
+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}
- \documentclass[twoside,dvips]{article}
- \usepackage{graphics,color}
+\NewDocumentCommand\\{!s !o}{ ... }
\end{verbatim}
-Class and package options are covered in more detail in
-\emph{\LaTeXcomp} and in \emph{\clsguide}.
-
-\subsection{Standard classes}
-
-The following classes are distributed with \LaTeX:
-\begin{description}
-
-\item[article] The |article| class described in \emph{\LaTeXbook}.
-\item[book] The |book| class described in \emph{\LaTeXbook}.
-\item[report] The |report| class described in \emph{\LaTeXbook}.
-\item[letter] The |letter| class described in \emph{\LaTeXbook}.
-\item[slides] The |slides| class described in \emph{\LaTeXbook},
- formerly \SLiTeX.
-\item[proc] A document class for proceedings, based on |article|.
- Formerly the |proc| package.
-\item[ltxdoc] The document class for documenting the \LaTeX{}
- program, based on |article|.
-\item[ltxguide] The document class for \emph{\usrguide} and
- \emph{\clsguide}, based on |article|. The document you are reading
- now uses the |ltxguide| class. The layout for this class is likely
- to change in future releases of \LaTeX.
-\item[ltnews] The document class for the \emph{\LaTeX{} News}
- information sheet, based on |article|. The layout for this class
- is likely to change in future releases of \LaTeX.
-\item[minimal]
-\NEWfeature{1995/12/01}
- This class is the bare minimum (3 lines) that is needed in a
- \LaTeX\ class file. It just sets the text width and height, and
- defines |\normalsize|. It is principally intended for debugging
- and testing \LaTeX\ code in situations where you do not need to
- load a `full' class such as |article|. If, however, you are
- designing a completely new class that is aimed for documents with
- structure radically different from the structure supplied by the
- article class, then it may make sense to use this as a base and add
- to it code implementing the required structure, rather than
- starting from |article| and modifying the code there.
-\end{description}
-
-\subsection{Standard packages}
-\label{Sec:st-pack}
-
-The following packages are distributed with \LaTeX:
-\begin{description}
-\item[alltt]
-\NEWfeature{1994/12/01}
- This package provides the |alltt| environment, which is like
- the |verbatim| environment except that |\|, |{|, and |}|
- have their usual meanings. It is described in |alltt.dtx| and
- \emph{\LaTeXbook}.
-\item[doc] This is the basic package for typesetting the documentation
- of \LaTeX{} programs. It is described in |doc.dtx| and in
- \emph{\LaTeXcomp}.
-\item[exscale] This provides scaled versions of the math extension
- font. It is described in |exscale.dtx| and \emph{\LaTeXcomp}.
- \item[fontenc] This is used to specify which font encoding \LaTeX{}
- should use. It is described in |ltoutenc.dtx|.
-\item[graphpap]
-\NEWfeature{1994/12/01}
- This package defines the |\graphpaper| command; this
- can be used in a |picture| environment.
-\item[ifthen] Provides commands of the form `if\dots then do\dots
- otherwise do\dots'.
- It is described in |ifthen.dtx| and \emph{\LaTeXcomp}.
-\item[inputenc]
-\NEWfeature{1994/12/01}
- This is used to specify which input encoding \LaTeX{} should use.
- It is described in |inputenc.dtx|.
-\item[latexsym] \LaTeXe{} no longer loads the \LaTeX{} symbol font by
- default. To access it, you should use the |latexsym| package. It
- is described in |latexsym.dtx| and in \emph{\LaTeXcomp}; see also
- Section~\ref{Sec:problems}.
- \item[makeidx] This provides commands for producing indexes. It is
- described in \emph{\LaTeXbook} and in \emph{\LaTeXcomp}.
- \item[newlfont] This is used to emulate the font commands of
- \LaTeX~2.09 with the New Font Selection Scheme. It is described in
- \emph{\LaTeXcomp}.
- \item[oldlfont] This is used to emulate the font commands of
- \LaTeX~2.09. It is described in \emph{\LaTeXcomp}.
- \item[showidx]
- This causes the argument of each |\index| command to
- be printed on the page where it occurs.
- It is described in \emph{\LaTeXbook}.
- \item[syntonly] This is used to process a document without
- typesetting it. It is described in |syntonly.dtx| and in
- \emph{\LaTeXcomp}.
- \item[tracefnt] This allows you to control how much information about
- \LaTeX's font loading is displayed. It is described in
- \emph{\LaTeXcomp}.
-\end{description}
-
-\subsection{Related software}
-
-\NEWdescription{1998/12/01}
-The following software should be available from the same distributor
-as your copy of \LaTeXe. You should obtain at least the
-\textsf{graphics} and \textsf{tools} collections in order to have all
-the files described in \emph{\LaTeXbook}. The |amsmath| package (part
-of \textsf{amslatex} and formerly known as |amstex|)
-and \textsf{babel} are also mentioned in the list
-of `standard packages' in section C.5.2 of that book.
-\begin{description}
-\item[amslatex] Advanced mathematical typesetting from the American
- Mathematical Society. This includes the |amsmath| package; it
- provides many commands for typesetting mathematical formulas of
- higher complexity. It is produced and supported by the American
- Mathematical Society and it is described in \emph{\LaTeXcomp}.
-\item[babel] This package and related files support typesetting in
- many languages. It is described in \emph{\LaTeXcomp}.
-\item[cyrillic]
-\NEWfeature{1998/12/01}
- Everything you need (except the fonts themselves) for
- typesetting with Cyrillic fonts.
-\item[graphics] This includes the |graphics| package which
- provides support for the inclusion and transformation of graphics,
- including files produced by other software. Also included, is the
- |color| package which provides support for typesetting in colour.
- Both these packages are described in \emph{\LaTeXbook}.
-\item[psnfss] Everything you need (except the fonts themselves) for
- typesetting with a large range of Type~1 (PostScript) fonts.
-\item[tools] Miscellaneous packages written by the \LaTeX3
- project team.
-\end{description}
-These packages come with documentation and each of them is also
-described in at least one of the books \emph{\LaTeXcomp} and
-\emph{\LaTeXbook}.
-
-\subsubsection{Tools}
-
-This collection of packages includes, at least, the following (some
-files may have slightly different names on certain systems):
-
-\begin{description}
-\item[array]
- Extended versions of the environments |array|, |tabular|
- and |tabular*|, with many extra features.
-\item[calc]
-\NEWfeature{1996/12/01}
- Enables the use of certain algebraic notation when specifying
- values for lengths and counters.
-\item[dcolumn]
- Alignment on `decimal points' in tabular entries. Requires the
- |array| package.
-\item[delarray]
- Adds `large delimiters' around arrays. Requires |array|.
-\item[hhline]
- Finer control over horizontal rules in tables. Requires |array|.
-\item[longtable]
- Multi-page tables. (Does not require |array|, but it uses the
- extended features if both are loaded.)
-\item[tabularx]
- Defines a |tabularx| environment that is similar to |tabular*|
- but it modifies the column widths, rather than the inter-column
- space, to achieve the desired table width.
-\item[afterpage]
- Place text after the current page.
-\item[bm]
- Access bold math symbols.
-\item[enumerate]
- Extended version of the |enumerate| environment.
-\item[fontsmpl]
- Package and test file for producing `font samples'.
-\item[ftnright]
- Place all footnotes in the right-hand column in two-column mode.
-\item[indentfirst]
- Indent the first paragraph of sections, etc.
-\item[layout]
- Show the page layout defined by the current document class.
-\item[multicol]
- Typeset text in columns, with the length of the columns
- `balanced'.
-\item[rawfonts]
- Preload fonts using the old internal font names of \LaTeX~2.09.
- See Section~\ref{Sec:oldinternals}.
-\item[somedefs]
- Selective handling of package options. (Used by the rawfonts
- package.)
-\item[showkeys]
- Prints the `keys' used by |\label|, |\ref|, |\cite| etc.; useful
- whilst drafting.
-\item[theorem]
- Flexible declaration of `theorem-like' environments.
-\item[varioref]
- `Smart' handling of page references.
-\item[verbatim]
- Flexible extension of the verbatim environment.
-\item[xr]
- Cross reference other `external' documents.
-\item[xspace]
- `Smart space' command that helps you to avoid the common mistake
- of missing spaces after command names.
-\end{description}
-
-
-\section{Commands}
-\label{Sec:commands}
-
-This section describes the new commands available in \LaTeXe.
-They are covered in more detail in \emph{\LaTeXbook} and in
-\emph{\LaTeXcomp}.
-
-\subsection{Preamble commands}
-\label{Sec:pre}
-
-The changes to the preamble commands are intentionally designed to make
-\LaTeXe{} documents look clearly different from old documents. The
-commands should be used only before |\begin{document}|.
-\begin{decl}
-|\documentclass| \oarg{option-list} \arg{class-name}
- \oarg{release-date}
-\end{decl}
-
-This command replaces the
-\LaTeX~2.09 command |\documentstyle|.
-
-There must be exactly one |\documentclass| command in a document; and
-it should normally come before any other command. (There are some
-exceptions, e.g., you can have |filecontents| environments before it
-or |\RequirePackage| but these should be only used in special
-scenarios as discussed elsewhere.)
+\subsection{`Embellishments'}
+\label{sec:cmd:embellishment}
-The \m{option-list} is a list of options, each of which may modify the
-formatting of elements which are defined in the \m{class-name} file,
-as well as those in all following |\usepackage| commands (see
-below).
-
-The optional argument \m{release-date} can be used to specify the
-earliest desired release date of the class file; it should contain a
-date in the format \textsc{yyyy/mm/dd}. If a version of the class
-older than this date is found, a warning is issued.
-
-For example, to specify a two-column article, using a version of
-|article.cls| released after June 1994, you specify:
+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}
- \documentclass[twocolumn]{article}[1994/06/01]
+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.
-\begin{decl}
-|\documentstyle| \oarg{option-list} \arg{class-name}
-\end{decl}
-
-This command is still supported for compatibility with old files. It
-is essentially the same as |\documentclass| except that it invokes
-\emph{\LaTeX~2.09 compatibility mode}. It also causes any options in
-the \m{option-list} that are not processed by the class file to be
-loaded as packages after the class has been loaded. See
-Section~\ref{Sec:209} for more details on \LaTeX~2.09 compatibility
-mode.
-
-\begin{decl}
-|\usepackage| \oarg{option-list} \arg{package-name} \oarg{release-date}
-\end{decl}
-Any number of |\usepackage| commands is allowed. Each package file
-(as denoted by \m{package-name}) defines new elements (or modifies
-those defined in the class file loaded by the \m{class-name} argument
-of the |\documentclass| command). A package file thus extends the
-range of documents which can be processed.
+\subsection{Testing special values}
+\label{sec:cmd:special}
-The \m{option-list} argument can contain a list of options, each of
-which can modify the formatting of elements which are defined in this
-\m{package-name} file.
+Optional arguments make use of dedicated variables to return information about
+the nature of the argument received.
-As above, \m{release-date} can contain the earliest desired release
-date of the package file in the format \textsc{yyyy/mm/dd}; if an
-older version of the package is found, a warning is issued.
-For example, to load the |graphics| package for the |dvips| driver,
-using a version of |graphics.sty| released after June 1994, you write:
-\begin{verbatim}
- \usepackage[dvips]{graphics}[1994/06/01]
-\end{verbatim}
-Each package is loaded only once. If the same package is requested
-more than once, nothing happens in the second or following attempt
-unless the package has been requested with options that were not given
-in the original |\usepackage|. If such extra options are specified
-then an error message is produced. See Section~\ref{Sec:problems} how
-to resolve this problem.
-
-As well as processing the options given in the \m{option-list} of the
-|\usepackage| command, each package processes the
-\m{option-list} of the |\documentclass| command as well. This
-means that any option which should be processed by every package (to
-be precise, by every package that specifies an action for it) can be
-specified just once, in the |\documentclass| command, rather than
-being repeated for each package that needs it.
\begin{decl}
-|\listfiles|
+ |\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.
-If this command is placed in the preamble then a list of the files
-read in (as a result of processing the document) will be displayed
-on the terminal (and in the log file) at the end of the run. Where
-possible, a short description will also be produced.
+Note that three tests are available, depending on which outcome
+branches are required: \cs{IfNoValueTF}, \cs{IfNoValueT} and
+\cs{IfNoValueF}.
-\NEWdescription{1995/12/01}
-\emph{Warning}: this command will list only files which were read
-using \LaTeX{} commands such as |\input|\arg{file} or
-|\include|\arg{file}. If the file was read using the primitive \TeX{}
-syntax |\input |\emph{file} (without |{ }| braces around the file name)
-then it will not be listed; failure to use the \LaTeX{} form with the
-braces can cause more severe problems, possibly leading to overwriting
-important files, so \textbf{always put in the braces}.
+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}
-|\setcounter{errorcontextlines}| \arg{num}
+ |\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.
-\TeX~3 introduced a new primitive |\errorcontextlines| which controls
-the format of error messages. \LaTeXe\ provides an interface to this
-through the standard |\setcounter| command. As most \LaTeX\ users do
-not want to see the internal definitions of \LaTeX\ commands each time
-they make an error, \LaTeXe{} sets this to $-1$ by default.
-\subsection{Environments to write out support files}
-\NEWfeature{2019}
-%
-Until the \LaTeX\ release in 2019 the |filecontents| environment was
-restricted to a place before the |\documentclass| command. These days
-it can be used anywhere, though we still think that in most cases it is
-best to only use it a the top of your document or in the preamble.
-\begin{decl}
-|\begin{filecontents}| \oarg{option-list} \arg{file-name} \\
- \m{file-contents} \\
-|\end{filecontents}|
+\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 |filecontents| environment is intended for bundling within a
-single document file the contents of packages, options, or other
-files. When the document file is run through \LaTeXe{} the body of
-this environment is written verbatim (preceded by a comment line) to a
-file whose name is given as the environment's only argument. However,
-if that file already exists then nothing happens except for an
-information message.
-These days most UTF-8 text characters can be used in a
-|filecontents| envi\-ronment---they will be written unchanged to the
-output file. However, tabs and form feeds produce a warning,
-explaining that they are turned into spaces or blank lines,
-respectively.
-
-By default the environment does not overwrite an existing file and it
-even refuses to write out the data if there exists a file that is
-anywhere in the path that \TeX\ searches when inputting files. With
-the option |nosearch| you can ask it to look only into the current
-directory and with the option |overwrite| (or |force|) you can request
-it to write the file regardless. It will, however, never write to
-|\jobname.tex| to avoid overwriting itself.
+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}
-The |filecontents| environment is used for including \LaTeX{} files.
-For other plain text files (such as Encapsulated PostScript files),
-you should use the |filecontents*| environment which does not add a
-comment line.
+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.
-\subsection{Document structure}
+\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.
-The |book| document class introduces new commands to indicate
-document structure.
\begin{decl}
-|\frontmatter| \\ |\mainmatter| \\ |\backmatter|
+ |\IfBooleanTF| \arg{arg} \arg{true code} \arg{false code} \\
+ |\IfBooleanT| \arg{arg} \arg{true code} \\
+ |\IfBooleanF| \arg{arg} \arg{false code}
\end{decl}
-These commands indicate the beginning of the front matter (title page,
-table of contents and prefaces), main matter (main text) and back
-matter (bibliography, indexes and colophon).
+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{Auto-converting to key--value format}
+\label{sec:cmd:keyval}
+
+Some document commands have a long history of accepting a `free text' optional
+argument, for example \cs{caption} and the sectioning commands \cs{section},
+etc. Introducing more sophisticated (keyval) options to these commands
+therefore needs a method to interpret the optional argument \emph{either} as
+free text \emph{or} as a series of keyvals. This needs to take place
+during argument grabbing as there is a need for careful treatment of
+braces to obtain the correct result.
+
+The \texttt{=} modifier is available to allow \pkg{ltcmd} to correctly
+implement this process. The modifier guarantees that the argument will be
+passed to further code as a series of keyvals. To do that, the \texttt{=}
+should be followed by an argument containing the default key name. This is used
+as the key in a key--value pair \emph{if} the `raw' argument does \emph{not}
+have the correct form to be interpreted as a set of keyvals.
+
+Taking \cs{caption} as an example, with the demonstration implementation
+\begin{verbatim}
+\DeclareDocumentCommand
+ \caption
+ {s ={short-text} +O{#3} +m}
+ {%
+ \showtokens{Grabbed arguments:^^J(#2)^^Jand^^J(#3)}%
+ }
+\end{verbatim}
+the default key name is \texttt{short-text}. When the command \cs{caption} is
+then used, if the optional argument is free text such as
+\begin{verbatim}
+\caption[Some short text]{A much longer and more detailed text for
+ demonstration purposes}
+\end{verbatim}
+then the output will be
+\begin{verbatim}
+Grabbed arguments:
+(short-text={Some short text})
+and
+(A much longer and more detailed text for demonstration purposes)
+\end{verbatim}
+On the other hand, if the caption is given with a keyval-form argument
+\begin{verbatim}
+\caption[label = cap:demo]%
+ {A much longer and more detailed text for demonstration purposes}
+\end{verbatim}
+then this will be respected
+\begin{verbatim}
+Grabbed arguments:
+(label = cap:demo)
+and
+(A much longer and more detailed text for demonstration purposes)
+\end{verbatim}
-\subsection{Definitions}
+Interpretation as keyval form is determined by the presence of \texttt{=}
+characters within the argument. Those in inline math mode (enclosed within
+\verb|$...$| or \verb|\(...\)|) are ignored. An argument can be forced to be
+read as keyvals by including an empty entry at the start
+\begin{verbatim}
+\caption[=,This is now a keyval]%
+% ...
+\caption[This is not $=$ keyval]%
+\end{verbatim}
-In \LaTeX, commands can have both mandatory and optional arguments,
-for example in:
+This empty entry is \emph{not} passed to the underlying code, so will not lead
+to issues with keyval parsers that do not allow an empty key name. Any text-mode
+\texttt{=} signs will need to be braced to avoid being misinterpreted: this
+is likely most conveniently handled by bracing the entire argument
\begin{verbatim}
- \documentclass[11pt]{article}
+\caption[{Not = to a keyval!}]%
+\end{verbatim}
+which will be passed correctly as
+\begin{verbatim}
+Grabbed arguments:
+(short-text = {Not = to a keyval!})
\end{verbatim}
-the |11pt| argument is optional, whereas the |article| class name is
-mandatory.
-In \LaTeX~2.09 users could define commands with arguments, but these
-had to be mandatory arguments. With \LaTeXe, users can now define
-commands and environments which also have one optional argument.
+\subsection{Argument processors}
+\label{sec:cmd:processors}
-\begin{decl}
-|\newcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\
-|\newcommand*| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\
-|\renewcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\
-|\renewcommand*| \arg{cmd} \oarg{num} \oarg{default} \arg{definition}
-\end{decl}
+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.
-These commands have a new, second, optional argument; this is used for
-defining commands which themselves take one optional argument. This
-new argument is best introduced by means of a simple (and hence not
-very practical) example:
+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}
- \newcommand{\example}[2][YYY]{Mandatory arg: #2;
- Optional arg: #1.}
+>{\ProcessorB} >{\ProcessorA} m
\end{verbatim}
-This defines |\example| to be a command with two arguments, referred
-to as |#1| and |#2| in the \arg{definition}---nothing new so far. But
-by adding a second optional argument to this |\newcommand| (the
-|[YYY]|) the first argument (|#1|) of the newly defined command
-|\example| is made optional with its default value being |YYY|.
+would apply \cs{ProcessorA} followed by \cs{ProcessorB} to the tokens grabbed
+by the \texttt{m} argument.
-Thus the usage of |\example| is either:
+\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}
- \example{BBB}
+\NewDocumentCommand \foo {>{\SplitArgument{2}{;}} m}
+ {\InternalFunctionOfThreeArguments#1}
\end{verbatim}
-which prints:
-\begin{quote}
- Mandatory arg: BBB;
- Optional arg: YYY.
-\end{quote}
-or:
+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}
- \example[XXX]{AAA}
+\NewDocumentCommand \foo { >{\TrimSpaces} e{_^} }
+ { [#1](#2) }
\end{verbatim}
-which prints:
-\begin{quote}
- Mandatory arg: AAA;
- Optional arg: XXX.
-\end{quote}
-
-The default value of the optional argument is \texttt{YYY}.
-This value is specified as the \oarg{default} argument of the
-|\newcommand| that created |\example|.
+applies \cs{TrimSpaces} to both arguments.
-As another more useful example, the definition:
+\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}
- \newcommand{\seq}[2][n]{\lbrace #2_{0},\ldots,\,#2_{#1} \rbrace}
+\NewDocumentCommand \foo {>{\SplitList{;}} m}
+ {\MappingFunction#1}
\end{verbatim}
-means that the input |$\seq{a}$| produces
-the formula $\lbrace a_{0},\ldots,\,a_{n} \rbrace$,
-whereas the input |$\seq[k]{x}$| produces the formula
-$\lbrace x_{0},\ldots,\,x_{k} \rbrace$.
-
-In summary, the command:
-\begin{quote}
- |\newcommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition}
-\end{quote}
-defines \m{cmd} to be a command with \m{num} arguments, the first of
-which is optional and has default value \m{default}.
-
-Note that there can only be one optional argument but, as before,
-there can be up to nine arguments in total.
+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}
-|\newenvironment|
- \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def} \\
-|\newenvironment*|
- \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def} \\
-|\renewenvironment|
- \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def} \\
-|\renewenvironment*|
- \arg{cmd} \oarg{num} \oarg{default} \arg{beg-def} \arg{end-def}
+ |\ProcessList| \arg{list} \arg{function}
\end{decl}
-
-\LaTeXe\ also supports the creation of environments that have one
-optional argument. Thus the syntax of these two commands has
-been extended in the same way as that of |\newcommand|.
+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}
-|\providecommand| \arg{cmd} \oarg{num} \oarg{default} \arg{definition} \\
-|\providecommand*| \arg{cmd} \oarg{num} \oarg{default} \arg{definition}
+ |\ReverseBoolean|
\end{decl}
-
-This takes the same arguments as |\newcommand|. If \m{cmd} is already
-defined then the existing definition is kept; but if it is currently
-undefined then the effect of |\providecommand| is to define \m{cmd}
-just as if |\newcommand| had been used.
-
-\NEWfeature{1994/12/01}
- All the above five `defining commands' now have \texttt{*}-forms that
- are usually the better form to use when defining commands with
- arguments, unless any of these arguments is intended to contain
- whole paragraphs of text. Moreover, if you ever do find yourself
- needing to use the non-star form then you should ask whether
- that argument would not better be treated as the contents of a
- suitably defined environment.
-
-\NEWfeature{1995/12/01}
- The commands produced by the above five `defining commands' are
- now robust.
-
-\subsection{Boxes}
-
-These next three commands for making LR-boxes all existed in
-\LaTeX~2.09. They have been enhanced in two ways.
+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}
-|\makebox| \oarg{width} \oarg{pos} \arg{text} \\
-|\framebox| \oarg{width} \oarg{pos} \arg{text} \\
-|\savebox| \arg{cmd} \oarg{width} \oarg{pos} \arg{text}
+ |\TrimSpaces|
\end{decl}
-
-One small but far-reaching change for \LaTeXe\ is that, within the
-\m{width} argument only, four special lengths can be used. These are
-all dimensions of the box that would be produced by using simply
-|\mbox|\arg{text}:
-\begin{itemize}
-\item [] |\height|\quad its height above the baseline;
-\item [] |\depth|\quad its depth below the baseline;
-\item [] |\totalheight|\quad the sum of |\height| and |\depth|;
-\item [] |\width|\quad its width.
-\end{itemize}
-Thus, to put `hello' in the centre of a box of twice its natural
-width, you would use:
+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}
- \makebox[2\width]{hello}
+\NewDocumentCommand\foo {>{\TrimSpaces} m}
+ {\showtokens{#1}}
\end{verbatim}
-Or you could put \textit{f} into a square box, like
-this:
- \framebox{\makebox[\totalheight]{\itshape f\/}}
+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}
- \framebox{\makebox[\totalheight]{\itshape f\/}}
+\NewDocumentEnvironment{twice} {O{\ttfamily} +b}
+ {#2#1#2} {}
+\begin{twice}[\itshape]
+ Hello world!
+\end{twice}
\end{verbatim}
-Note that it is the total width of the framed box, including the
-frame, which is set to |\totalheight|.
+typesets `Hello world!{\itshape Hello world!}'.
-The other change is a new possibility for \m{pos}: |s| has been added
-to |l| and |r|. If \m{pos} is |s| then the text is stretched the full
-length of the box, making use of any `rubber lengths' (including any
-inter-word spaces) in the contents of the box. If no such `rubber
-length' is present, an `underfull box' will probably be produced.
+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.
-\begin{decl}
-|\parbox| \oarg{pos} \oarg{height} \oarg{inner-pos} \arg{width}
- \arg{text} \\
-|\begin{minipage}|
- \oarg{pos} \oarg{height} \oarg{inner-pos} \arg{width}\\
-\m{text}\\
-|\end{minipage}|
-\end{decl}
+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.
-As for the box commands above, |\height|, |\width|, etc.~may be used
-in the \oarg{height} argument to denote the natural dimensions of the
-box.
+Environments that use this feature can be nested.
-The \m{inner-pos} argument is new in \LaTeXe. It is the vertical
-equivalent to the \m{pos} argument for |\makebox|, etc, determining
-the position of \m{text} within the box. The \m{inner-pos} may be any
-one of |t|, |b|, |c|, or |s|, denoting top, bottom, centered, or
-`stretched' alignment respectively. When the \m{inner-pos} argument
-is not specified, \LaTeX\ gives it same value as \m{pos} (this could be
-the latter's default value).
+\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}
-|\begin{lrbox}| \arg{cmd}\\
-\m{text}\\
-|\end{lrbox}|
+ |\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}
-This is an environment which does not directly print anything.
-Its effect is to save the typeset \m{text} in the bin \m{cmd}. Thus
-it is like |\sbox| \arg{cmd} \arg{text}, except that any white space
-before or after the contents \m{text} is ignored.
-
-This is very useful as it enables both the |\verb| command and the
-\texttt{verbatim} environment to be used within \m{text}.
-
-It also makes it possible to define, for example, a `framed box'
-environment. This is done by first using this environment to save
-some text in a bin \m{cmd} and then calling
-|\fbox{\usebox{|\m{cmd}|}}|.
-
-The following example defines an environment, called |fmpage|, that is
-a framed version of |minipage|.
+\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}
- \newsavebox{\fmbox}
- \newenvironment{fmpage}[1]
- {\begin{lrbox}{\fmbox}\begin{minipage}{#1}}
- {\end{minipage}\end{lrbox}\fbox{\usebox{\fmbox}}}
+\NewDocumentCommand { \foobar } { D<>{default} } {(#1)}
+\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{Measuring things}
-
-The first of these next commands was in \LaTeX~2.09. The two new
-commands are the obvious analogues.
+\subsection{Creating new argument processors}
\begin{decl}
-|\settowidth| \arg{length-cmd} \arg{lr text} \\
-|\settoheight| \arg{length-cmd} \arg{lr text} \\
-|\settodepth| \arg{length-cmd} \arg{lr text}
+ |\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{Line endings}
+\subsection{Access to the argument specification}
-\NEWdescription{1994/12/01}
-The command |\\|, which is used to indicate a line-end in various
-places, is now a robust command when used within arguments such as
-section titles.
+The argument specifications for document commands and environments are
+available for examination and use.
-Also, because it is often necessary to distinguish which type of line
-is to be ended, we have introduced the following new command; it
-has the same argument syntax as that of |\\|.
-\begin{decl}[1994/12/01]
-|\tabularnewline| \oarg{vertical-space}
+\begin{decl}
+ |\GetDocumentCommandArgSpec| \arg{function} \\
+ |\GetDocumentEnvironmentArgSpec| \arg{environment}
\end{decl}
-One example of its use is when the text in the last
-column of a |tabular| environment is set with |\raggedright|; then
-|\tabularnewline| can be used to indicate the end of a row of the
-|tabular|, whilst |\\| will indicate the end of a line of text in a
-paragraph within the column. This command can be used in the |array|
-environment as well as |tabular|, and also the extended versions of
-these environments offered by the \textsf{array} and \textsf{longtable}
-packages in the tools collection.
-
-\subsection{Controlling page breaks}
-
-Sometimes it is necessary, for a final version of a document, to
-`help' \LaTeX\ break the pages in the best way. \LaTeX~2.09 had a
-variety of commands for this situation: |\clearpage|, |\pagebreak|
-etc. \LaTeXe\ provides, in addition, commands which can produce
-longer pages as well as shorter ones.
-
+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}
-|\enlargethispage| \arg{size} \\
-|\enlargethispage*| \arg{size}
+ |\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.
-These commands increase the height of a page (from its normal value of
-|\textheight|) by the specified amount \m{size}, a rigid length. This
-change affects \emph{only} the current page.
-This can be used, for example, to allow an extra line to be fitted
-onto the page or, with a negative length, to produce a page
-shorter than normal.
-The star form also shrinks any vertical white space on the page as
-much as possible, so as to fit the maximum amount of text on the
-page.
+\section{Copying and showing (robust) commands}
-\NEWdescription{1995/12/01}
-These commands do not change the position of the footer text; thus, if
-a page is lengthened too far, the main text may overprint the footer.
+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.
-\subsection{Floats}
-
-There is a new command, |\suppressfloats|, and a new `float
-specifier'. These will enable people to gain better
-control of \LaTeX's float placement algorithm.
+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}
-|\suppressfloats| \oarg{placement}
+ |\NewCommandCopy| \arg{cmd} \arg{existing-cmd} \\
+ |\RenewCommandCopy| \arg{cmd} \arg{existing-cmd} \\
+ |\DeclareCommandCopy| \arg{cmd} \arg{existing-cmd}
\end{decl}
-This command stops any further floating environments from being placed
-on the current page. With an optional argument, which should be either
-|t| or |b| (not both), this restriction applies only to putting
-further floats at the top or at the bottom. Any floats which would
-normally be placed on this page are placed on the next page instead.
-
-\begin{decl}
-The extra float location specifier: \ \texttt{!}
-\end{decl}
-
-This can be used, along with at least one of \texttt{h}, \texttt{t},
-\texttt{b} and \texttt{p}, in the location optional argument of a
-float.
-
-If a \texttt{!} is present then, just for this particular float,
-whenever it is processed by the float mechanism the following are
-ignored:
-\begin{itemize}
-\item all restrictions on the number of floats which can appear;
-\item all explicit restrictions on the amount of space on a text page
-which may be occupied by floats or must be occupied by text.
-\end{itemize}
-The mechanism will, however, still attempt to ensure that pages are
-not overfull and that floats of the same type are printed in the
-correct order.
+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).
-Note that its presence has no effect on the production of float pages.
+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.
-A \texttt{!} specifier overrides the effect of any |\suppressfloats|
-command for this particular float.
-\subsection{Font changing: text}
+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}.
-The font selection scheme used in \LaTeXe{} differs a lot from that
-used in \LaTeX~2.09. In this section, we give a brief description of
-the new commands. A more detailed description with examples is given
-in \emph{\LaTeXcomp}, and the interface for class- and package-writers
-is described in \emph{\fntguide}.
-\begin{decl}
-|\normalfont|\\
-|\rmfamily|\\
-|\sffamily|\\
-|\ttfamily|\\
-|\mdseries|\\
-|\bfseries|\\
-|\upshape|\\
-|\itshape|\\
-|\slshape|\\
-|\scshape|
-\end{decl}
-These are font commands whose use is the same as the commands |\rm|,
-|\bf|, etc. The difference is that each command changes just one
-attribute of the font (the attribute changed is part of the name).
-One result of this is that, for example, |\bfseries\itshape| produces
-both a change of series and a change of shape, to give a bold italic
-font.
\begin{decl}
-|\textnormal|\arg{text}\\
-|\textrm|\arg{text}\\
-|\textsf|\arg{text}\\
-|\texttt|\arg{text}\\
-|\textmd|\arg{text}\\
-|\textbf|\arg{text}\\
-|\textup|\arg{text}\\
-|\textit|\arg{text}\\
-|\textsl|\arg{text}\\
-|\textsc|\arg{text}\\
-|\emph|\arg{text}
+ |\ShowCommand| \arg{cmd}
\end{decl}
-These are one-argument commands; they take as an argument the
-text which is to be typeset in the particular font. They also
-automatically insert italic corrections where appropriate; if you do
-not like the result, you can add an italic correction with |\/| or
-remove it with |\nocorr|. The |\nocorr| should always be the first or
-last thing within the \arg{text} argument.
-
-\subsection{Font changing: math}
-
-Most of the fonts used within math mode do not need to be explicitly
-invoked; but to use letters from a range of fonts, the following
-class of commands is provided.
+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.
-\begin{decl}
-|\mathrm| \arg{letters}\\
-|\mathnormal| \arg{letters}\\
-|\mathcal| \arg{letters}\\
-|\mathbf| \arg{letters}\\
-|\mathsf| \arg{letters}\\
-|\mathtt| \arg{letters}\\
-|\mathit| \arg{letters}
-\end{decl}
-These are also one-argument commands which take as an argument the
-letters which are to be typeset in the particular font. The argument
-is processed in math mode so spaces within it will be ignored. Only
-letters, digits and accents have their font changed, for example
-|$\mathbf{\tilde A \times 1}$| produces $\mathbf{\tilde A \times 1}$.
+\section[Preconstructing command names \\ (or otherwise expanding arguments)]
+ {Preconstructing command names (or otherwise expanding arguments)}
+\label{sec:preconstructing-csnames}
-\subsection{Ensuring math mode}
+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}
-|\ensuremath| \arg{math commands}
+ |\UseName| \arg{string} \\
+ |\ExpandArgs| \arg{spec} \arg{cmd} \arg{arg1} \dots
\end{decl}
-In \LaTeX~2.09, if you wanted a command to work both in math mode and
-in text mode, the suggested method was to define something like:
+\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}
- \newcommand{\Gp}{\mbox{$G_p$}}
+\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}
-Unfortunately, the |\mbox| stops |\Gp| changing size correctly in (for
-instance) subscripts or a fraction.
+Given that declaration you can then write
+\verb/\newcopyedit{note}[blue]/ which defines the command \cs{note}
+and the corresponding counter for you.
-In \LaTeXe{} you can define it thus:
+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}
- \newcommand{\Gp}{\ensuremath{G_p}}
+\NewDocumentCommand\savebyname{m}
+ {\ExpandArgs{cc}\NewCommandCopy{saved#1}{#1}}
\end{verbatim}
-Now |\Gp| will work correctly in all contexts.
-
-This is because the |\ensuremath| does nothing, producing simply
-|G_p|, when |\Gp| is used within math mode; but it ensures that math
-mode is entered (and exited) as required when |\Gp| is used in text
-mode.
-
-
-\subsection{Setting text superscripts}
-\begin{decl}
-|\textsuperscript| \arg{text}
-\end{decl}
-
-\NEWfeature{1995/06/01} In \LaTeX~2.09 textual superscripts such as
-footnote markers were produced by internally entering math mode and
-typesetting the number as a math superscript. This normally looked
-fine since the digits in math fonts are the same as those in text
-fonts when Computer Modern fonts are used. But when a different
-document font (such as Times) is selected, the results look rather
-strange. For this reason the command |\textsuperscript| has been
-introduced which typesets its argument in the current text font, in a
-superscript position and in the correct size.
-
-\subsection{Text commands: all encodings}
-
-\NEWdescription{1994/12/01}
- One of the main differences between \LaTeXe{} and \LaTeX~2.09 is
- that \LaTeXe{} can deal with fonts in arbitrary \emph{encodings}.
- (A font encoding is the sequence of characters in the font---for
- example a Cyrillic font would have a different encoding from a Greek
- font.)
-
- The two major font encodings that are used for Latin languages such
- as English or German are |OT1| (Donald Knuth's 7-bit encoding, which
- has been used during most of \TeX's lifetime) and |T1| (the new
- 8-bit `Cork' encoding).
-
- \LaTeX~2.09 only supported the |OT1| encoding, whereas \LaTeXe{} has
- support for both |OT1| and |T1| built-in. The next section will
- cover the new commands which are available if you have |T1|-encoded
- fonts. This section describes new commands which are available in
- all encodings.
-
- Most of these commands provide characters which were available in
- \LaTeX~2.09 already. For example |\textemdash| gives an `em dash',
- which was available in \LaTeX~2.09 by typing |---|. However, some
- fonts (for example a Greek font) may not have the |---| ligature,
- but you will still be able to access an em dash by typing
- |\textemdash|.
-
-\begin{decl}[1994/12/01]
- |\r{<text>}|
-\end{decl}
- This command gives a `ring' accent, for example `\r{o}' can be typed
- |\r{o}|.
-
-\begin{decl}[1994/12/01]
- |\SS|
-\end{decl}
- This command produces a German `SS', that is a capital `\ss'. This
- letter can hyphenate differently from `SS', so is needed for entering
- all-caps German.
-
-\begin{decl}[1994/12/01]
- |\textcircled{<text>}|
-\end{decl}
- This command is used to build `circled characters' such as
- |\copyright|. For example |\textcircled{a}| produces
- \textcircled{a}.
-
-\begin{decl}[1994/12/01]
- |\textcompwordmark|
-\end{decl}
- This command is used to separate letters which would normally
- ligature. For example `f\textcompwordmark i' is produced with
- |f\textcompwordmark i|. Note that the `f' and `i' have not
- ligatured to produce `fi'. This is rarely useful in English
- (`shelf\textcompwordmark ful' is a rare example of where it might be
- used) but is used in languages such as German.
-
-\begin{decl}[1994/12/01]
- |\textvisiblespace|
-\end{decl}
- This command produces a `visible space' character
- `\textvisiblespace'. This is sometimes used in computer listings,
- for example `type \textsf{hello\textvisiblespace world}'.
-
-\begin{decl}[1994/12/01]
- |\textemdash|
- |\textendash|
- |\textexclamdown|
- |\textquestiondown| \\
- |\textquotedblleft|
- |\textquotedblright|
- |\textquoteleft|
- |\textquoteright|
-\end{decl}
- These commands produce characters which would otherwise be
- accessed via ligatures:
- \begin{center}
- \begin{tabular}{ccl}
- \emph{ligature} & \emph{character} & \emph{command} \\
- |---| & --- & |\textemdash| \\
- |--| & -- & |\textendash| \\
- |!`| & !` & |\textexclamdown| \\
- |?`| & ?` & |\textquestiondown| \\
- |``| & `` & |\textquotedblleft| \\
- |''| & '' & |\textquotedblright| \\
- |`| & ` & |\textquoteleft| \\
- |'| & ' & |\textquoteright|
- \end{tabular}
- \end{center}
- The reason for making these characters directly accessible is so
- that they will work in encodings which do not have these characters.
-
-\begin{decl}[1994/12/01]
- |\textbullet|
- |\textperiodcentered|
-\end{decl}
- These commands allow access to characters which were previously only
- available in math mode:
- \begin{center}
- \begin{tabular}{lcl}
- \emph{math command} & \emph{character} & \emph{text command} \\
- |\bullet| & $\bullet$ & |\textbullet| \\
- |\cdot| & $\cdot$ & |\textperiodcentered|
- \end{tabular}
- \end{center}
-
-\begin{decl}[1995/12/01]
- |\textbackslash|
- |\textbar|
- |\textless|
- |\textgreater|
-\end{decl}
- These commands allow access to ASCII characters which were
- only available in verbatim or math mode:
- \begin{center}
- \begin{tabular}{lcl}
- \emph{math command} & \emph{character} & \emph{text command} \\
- |\backslash| & $\backslash$ & |\textbackslash| \\
- |\mid| & $\mid$ & |\textbar| \\
- |<<| & $<$ & |\textless| \\
- |>>| & $>$ & |\textgreater|
- \end{tabular}
- \end{center}
-
-\begin{decl}[1995/12/01]
- |\textasciicircum|
- |\textasciitilde|
-\end{decl}
- These commands allow access to ASCII characters which were
- previously only available in verbatim:
- \begin{center}
- \begin{tabular}{cl}
- \emph{verbatim} & \emph{text command} \\
- |^| & |\textasciicircum| \\
- |~| & |\textasciitilde|
- \end{tabular}
- \end{center}
-
-\begin{decl}[1995/12/01]
- |\textregistered|
- |\texttrademark|
-\end{decl}
- These commands provide the `registered trademark' (R) and
- `trademark' (TM) symbols.
-
-\subsection{Text commands: the T1 encoding}
-
-\NEWdescription{1994/12/01}
- The |OT1| font encoding is fine for typesetting in English, but has
- problems when typesetting other languages. The |T1| encoding solves
- some of these problems, by providing extra characters (such as `eth'
- and `thorn'), and it allows words containing accented letters to be
- hyphenated (as long as you have a package like |babel| which allows
- for non-American hyphenation).
-
- This section describes the commands you can use if you have the |T1|
- fonts. To use them, you need to get the `ec fonts', or the
- |T1|-encoded PostScript fonts, as used by \textsf{psnfss}.
- All these fonts are
- available by anonymous ftp in the Comprehensive \TeX{} Archive, and
- are also available on the CD-ROMs \emph{4all \TeX} and
- \emph{\TeX{} Live} (both available from the \TeX{} Users Group).
-
- You can then select the |T1| fonts by saying:
+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}
- \usepackage[T1]{fontenc}
+\ExpandArgs{Nc}\NewCommandCopy\mysectionctr{c@section}
\end{verbatim}
- This will allow you to use the commands in this section.
+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}.
- \emph{Note:} Since this document must be processable on any site
- running an up-to-date \LaTeX, it does not contain any characters
- that are present only in |T1|-encoded fonts. This means that this
- document cannot show you what these glyphs look like! If you want
- to see them then run \LaTeX{} on the document |fontsmpl| and
- respond `|cmr|' when it prompts you for a family name.
-\begin{decl}[1994/12/01]
- |\k{<text>}|
-\end{decl}
- This command produces an `ogonek' accent.
-
-\begin{decl}[1994/12/01]
- |\DH|
- |\DJ|
- |\NG|
- |\TH|
- |\dh|
- |\dj|
- |\ng|
- |\th|
-\end{decl}
- These commands produce characters `eth', `dbar', `eng', and `thorn'.
-
-\begin{decl}[1994/12/01]
- |\guillemotleft|
- |\guillemotright|
- |\guilsinglleft|
- |\guilsinglright| \\
- |\quotedblbase|
- |\quotesinglbase|
- |\textquotedbl|
-\end{decl}
- % A local hack (could be improved):
- \newcommand{\fauxguillemet}[1]{$\vcenter{\hbox{$\scriptscriptstyle#1$}}$}
- These commands produce various sorts of quotation mark.
- Rough representations of them are:
- \fauxguillemet\ll a\fauxguillemet\gg{}
- \fauxguillemet<a\fauxguillemet>
- ,\kern -0.1em,\kern 0.05em a\kern -0.05em``
- ,\kern 0.05em a\kern -0.05em` and |"|a|"|.
-
-\NEWdescription{2001/06/01}
- There are therefore some extra short-form ligatures available for
- use in documents that will only be used with |T1|-encoded fonts.
-
- The guillemets |\guillemotleft| and |\guillemotright|%
- \footnote{We apologise once again for maintaining Adobe's
- enormous solipsism~(sic) of confusing a diving bird with
- punctuation marks!}
- can be obtained by typing |<<<<| and |>>>>| and |\quotedblbase|
- by typing |,,|\,.
-
- Also, unlike the unexpected results with
- |OT1|-encoded fonts, |<<| and |>>| will produce \textless{} and
- \textgreater{}.
-
- Note also that the single character |"| will no longer produce ''
- but rather |\textquotedbl|.
-
-\subsection{Logos}
-\begin{decl}
-|\LaTeX|\\
-|\LaTeXe|
-\end{decl}
+\section{Expandable floating point (and other) calculations}
-|\LaTeX| (producing `\LaTeX') is still the `main' logo command,
-but if you need to refer to the new features, you can write
-|\LaTeXe| (producing `\LaTeXe').
+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.
-\subsection{Picture commands}
\begin{decl}
- |\qbezier[<N>](<AX>,<AY>)(<BX>,<BY>)(<CX>,<CY>)| \\
- | \bezier{<N>}(<AX>,<AY>)(<BX>,<BY>)(<CX>,<CY>)|
-\end{decl}
-The |\qbezier| command can be used in |picture| mode to draw a
-quadratic Bezier curve from position |(<AX>,<AY>)| to |(<CX>,<CY>)| with
-control point |(<BX>,<BY>)|. The optional argument \m{N} gives the
-number of points on the curve.
-
-For example, the diagram:
-\begin{center}
- \begin{picture}(50,50)
- \thicklines
- \qbezier(0,0)(0,50)(50,50)
- \qbezier[20](0,0)(50,0)(50,50)
- \thinlines
- \put(0,0){\line(1,1){50}}
- \end{picture}
-\end{center}
-is drawn with:
-\begin{verbatim}
- \begin{picture}(50,50)
- \thicklines
- \qbezier(0,0)(0,50)(50,50)
- \qbezier[20](0,0)(50,0)(50,50)
- \thinlines
- \put(0,0){\line(1,1){50}}
- \end{picture}
-\end{verbatim}
-The |\bezier| command is the same, except that the argument \m{N} is not
-optional. It is provided for compatibility with the \LaTeX~2.09
-|bezier| document style option.
-
-\subsection{Old commands}
-
-\begin{decl}
-|\samepage|
+ |\fpeval| \arg{floating point expression}
\end{decl}
-The |\samepage| command still exists but is no longer being
-maintained.
-This is because it only ever worked erratically; it does not
-guarantee that there will be no page-breaks within its scope; and
-it can cause footnotes and marginals to be wrongly placed.
+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.
-We recommend using |\enlargethispage| in conjunction with page-break
-commands such as |\newpage| and |\pagebreak| to help control page
-breaks.
-\begin{decl}
- |\SLiTeX|
-\end{decl}
-Since \SLiTeX{} no longer exists, the logo is no longer defined in the
-\LaTeX{} kernel. A suitable replacement is |\textsc{Sli\TeX}|. The
-\SLiTeX{} logo is defined in \LaTeX~2.09 compatibility mode.
-
-\begin{decl}
-|\mho| |\Join| |\Box| |\Diamond| |\leadsto| \\
-|\sqsubset| |\sqsupset| |\lhd| |\unlhd| |\rhd| |\unrhd|
-\end{decl}
-
-These symbols are contained in the \LaTeX{} symbol font, which was
-automatically loaded by \LaTeX~2.09. However, \TeX{} has room for
-only sixteen math font families; thus many users discovered that they
-ran out. Because of this, \LaTeX{} does not load the \LaTeX{} symbol
-font unless you use the \textsf{latexsym} package.
-
-These symbols are also made available, using different fonts, by the
-\textsf{amsfonts} package, which also defines a large number of other
-symbols. It is supplied by the American Mathematical Society.
-
-The \textsf{latexsym} package is loaded automatically in \LaTeX~2.09
-compatibility mode.
-
-\section{\LaTeX~2.09 documents}
-\label{Sec:209}
-
-\LaTeXe{} can process (almost) any \LaTeX~2.09 document, by entering
-\emph{\LaTeX~2.09 compatibility mode}. Nothing has changed, you run
-\LaTeX{} in the same way you always did, and you will get much the
-same results.
-
-The reason for the `almost' is that some \LaTeX~2.09 packages made use
-of low-level unsupported features of \LaTeX. If you discover such a
-package, you should find out if it has been updated to work with
-\LaTeXe. Most packages will still work with \LaTeXe---the easiest way
-to find out whether a package still works is to try it!
-
-\LaTeX~2.09 compatibility mode is a comprehensive emulation of
-\LaTeX~2.09, but at the cost of time. Documents can run up to 50\%
-slower in compatibility mode than they did under \LaTeX~2.09.
-In addition, many of the new features of \LaTeXe{} are not available in
-\LaTeX~2.09 compatibility mode.
-
-\subsection{Warning}
-
-\NEWdescription{1995/12/01}
-This \emph{\LaTeX~2.09 compatibility mode} is provided solely to allow
-you to process 2.09 documents, i.e.~documents that were written (we
-hope, a long time ago) for a very old system and therefore could be
-processed by using a genuine antique \LaTeX~2.09 system.
-
-This mode is therefore \emph{not} intended to provide access to the
-enhanced features of \LaTeXe{}. Thus it must not be used to process
-new documents which masquerade as 2.09 documents (i.e.~they begin with
-|\documentstyle|) but which could not be processed using that genuine
-antique \LaTeX~2.09 system because they contain some new,
-\LaTeXe{}-only, commands or environments.
-
-To prevent such misuse of the system, and the consequent trouble it
-causes when such misleadingly encoded documents are distributed, the
-\emph{\LaTeX~2.09 compatibility mode} turns off most of these new
-features and commands. Any attempt to use them will give you an error
-message and, moreover, many of them simply will not work, whilst
-others will produce unpredictable results.
-So don't bother sending us any bug reports about such occurrences since
-they are intentional.
-
-
-\subsection{Font selection problems}
-\label{Sec:fsprob}
-
-When using compatibility mode, it is possible that you will find
-problems with font-changing commands in some old documents. These
-problems are of two types:
+Briefly, the floating point expressions may comprise:
\begin{itemize}
-\item producing error messages;
-\item not producing the font changes you expected.
+ \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}
-In case of error messages it is possible that the document (or an old
-style file used therein) contains references to old internal commands
-which are no longer defined, see Section~\ref{Sec:oldinternals} for
-more information if this is the case.
-
-\NEWdescription{1995/12/01}
-One example of the unexpected is if you use one of the new style of
-math-mode font changing command as follows:
-\begin{verbatim}
-$ \mathbf{xy} A $
-\end{verbatim}
-You may well find that this behaves as if you had put:
-\begin{verbatim}
-$ \bf {xy} A $
-\end{verbatim}
-everything including the $A$ coming out bold.
-
-\LaTeX~2.09 allowed sites to customize their \LaTeX{} installation,
-which resulted in documents producing different results on different
-\LaTeX{} installations. \LaTeXe{} no longer allows so much
-customization but, for compatibility with old documents, the local
-configuration file |latex209.cfg| is loaded every time \LaTeXe{}
-enters \LaTeX~2.09 compatibility mode.
-
-For example, if your site was customized to use the New Font
-Selection Scheme (\NFSS) with the |oldlfont| option, then you can
-make \LaTeXe{} emulate this by creating a |latex209.cfg| file
-containing the commands:
-\begin{verbatim}
-\ExecuteOptions{oldlfont}\RequirePackage{oldlfont}
-\end{verbatim}
-Similarly, to emulate \NFSS{} with the |newlfont| option, you can
-create a |latex209.cfg| file containing:
+An example of use could be the following:
\begin{verbatim}
-\ExecuteOptions{newlfont}\RequirePackage{newlfont}
+\LaTeX{} can now compute: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3}
+ = \fpeval{sin(3.5)/2 + 2e-3} $.
\end{verbatim}
-
-
-\subsection{Native mode}
-\label{Sec:native}
-
-To run an old document faster, and use the new features of
-\LaTeXe, you should try using \emph{\LaTeXe{} native mode}.
-This is done by replacing the command:
-\begin{quote}
- |\documentstyle[|\m{options}|,|\m{packages}|]|\arg{class}
-\end{quote}
-with:
+which produces the following output:
\begin{quote}
- |\documentclass|\oarg{options}\arg{class} \\
- |\usepackage{latexsym,|\m{packages}|}|
+ \LaTeX{} can now compute: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3}
+ = \fpeval{sin(3.5)/2 + 2e-3} $.
\end{quote}
-However, some documents which can be processed in \LaTeX~2.09
-compatibility mode may not work in native mode. Some \LaTeX~2.09
-packages will only work with \LaTeXe{} in 2.09 compatibility mode.
-Some documents will cause errors because of \LaTeXe's improved error
-detection abilities.
-
-But most \LaTeX~2.09 documents can be processed by \LaTeXe{}'s native
-mode with the above change. Again, the easiest way to find out
-whether your documents can be processed in native mode is to try it!
-
-
-\section{Local modifications}
-\label{sec:loc}
-
-\NEWdescription{1995/12/01}
-There are two common types of local modifications that can be done
-very simply. Do not forget that documents produced using such
-modifications will not be usable at other places (such documents are
-called `non-portable').
-
-One type of modification is the use of personal commands for commonly
-used symbols or constructions. These should be put into a package
-file (for example, one called \texttt{mymacros.sty}) and loaded by
-putting |\usepackage{mymacros}| in the document preamble.
-
-Another type is a local document class that is very similar to one of
-the standard classes but contains some straightforward modifications
-such as extra environments, different values for some parameters, etc.
-These should be put into a class file; here we shall describe a simple
-method of constructing such a file using, as an example, a class
-called \textsf{larticle} that is very similar to the \textsf{article}
-class.
-
-\NEWfeature{1995/12/01}
-The class file called \texttt{larticle.cls} should (after the
-preliminary identification commands) start as follows:
-\begin{verbatim}
- \LoadClassWithOptions{article}
-\end{verbatim}
-This command should be followed by whatever additions and changes you
-wish to make to the results of reading in the file
-\texttt{article.sty}.
-
-The effect of using the above |\LoadClassWithOptions| command is to
-load the standard class file \textsf{article} with whatever options
-are asked for by the document. Thus a document using your
-\textsf{larticle} class can specify any option that could be specified
-when using the standard \textsf{article} class; for example:
-\begin{verbatim}
- \documentclass[a4paper,twocolumn,dvips]{larticle}
-\end{verbatim}
-
-
-\section{Problems}
-\label{Sec:problems}
-
-This section describes some of the things which may go wrong when
-using \LaTeXe, and what you can do about it.
-
-\subsection{New error messages}
-
-\LaTeXe{} has a number of new error messages.
-Please also note that many error messages now produce further helpful
-information if you press |h| in response to the error prompt.
\begin{decl}
-|Option clash for package |\m{package}|.|
+ |\inteval| \arg{integer expression}
\end{decl}
-The named package has been loaded twice with different options. If
-you enter |h| you will be told what the options were, for example, if
-your document contained:
-\begin{verbatim}
- \usepackage[foo]{fred}
- \usepackage[baz]{fred}
-\end{verbatim}
-then you will get the error message:
-\begin{verbatim}
- Option clash for package fred.
-\end{verbatim}
-and typing |h| at the |?| prompt will give you:
-\begin{verbatim}
- The package fred has already been loaded with options:
- [foo]
- There has now been an attempt to load it with options:
- [baz]
- Adding the line:
- \usepackage[foo,baz]{fred}
- to your document may fix this.
- Try typing <<return>> to proceed.
-\end{verbatim}
-The cure is, as suggested, to load the package with both sets of
-options. Note that since \LaTeX{} packages can call other packages,
-it is possible to get a package option clash without explicitly
-requesting the same package twice.
-\begin{decl}
- |Command |\m{command}| not provided in base NFSS.|
-\end{decl}
-The \m{command} is not provided by default in \LaTeXe. This error is
-generated by using one of the commands:
+ 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}
- \mho \Join \Box \Diamond \leadsto
- \sqsubset \sqsupset \lhd \unlhd \rhd \unrhd
+\LaTeX{} can now compute: The sum of the numbers is $\inteval{1 + 2 + 3}$.
\end{verbatim}
-which are now part of the \textsf{latexsym} package.
-The cure is to add:
-\begin{verbatim}
- \usepackage{latexsym}
-\end{verbatim}
-in the preamble of your document.
-
-\begin{decl}
- |LaTeX2e command <command> in LaTeX 2.09 document.|
-\end{decl}
-The \m{command} is a \LaTeXe{} command but this is a \LaTeX~2.09
-document. The cure is to replace the command by a \LaTeX~2.09
-command, or to run document in native mode, as described in
-Section~\ref{Sec:native}.
-
-\begin{decl}
- |NFSS release 1 command \newmathalphabet found.|
-\end{decl}
-The command |\newmathalphabet| was used by the New Font Selection
-Scheme Release 1 but it has now been replaced by
-|\DeclareMathAlphabet|, the use of which is described in
-\emph{\fntguide}.
-
-The best cure is to update the package which contained the
-|\newmathalphabet| command. Find out if there is a new release of
-the package, or (if you wrote the package yourself) consult
-\emph{\fntguide} for the new syntax of font commands.
-
-If there is no updated version of the package then you can cure this
-error by using the \textsf{newlfont} or \textsf{oldlfont} package,
-which tells \LaTeX{} which version of |\newmathalphabet| should be
-emulated.
-
-You should use \textsf{oldlfont} if the document selects math fonts with
-syntax such as this:
-\begin{quote}
- |{\cal A}|, etc.
-\end{quote}
-Use \textsf{newlfont} if the document's syntax is like this:
-\begin{quote}
- |\cal{A}|, etc.
-\end{quote}
-
-
-\begin{decl}
- |Text for \verb command ended by end of line.|
-\end{decl}
-The |\verb| command has been begun but not ended on that line. This
-usually means that you have forgotten to put in the end-character of
-the |\verb| command.
+which results in
+\enquote{\LaTeX{} can now compute: The sum of the numbers is $\inteval{1 + 2 + 3}$.}
-\begin{decl}
- |Illegal use of \verb command.|
-\end{decl}
-The |\verb| command has been used inside the argument of another
-command. This has never been allowed in \LaTeX{}---often producing
-incorrect output without any warning---and so \LaTeXe{} produces
-an error message.
-
-\subsection{Old internal commands}
-\label{Sec:oldinternals}
-
-A number of \LaTeX~2.09 internal commands have been removed, since
-their functionality is now provided in a different way. See
-\emph{\clsguide} for more details of the new, supported interface for
-class and package writers.
\begin{decl}
- |\tenrm| |\elvrm| |\twlrm| \dots\\
- |\tenbf| |\elvbf| |\twlbf| \dots\\
- |\tensf| |\elvsf| |\twlsf| \dots\\
- $\vdots$
+ |\dimeval| \arg{dimen expression} \qquad
+ |\skipeval| \arg{skip expression}
\end{decl}
-These commands provided access to the seventy fonts preloaded by
-\LaTeX~2.09. In contrast, \LaTeXe{} normally preloads at most
-fourteen fonts, which saves a lot of font memory; but a consequence is
-that any \LaTeX{} file which used the above commands to directly
-access fonts will no longer work.
-Their use will usually produce an error message such as:
+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}
- ! Undefined control sequence.
- l.5 \tenrm
+\newcommand\calulateheight[1]{%
+ \setlength\textheight{\dimeval{\topskip+\baselineskip*\inteval{#1-1}}}}
\end{verbatim}
-The cure for this is to update the document to use the new
-font-changing commands provided by \LaTeXe; these are described in
-\emph{\fntguide}.
-
-If this is not possible then, as a last resort, you can
-use the \textsf{rawfonts} package, which loads the
-seventy \LaTeX~2.09 fonts and provides direct access to them using the
-old commands. This takes both time and memory. If you do not
-wish to load all seventy fonts, you can select some of them by using the
-|only| option to \textsf{rawfonts}. For example, to load only |tenrm|
-and |tenbf| you write:
-\begin{verbatim}
- \usepackage[only,tenrm,tenbf]{rawfonts}
-\end{verbatim}
-
-The \textsf{rawfonts} package is distributed as part of the \LaTeX{}
-tools software, see Section~\ref{Sec:st-pack}.
-
-\subsection{Old files}
-
-One of the more common mistakes in running \LaTeX{} is to read in old
-versions of packages instead of the new versions. If you get an
-incomprehensible error message from a standard package, make sure you
-are loading the most recent version of the package. You can find out
-which version of the package has been loaded by looking in the log
-file for a line like:
-\begin{verbatim}
- Package: fred 1994/06/01 v0.01 Fred's package.
-\end{verbatim}
-You can use the \m{release-date} options to |\documentclass| and
-|\usepackage| to make sure that you are getting a suitably recent copy
-of the document class or package. This is useful when sending a
-document to another site, which may have out-of-date software.
-
-\subsection{Where to go for more help}
-
-If you can't find the answer for your problem here, try looking in
-\emph{\LaTeXbook} or \emph{\LaTeXcomp}. If you have a problem with
-installing \LaTeX, look in the installation guide files which come with
-the distribution.
-
-If this doesn't help, contact your local \LaTeX{} guru or local
-\LaTeX{} mailing list.
-
-If you think you've discovered a bug then please report it! First,
-you should find out if the problem is with a third-party package or
-class. If the problem is caused by a package or class other than
-those listed in Section~\ref{Sec:class+packages} then please report
-the problem to the author of the package or class, not to the \LaTeX3
-project team.
-
-If the bug really is with core \LaTeX{} then you should create a
-\emph{short}, \emph{self-contained} document which exhibits the
-problem. You should run a \emph{recent} (less than a year old)
-version of \LaTeX{} on the file and then run \LaTeX{} on
-|latexbug.tex|. This will create an error report which you should
-send, together with the sample document and log file, to the
-\LaTeX{} bugs address which can be found in the file
-|latexbug.tex| or |bugs.txt|.
-
-
-\section{Enjoy!}
-\label{Sec:enjoy}
-
-We certainly hope you will enjoy using the new standard \LaTeX{} but,
-if this is not possible, we hope that you will enjoy success and
-fulfillment as a result of the documents which it will help you to
-create.
-
-If you find that the contribution of \LaTeX{} to your life is such
-that you would like to support the work of the project team, then
-please read Section~\ref{Sec:ltx3} and discover practical ways to do
-this.
-
-\begin{thebibliography}{1}
-
-\bibitem{A-W:GRM97}
-Michel Goossens, Sebastian Rahtz and Frank Mittelbach.
-\newblock {\em The {\LaTeX} Graphics Companion}.
-\newblock Addison-Wesley, Reading, Massachusetts, 1997.
-
-
-\bibitem{A-W:GR99}
-Michel Goossens and Sebastian Rahtz.
-\newblock {\em The {\LaTeX} Web Companion}.
-\newblock Addison-Wesley, Reading, Massachusetts, 1999.
-
-
-\bibitem{A-W:DEK91}
-Donald~E. Knuth.
-\newblock {\em The \TeX book}.
-\newblock Addison-Wesley, Reading, Massachusetts, 1986.
-\newblock Revised to cover \TeX3, 1991.
-
-
-\bibitem{A-W:LLa94}
-Leslie Lamport.
-\newblock {\em {\LaTeX:} A Document Preparation System}.
-\newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994.
-
-\bibitem{A-W:MG2004}
-Frank Mittelbach and Michel Goossens.
-\newblock {\em The {\LaTeX} Companion second edition}.
-\newblock With Johannes Braams, David Carlisle, and Chris Rowley.
-\newblock Addison-Wesley, Reading, Massachusetts, 2004.
-
-
-\end{thebibliography}
+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}