diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex-dev/base/usrguide3.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex-dev/base/usrguide3.tex | 314 |
1 files changed, 305 insertions, 9 deletions
diff --git a/Master/texmf-dist/doc/latex-dev/base/usrguide3.tex b/Master/texmf-dist/doc/latex-dev/base/usrguide3.tex index 82c1c068630..249b708943c 100644 --- a/Master/texmf-dist/doc/latex-dev/base/usrguide3.tex +++ b/Master/texmf-dist/doc/latex-dev/base/usrguide3.tex @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2020-2021 +% Copyright (C) 2020-2022 % The LaTeX Project and any individual authors listed elsewhere % in this file. % @@ -31,12 +31,13 @@ \documentclass{ltxguide} \usepackage[T1]{fontenc} % needed for \textbackslash in tt +\usepackage{csquotes} \title{New \LaTeX\ methods for authors (starting 2020)} -\author{\copyright~Copyright 2020-2021, \LaTeX\ Project Team.\\ +\author{\copyright~Copyright 2020-2022, \LaTeX\ Project Team.\\ All rights reserved.} -\date{2021-06-11} +\date{2022-01-03} \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}} \NewDocumentCommand\marg{m}{\arg{#1}} @@ -48,6 +49,18 @@ \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 @@ -227,6 +240,11 @@ defined. 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} \\ @@ -288,7 +306,7 @@ must exist). So after \end{verbatim} the user input |\foo{arg1}[arg2]{arg3}| and \verb*|\foo{arg1} [arg2] {arg3}| will both be parsed in the same way. - + The behavior of optional arguments \emph{after} any mandatory arguments is selectable. The standard settings will allow spaces here, and thus with \begin{verbatim} @@ -554,10 +572,12 @@ spaces are trimmed at both ends of the body: in the example there would otherwise be spaces coming from the ends the lines after |[\itshape]| and |world!|. Putting the prefix |!| before \texttt{b} suppresses space-trimming. -When \texttt{b} is used in the argument specification, the last argument of the environment declaration (e.g., \cs{NewDocumentEnvironment}), which consists of an \meta{end code} to insert at -|\end|\marg{environment}, is redundant since one can simply put that code at -the end of the \meta{start code}. Nevertheless this (empty) \meta{end code} -must be provided. +When \texttt{b} is used in the argument specification, the last +argument of the environment declaration (e.g., +\cs{NewDocumentEnvironment}), which consists of an \meta{end code} to +insert at |\end|\marg{environment}, is redundant since one can simply +put that code at the end of the \meta{start code}. Nevertheless this +(empty) \meta{end code} must be provided. Environments that use this feature can be nested. @@ -665,7 +685,7 @@ with both calls to the command seeing the delimiter |\x|. \subsection{Creating new argument processors} \begin{decl} - |\ProcessedArgument| + |\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 @@ -710,4 +730,280 @@ requested \meta{function} or \meta{environment} at the terminal. If the \meta{function} or \meta{environment} has no known argument specification then an error is issued. + + +\section{Copying and showing (robust) commands} + +If you want to (slightly) alter an existing command you may want to +save the current definition under a new name and then use that in a +new definition. If the existing command is robust, then the old trick of +using the low-level \cs{let} for this doesn't work, because it only +copies the top-level definition, but not the part that actually does +the work. As most \LaTeX{} commands are nowadays robust, \LaTeX{} +now offers some high-level declarations for this instead. + +However, please note that it is usually better to make use of +available hooks (e.g., the generic command or environment hooks), +instead of copying the current definition and thereby freezing it; see +the hook management documentation \texttt{lthooks-doc.pdf} for +details. + +\begin{decl} + |\NewCommandCopy| \arg{cmd} \arg{existing-cmd} \\ + |\RenewCommandCopy| \arg{cmd} \arg{existing-cmd} \\ + |\DeclareCommandCopy| \arg{cmd} \arg{existing-cmd} +\end{decl} + +This copies the definition of \meta{existing-cmd} to \meta{cmd}. After +this \meta{existing-cmd} can be redefined and \meta{cmd} +still works! This allows you to then provide a new definition for +\meta{existing-cmd} that makes use of \meta{cmd} (i.e., of its old +definition). For example, after +\begin{verbatim} + \NewCommandCopy\LaTeXorig\LaTeX + \RenewDocumentCommand\LaTeX{}{\textcolor{blue}{\LaTeXorig}} +\end{verbatim} +all \LaTeX{} logos generated with \cs{LaTeX} will come out in blue +(assuming you have a color package loaded). + +The differences between \cs{New...} and \cs{Renew...} are as +elsewhere: i.e., you get an error depending on whether or not +\meta{cmd} already exists, or in case of \cs{Declare...} it is copied +regardless. Note that there is no \cs{Provide...} declaration, because +that would be of limited value. + + +If the \meta{cmd} or \meta{existing-cmd} can't be provided as a single +token but need \enquote{constructing}, you can use \cs{ExpandArgs} +as explained in +Section~\ref{sec:preconstructing-csnames}. + + + + +\begin{decl} + |\ShowCommand| \arg{cmd} +\end{decl} + +This displays the meaning of the \meta{cmd} on the terminal and then +stops (just like the primitive \cs{show}). The difference is that it +correctly shows the meaning of more complex commands, e.g., in case of +robust commands it displays not only the top-level definition but +also the actual payload code and in case of commands declared with +\cs{NewDocumentCommand}, etc.\ it also gives you detailed information +about the argument signature. + + +\section[Preconstructing command names \\ (or otherwise expanding arguments)] + {Preconstructing command names (or otherwise expanding arguments)} +\label{sec:preconstructing-csnames} + +When declaring new commands with \cs{NewDocumentCommand} or +\cs{NewCommandCopy} or similar, it is sometimes necessary to +``construct'' the csname. As a general mechanism the L3 programming +layer has \cs{exp_args:N...} for this, but there is no mechanism for +it if \cs{ExplSyntaxOn} is not active (and mixing programming and user +interface level commands is not a good approach anyhow). We therefore +offer a mechanism to access this ability using CamelCase naming. + +\begin{decl} + |\UseName| \arg{string} \\ + |\ExpandArgs| \arg{spec} \arg{cmd} \arg{arg1} \dots +\end{decl} + +\cs{UseName} turns the \meta{string} directly into a csname and +then executes it: this is equivalent to the long-standing +\LaTeXe{} internal command \cs{@nameuse}, or the L3 programming +equivalent \cs{use:c}. \cs{ExpandArgs} takes a \meta{spec} which +describes how to expand the \meta{arguments}, carries out these +operations then executes the \meta{cmd}. The \meta{spec} uses +the descriptions offered by the L3 programming layer, and the +relevant \cs{exp_args:N...} function must exist. Common cases will +have a \meta{spec} of \texttt{c}, \texttt{cc} or \texttt{Nc}: see below. + +As an example, the following declaration provides a method to generate +copyedit commands: +\begin{verbatim} +\NewDocumentCommand\newcopyedit{mO{red}} + {\newcounter{todo#1}% + \ExpandArgs{c}\NewDocumentCommand{#1}{s m}% + {\stepcounter{todo#1}% + \IfBooleanTF {##1}% + {\todo[color=#2!10]{\UseName{thetodo#1}: ##2}}% + {\todo[inline,color=#2!10]{\UseName{thetodo#1}: ##2}}% + }% + } +\end{verbatim} +Given that declaration you can then write +\verb/\newcopyedit{note}[blue]/ which defines the command \cs{note} +and the corresponding counter for you. + +A second example is to copy a command by string name using +\cs{NewCommandCopy}: here we might need to construct both command +names. +\begin{verbatim} +\NewDocumentCommand\savebyname{m} + {\ExpandArgs{cc}\NewCommandCopy{saved#1}{#1}} +\end{verbatim} + +In the \meta{spec} each \texttt{c} stands for one argument that is +turned into a `\texttt{c}'ommand. An \texttt{n} represents a +`\texttt{n}'ormal argument that is not altered and \texttt{N} stands for +a `\texttt{N}'ormal argument which is also left unchanged, but one +consisting only of a single token (and usually unbraced). Thus, to +construct a command from a string only for the second argument of +\cs{NewCommandCopy} you would write +\begin{verbatim} +\ExpandArgs{Nc}\NewCommandCopy\mysectionctr{c@section} +\end{verbatim} +There are several other single letters supported in the L3 programming +layer that \emph{could} be used in the \meta{spec} to manipulate +arguments in other ways. If you are interested, take a look at the +\enquote{Argument expansion} section in the L3 programming layer +documentation in \texttt{interface3.pdf}. + + + +\section{Expandable floating point (and other) calculations} + +The \LaTeX3 programming layer which is part of the format offers a +rich interface to manipulate floating point variables and values. To +allow for (simpler) applications to use this on document-level or in +packages otherwise not making use of the L3 programming layer a few +interface commands are made available. + + +\begin{decl} + |\fpeval| \arg{floating point expression} +\end{decl} + +The expandable command \cs{fpeval} takes as its argument a floating +point expression and produces a result using the normal rules of +mathematics. As this command is expandable it can be used where \TeX{} +requires a number and for example within a low-level \cs{edef} operation +to give a purely numerical result. + + + +Briefly, the floating point expressions may comprise: +\begin{itemize} + \item Basic arithmetic: addition $x\fpbin{+}y$, subtraction $x\fpbin{-}y$, + multiplication $x\fpbin{*}y$, division $x\fpbin{/}y$, square root~$\sqrt{x}$, + and parentheses. + \item Comparison operators: $x\fprel{<}y$, + $x\fprel{<=}y$, $x\fprel{>?}y$, + $x\fprel{!=}y$ \emph{etc.} + \item Boolean logic: sign $\fpop{sign} x$, + negation $\fpop{!}x$, conjunction + $x\fprel{\&\&}y$, disjunction $x\fprel{\string|\string|}y$, ternary + operator $x\fprel{?}y\fprel{:}z$. + \item Exponentials: $\fpop{exp} x$, $\fpop{ln} x$, $x\mathord{\texttt{\^{}}}y$. + \item Integer factorial: $\fpop{fact} x$. + \item Trigonometry: $\fpop{sin} x$, $\fpop{cos} x$, $\fpop{tan} x$, $\fpop{cot} x$, $\fpop{sec} + x$, $\fpop{csc} x$ expecting their arguments in radians, and + $\fpop{sind} x$, $\fpop{cosd} x$, + $\fpop{tand} x$, $\fpop{cotd} x$, + $\fpop{secd} x$, $\fpop{cscd} x$ expecting their + arguments in degrees. + \item Inverse trigonometric functions: $\fpop{asin} x$, + $\fpop{acos} x$, $\fpop{atan} x$, + $\fpop{acot} x$, $\fpop{asec} x$, + $\fpop{acsc} x$ giving a result in radians, and + $\fpop{asind} x$, $\fpop{acosd} x$, + $\fpop{atand} x$, $\fpop{acotd} x$, + $\fpop{asecd} x$, $\fpop{acscd} x$ giving a result + in degrees. + \item Extrema: $\fpop{max}(x_{1},x_{2},\ldots)$, $\fpop{min}(x_{1},x_{2},\ldots)$, + $\fpop{abs}(x)$. + \item Rounding functions, controlled by two optional + values, $n$ (number of places, $0$ by default) and + $t$ (behavior on a tie, $\nan$ by default): + \begin{itemize} + \item $\fpop{trunc}(x,n)$ rounds towards zero, + \item $\fpop{floor}(x,n)$ rounds towards~$-\infty$, + \item $\fpop{ceil}(x,n)$ rounds towards~$+\infty$, + \item $\fpop{round}(x,n,t)$ rounds to the closest value, with + ties rounded to an even value by default, towards zero if $t=0$, + towards $+\infty$ if $t>0$ and towards $-\infty$ if $t<0$. + \end{itemize} + \item Random numbers: $\fpop{rand}()$, $\fpop{randint}(m,n)$. + \item Constants: \texttt{pi}, \texttt{deg} (one degree in radians). + \item Dimensions, automatically expressed in points, \emph{e.g.}, + \texttt{pc} is~$12$. + \item Automatic conversion (no need for \cs{number}) of + integer, dimension, and skip variables to floating points numbers, + expressing dimensions in points and ignoring the stretch and + shrink components of skips. + \item Tuples: $(x_1,\ldots{},x_n)$ that can be added together, + multiplied or divided by a floating point number, and nested. +\end{itemize} + +An example of use could be the following: +\begin{verbatim} + \LaTeX{} can now compute: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3} + = \fpeval{sin(3.5)/2 + 2e-3} $. +\end{verbatim} +which produces the following output: +\begin{quote} + \LaTeX{} can now compute: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3} + = \fpeval{sin(3.5)/2 + 2e-3} $. +\end{quote} + +\begin{decl} + |\inteval| \arg{integer expression} +\end{decl} + + The expandable command \cs{inteval} takes as its argument an integer + expression and produces a result using the normal rules of + mathematics with some restrictions, see below. The operations + recognized are |+|, |-|, |*| and |/| plus parentheses. As this + command is expandable it can be used where \TeX{} requires a number + and for example within a low-level \cs{edef} operation to give a + purely numerical result. + + This is basically a thin wrapper for the primitive \cs{numexpr} + command and therefore has some syntax restrictions. These are: + \begin{itemize} + \item \texttt{/} denotes division rounded to the closest integer with + ties rounded away from zero; + \item there is an error and the overall expression evaluates to zero + whenever the absolute value of any intermediate result exceeds + $2^{31}-1$, except in the case of scaling operations + $a$\texttt{*}$b$\texttt{/}$c$, for which $a$\texttt{*}$b$ may be + arbitrarily large; + \item parentheses may not appear after unary \texttt{+} or + \texttt{-}, namely placing \texttt{+(} or \texttt{-(} at the start + of an expression or after \texttt{+}, \texttt{-}, \texttt{*}, + \texttt{/} or~\texttt{(} leads to an error. + \end{itemize} + +An example of use could be the following. +\begin{verbatim} +\LaTeX{} can now compute: The sum of the numbers is $\inteval{1 + 2 + 3}$. +\end{verbatim} +which results in +\enquote{\LaTeX{} can now compute: The sum of the numbers is $\inteval{1 + 2 + 3}$.} + + +\begin{decl} + |\dimeval| \arg{dimen expression} \qquad + |\skipeval| \arg{skip expression} +\end{decl} + +Similar to \cs{inteval} but computing a length (\texttt{dimen}) or a +rubber length (\texttt{skip}) value. Both are thin wrappers around +the corresponding engine primitives, which makes them fast, but +therefore shows the same syntax peculiars as discussed +above. Nevertheless, in practice they are usually sufficient. For +example +\begin{verbatim} +\newcommand\calulateheight[1]{% + \setlength\textheight{\dimeval{\topskip+\baselineskip*\inteval{#1-1}}}} +\end{verbatim} +sets the \cs{textheight} to the appropriate value if a page should +hold a specific number of text lines. Thus after |\calulateheight{40}| +it is set to \dimeval{\topskip+\baselineskip*\inteval{40-1}}, given +the values \cs{topskip} (\dimeval{\topskip}) and \cs{baselineskip} +(\dimeval{\baselineskip}) in the current document. + \end{document} |