[latex3-commits] [git/LaTeX3-latex3-latex2e] develop, usrguide: Standardise verbatim formatting in usrguide3 (fixes #898) (1a542f70)
Joseph Wright
joseph.wright at morningstar2.co.uk
Sat Jul 23 14:23:37 CEST 2022
Repository : https://github.com/latex3/latex2e
On branches: develop,usrguide
Link : https://github.com/latex3/latex2e/commit/1a542f70b05461b60622d013c328a8e87d4bd351
>---------------------------------------------------------------
commit 1a542f70b05461b60622d013c328a8e87d4bd351
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date: Sat Jul 23 13:23:37 2022 +0100
Standardise verbatim formatting in usrguide3 (fixes #898)
>---------------------------------------------------------------
1a542f70b05461b60622d013c328a8e87d4bd351
base/doc/usrguide3.tex | 154 ++++++++++++++++++++++++-------------------------
1 file changed, 77 insertions(+), 77 deletions(-)
diff --git a/base/doc/usrguide3.tex b/base/doc/usrguide3.tex
index a148c77e..afca516c 100644
--- a/base/doc/usrguide3.tex
+++ b/base/doc/usrguide3.tex
@@ -211,12 +211,12 @@ by the parser.
An example:
\begin{verbatim}
- \NewDocumentCommand\chapter{s o m}
- {%
- \IfBooleanTF{#1}%
- {\typesetstarchapter{#3}}%
- {\typesetnormalchapter{#2}{#3}}%
- }
+\NewDocumentCommand\chapter{s o m}
+ {%
+ \IfBooleanTF{#1}%
+ {\typesetstarchapter{#3}}%
+ {\typesetnormalchapter{#2}{#3}}%
+ }
\end{verbatim}
would be a way to define a \cs{chapter} command which would essentially behave
like the current \LaTeXe{} command (except that it would accept an optional
@@ -288,7 +288,7 @@ be omitted by the user, thus becoming in effect mandatory. This can apply to
The default for \texttt{O}, \texttt{D} and \texttt{E} arguments can be
the result of grabbing another argument. Thus for example
\begin{verbatim}
- \NewDocumentCommand\foo{O{#2} m}
+\NewDocumentCommand\foo{O{#2} m}
\end{verbatim}
would use the mandatory argument as the default for the leading optional
one.
@@ -302,7 +302,7 @@ intervening spaces. This is true for both mandatory and optional arguments. So
collecting arguments up to the last mandatory argument to be collected (as it
must exist). So after
\begin{verbatim}
- \NewDocumentCommand\foo{m o m}{ ... }
+\NewDocumentCommand\foo{m o m}{ ... }
\end{verbatim}
the user input |\foo{arg1}[arg2]{arg3}| and \verb*|\foo{arg1} [arg2] {arg3}|
will both be parsed in the same way.
@@ -310,13 +310,13 @@ will both be parsed in the same way.
The behavior of optional arguments \emph{after} any mandatory arguments is
selectable. The standard settings will allow spaces here, and thus with
\begin{verbatim}
- \NewDocumentCommand\foobar{m o}{ ... }
+\NewDocumentCommand\foobar{m o}{ ... }
\end{verbatim}
both |\foobar{arg1}[arg2]| and \verb*|\foobar{arg1} [arg2]| will find an
optional argument. This can be changed by giving the modified |!| in the
argument specification:
\begin{verbatim}
- \NewDocumentCommand\foobar{m !o}{ ... }
+\NewDocumentCommand\foobar{m !o}{ ... }
\end{verbatim}
where \verb*|\foobar{arg1} [arg2]| will not find an optional argument.
@@ -328,7 +328,7 @@ and thus it is possible to require an optional argument directly follow such a
command. The most common example is the use of \texttt{\textbackslash\textbackslash}
in \pkg{amsmath} environments, which in the terms here would be defined as
\begin{verbatim}
- \NewDocumentCommand\\{!s !o}{ ... }
+\NewDocumentCommand\\{!s !o}{ ... }
\end{verbatim}
\subsection{`Embellishments'}
@@ -337,13 +337,13 @@ in \pkg{amsmath} environments, which in the terms here would be defined as
The \texttt{E}-type argument allows one default value per test token. This is
achieved by giving a list of defaults for each entry in the list, for example:
\begin{verbatim}
- E{^_}{{UP}{DOWN}}
+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}}
+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
@@ -366,12 +366,12 @@ the nature of the argument received.
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}}%
- }
+\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.
@@ -387,7 +387,7 @@ 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-}
+\IfNoValueTF{-NoValue-}
\end{verbatim}
will be logically \texttt{false}.
When two optional arguments follow each other (a syntax we typically
@@ -428,10 +428,14 @@ 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!}
+ \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
@@ -470,12 +474,12 @@ names which are accessible outside of code blocks.
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}}%
- }
+\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.
@@ -494,7 +498,7 @@ Each argument processor is specified by the syntax \texttt{>}\marg{processor}
in the argument specification. Processors are applied from right to left, so
that
\begin{verbatim}
- >{\ProcessorB} >{\ProcessorA} m
+>{\ProcessorB} >{\ProcessorA} m
\end{verbatim}
would apply \cs{ProcessorA} followed by \cs{ProcessorB} to the tokens grabbed
by the \texttt{m} argument.
@@ -512,8 +516,8 @@ If there are fewer than \arg{number} of \arg{tokens} in the argument
then |-NoValue-| markers are added at the end of the processed
argument.
\begin{verbatim}
- \NewDocumentCommand \foo {>{\SplitArgument{2}{;}} m}
- {\InternalFunctionOfThreeArguments#1}
+\NewDocumentCommand \foo {>{\SplitArgument{2}{;}} m}
+ {\InternalFunctionOfThreeArguments#1}
\end{verbatim}
If only a single character \meta{token} is used for the split, any
category code $13$ (active) character matching the \meta{token} will
@@ -527,7 +531,7 @@ Therefore, when an argument processor is applied to an \texttt{E}-type
argument, all the arguments pass through that processor before being fed
to the \meta{code}. For example, this command
\begin{verbatim}
- \NewDocumentCommand \foo { >{\TrimSpaces} e{_^} }
+\NewDocumentCommand \foo { >{\TrimSpaces} e{_^} }
{ [#1](#2) }
\end{verbatim}
applies \cs{TrimSpaces} to both arguments.
@@ -541,8 +545,8 @@ then wrapped in braces within |#1|. The result is that the
processed argument can be further processed using a mapping function
(see below).
\begin{verbatim}
- \NewDocumentCommand \foo {>{\SplitList{;}} m}
- {\MappingFunction#1}
+\NewDocumentCommand \foo {>{\SplitList{;}} m}
+ {\MappingFunction#1}
\end{verbatim}
If only a single character \meta{token} is used for the split, any
category code $13$ (active) character matching the \meta{token} will
@@ -556,8 +560,8 @@ 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}}
+\NewDocumentCommand \foo {>{\SplitList{;}} m}
+ {\ProcessList{#1}{\SomeDocumentCommand}}
\end{verbatim}
\begin{decl}
@@ -566,12 +570,12 @@ to apply a \meta{function} to every entry in a \meta{list}. The
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}}%
- }
+\NewDocumentCommand\foo{>{\ReverseBoolean} s m}
+ {%
+ \IfBooleanTF#1%
+ {\DoSomethingWithoutStar{#2}}%
+ {\DoSomethingWithStar{#2}}%
+ }
\end{verbatim}
\begin{decl}
@@ -581,8 +585,8 @@ Removes any leading and trailing spaces (tokens with character code~$32$
and category code~$10$) for the ends of the argument. Thus for example
declaring a function
\begin{verbatim}
- \NewDocumentCommand\foo {>{\TrimSpaces} m}
- {\showtokens{#1}}
+\NewDocumentCommand\foo {>{\TrimSpaces} m}
+ {\showtokens{#1}}
\end{verbatim}
and using it in a document as
\begin{flushleft}
@@ -604,13 +608,11 @@ it is sometimes useful to have the body as a standard argument.
This is achieved by ending the argument specification with~\texttt{b}, which is
a dedicated argument type for this situation. For instance
\begin{verbatim}
- \NewDocumentEnvironment{twice} {O{\ttfamily} +b}
- {#2#1#2} {}
-\end{verbatim}
-\begin{verbatim}
- \begin{twice}[\itshape]
- Hello world!
- \end{twice}
+\NewDocumentEnvironment{twice} {O{\ttfamily} +b}
+ {#2#1#2} {}
+\begin{twice}[\itshape]
+ Hello world!
+\end{twice}
\end{verbatim}
typesets `Hello world!{\itshape Hello world!}'.
@@ -688,17 +690,15 @@ cannot change. A command will correctly see an argument delimiter if
the open delimiter has the same character and category codes as at the
time of the definition. For example in:
\begin{verbatim}
- \NewDocumentCommand { \foobar } { D<>{default} } {(#1)}
-\end{verbatim}
-\begin{verbatim}
- \foobar <hello> \par
- \char_set_catcode_letter:N <
- \foobar <hello>
+\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>
+(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.
@@ -717,16 +717,16 @@ 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
+\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)
+(hello)
+(hello)
\end{verbatim}
with both calls to the command seeing the delimiter |\x|.
@@ -742,12 +742,12 @@ 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 } }
- }
+\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
@@ -808,8 +808,8 @@ 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}}
+\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).
@@ -988,7 +988,7 @@ Briefly, the floating point expressions may comprise:
An example of use could be the following:
\begin{verbatim}
- \LaTeX{} can now compute: $ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3}
+\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:
More information about the latex3-commits
mailing list.