diff options
Diffstat (limited to 'macros/latex-dev/base/usrguide.tex')
-rw-r--r-- | macros/latex-dev/base/usrguide.tex | 2570 |
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} |