[latex3-commits] [l3svn] r6937 - Use \NewDocumentCommand (instead of Declare) in code examples
noreply at latex-project.org
noreply at latex-project.org
Thu Feb 16 21:05:10 CET 2017
Author: bruno
Date: 2017-02-16 21:05:09 +0100 (Thu, 16 Feb 2017)
New Revision: 6937
Modified:
trunk/l3packages/xparse/xparse.dtx
Log:
Use \NewDocumentCommand (instead of Declare) in code examples
Modified: trunk/l3packages/xparse/xparse.dtx
===================================================================
--- trunk/l3packages/xparse/xparse.dtx 2017-02-16 19:56:16 UTC (rev 6936)
+++ trunk/l3packages/xparse/xparse.dtx 2017-02-16 20:05:09 UTC (rev 6937)
@@ -91,18 +91,18 @@
% At present, the functions in \pkg{xparse} which are regarded as
% \enquote{stable} are:
% \begin{itemize}
-% \item \cs{DeclareDocumentCommand}
% \item \cs{NewDocumentCommand}
% \item \cs{RenewDocumentCommand}
% \item \cs{ProvideDocumentCommand}
-% \item \cs{DeclareDocumentEnvironment}
+% \item \cs{DeclareDocumentCommand}
% \item \cs{NewDocumentEnvironment}
% \item \cs{RenewDocumentEnvironment}
% \item \cs{ProvideDocumentEnvironment}
-% \item \cs{DeclareExpandableDocumentCommand}
+% \item \cs{DeclareDocumentEnvironment}
% \item \cs{NewExpandableDocumentCommand}
% \item \cs{RenewExpandableDocumentCommand}
% \item \cs{ProvideExpandableDocumentCommand}
+% \item \cs{DeclareExpandableDocumentCommand}
% \item \cs{IfNoValue(TF)}
% \item \cs{IfBoolean(TF)}
% \end{itemize}
@@ -218,7 +218,7 @@
% defined such that they require matched pairs of delimiters when collecting
% an argument. For example
% \begin{verbatim}
-% \DeclareDocumentCommand{\foo}{o}{#1}
+% \NewDocumentCommand{\foo}{o}{#1}
% \foo[[content]] % #1 = "[content]"
% \foo[[] % Error: missing closing "]"
% \end{verbatim}
@@ -229,15 +229,15 @@
% Within delimited arguments, non-balanced or otherwise awkward tokens may
% be included by protecting the entire argument with a brace pair
% \begin{verbatim}
-% \DeclareDocumentCommand{\foo}{o}{#1}
-% \foo[{[}] % Allowed as the "[" is 'hidden'
+% \NewDocumentCommand{\foobar}{o}{#1}
+% \foobar[{[}] % Allowed as the "[" is 'hidden'
% \end{verbatim}
% These braces will be stripped if they surround the \emph{entire} content
% of the optional argument
% \begin{verbatim}
-% \DeclareDocumentCommand{\foo}{o}{#1}
-% \foo[{abc}] % => "abc"
-% \foo[ {abc}] % => " {abc}"
+% \NewDocumentCommand{\foobaz}{o}{#1}
+% \foobaz[{abc}] % => "abc"
+% \foobaz[ {abc}] % => " {abc}"
% \end{verbatim}
%
% Two more tokens have a special meaning when creating an argument
@@ -271,17 +271,17 @@
% to the last mandatory argument to be collected (as it must exist).
% So after
% \begin{verbatim}
-% \DeclareDocumentCommand \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. However, spaces are \emph{not} ignored when parsing optional
% arguments after the last mandatory argument. Thus with
% \begin{verbatim}
-% \DeclareDocumentCommand \foo { m o } { ... }
+% \NewDocumentCommand \foobar { m o } { ... }
% \end{verbatim}
-% |\foo{arg1}[arg2]| will find an optional argument but
-% \verb*|\foo{arg1} [arg2]| will not. This is so that trailing optional
+% |\foobar{arg1}[arg2]| will find an optional argument but
+% \verb*|\foobar{arg1} [arg2]| will not. This is so that trailing optional
% arguments are not picked up \enquote{by accident} in input.
%
% There is one major exception to the rules listed above: when
@@ -296,8 +296,8 @@
% delimited} (\texttt{R}-type) argument is that an error will be raised if
% the latter is missing. Thus for example
% \begin{verbatim}
-% \DeclareDocumentCommand {\foo} {r()m} {}
-% \foo{oops}
+% \NewDocumentCommand {\foobaz} {r()m} {}
+% \foobaz{oops}
% \end{verbatim}
% will lead to an error message being issued. The marker |-NoValue-|
% (\texttt{r}-type) or user-specified default (for \texttt{R}-type) will be
@@ -336,7 +336,7 @@
% default value can be expressed in terms of the value of any other
% arguments by using |#1|, |#2|, and so on.
% \begin{verbatim}
-% \DeclareDocumentCommand {\conjugate} { m O{#1ed} O{#2} } {(#1,#2,#3)}
+% \NewDocumentCommand {\conjugate} { m O{#1ed} O{#2} } {(#1,#2,#3)}
% \conjugate {walk} % => (walk,walked,walked)
% \conjugate {find} [found] % => (find,found,found)
% \conjugate {do} [did] [done] % => (do,did,done)
@@ -345,7 +345,7 @@
% argument specification. For instance a command could accept two
% optional arguments, equal by default:
% \begin{verbatim}
-% \DeclareDocumentCommand {\margins} { O{#3} m O{#1} m } {(#1,#2,#3,#4)}
+% \NewDocumentCommand {\margins} { O{#3} m O{#1} m } {(#1,#2,#3,#4)}
% \margins {a} {b} % => {(-NoValue-,a,-NoValue-,b)}
% \margins [1cm] {a} {b} % => {(1cm,a,1cm,b)}
% \margins {a} [1cm] {b} % => {(1cm,a,1cm,b)}
@@ -388,13 +388,13 @@
%
% \begin{function}
% {
-% \DeclareDocumentCommand ,
% \NewDocumentCommand ,
% \RenewDocumentCommand ,
-% \ProvideDocumentCommand
+% \ProvideDocumentCommand ,
+% \DeclareDocumentCommand
% }
% \begin{syntax}
-% \cs{DeclareDocumentCommand} \meta{Function} \Arg{arg spec} \Arg{code}
+% \cs{NewDocumentCommand} \meta{Function} \Arg{arg spec} \Arg{code}
% \end{syntax}
% This family of commands are used to create a document-level
% \meta{function}. The argument specification for the function is
@@ -404,7 +404,7 @@
%
% As an example:
% \begin{verbatim}
-% \DeclareDocumentCommand \chapter { s o m }
+% \NewDocumentCommand \chapter { s o m }
% {
% \IfBooleanTF {#1}
% { \typesetstarchapter {#3} }
@@ -417,43 +417,44 @@
% The \cs{typesetnormalchapter} could test its first argument for being
% |-NoValue-| to see if an optional argument was present.
%
-% The difference between the \cs{Declare\ldots}, \cs{New\ldots}
-% \cs{Renew\ldots} and \cs{Provide\ldots} versions is the behaviour
+% The difference between the \cs{New\ldots} \cs{Renew\ldots},
+% \cs{Provide\ldots} and \cs{Declare\ldots} versions is the behaviour
% if \meta{function} is already defined.
% \begin{itemize}
-% \item \cs{DeclareDocumentCommand} will always create the new
-% definition, irrespective of any existing \meta{function} with the
-% same name.
% \item \cs{NewDocumentCommand} will issue an error if \meta{function}
% has already been defined.
% \item \cs{RenewDocumentCommand} will issue an error if \meta{function}
% 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{function} with the
+% same name. This should be used sparingly.
% \end{itemize}
%
% \begin{texnote}
% Unlike \LaTeXe{}'s \cs{newcommand} and relatives, the
-% \cs{DeclareDocumentCommand} family of functions do not prevent creation of
+% \cs{NewDocumentCommand} family of functions do not prevent creation of
% functions with names starting \cs{end\ldots}.
% \end{texnote}
%
% \begin{function}
% {
-% \DeclareDocumentEnvironment ,
% \NewDocumentEnvironment ,
% \RenewDocumentEnvironment ,
-% \ProvideDocumentEnvironment
+% \ProvideDocumentEnvironment ,
+% \DeclareDocumentEnvironment
% }
% \begin{syntax}
-% \cs{DeclareDocumentEnvironment} \Arg{environment} \Arg{arg spec}
+% \cs{NewDocumentEnvironment} \Arg{environment} \Arg{arg spec}
% ~~\Arg{start code} \Arg{end code}
% \end{syntax}
-% These commands work in the same way as \cs{DeclareDocumentCommand},
-% etc., but create environments (\cs{begin}|{|\meta{function}|}| \ldots
-% \cs{end}|{|\meta{function}|}|). Both the \meta{start code} and
+% These commands work in the same way as \cs{NewDocumentCommand},
+% etc.\@, but create environments (\cs{begin}\Arg{environment} \ldots{}
+% \cs{end}\Arg{environment}). Both the \meta{start code} and
% \meta{end code}
% may access the arguments as defined by \meta{arg spec}.
+% The arguments will be given following \cs{begin}\Arg{environment}.
% \end{function}
%
% \subsection{Testing special values}
@@ -471,7 +472,7 @@
% 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}
-% \DeclareDocumentCommand \foo { o m }
+% \NewDocumentCommand \foo { o m }
% {
% \IfNoValueTF {#1}
% { \DoSomethingJustWithMandatoryArgument {#2} }
@@ -529,7 +530,7 @@
% Used to test if \meta{argument} (|#1|, |#2|, \emph{etc.}) is
% \cs{BooleanTrue} or \cs{BooleanFalse}. For example
% \begin{verbatim}
-% \DeclareDocumentCommand \foo { s m }
+% \NewDocumentCommand \foo { s m }
% {
% \IfBooleanTF #1
% { \DoSomethingWithStar {#2} }
@@ -577,7 +578,7 @@
% This processor reverses the logic of \cs{BooleanTrue} and
% \cs{BooleanFalse}, so that the example from earlier would become
% \begin{verbatim}
-% \DeclareDocumentCommand \foo { > { \ReverseBoolean } s m }
+% \NewDocumentCommand \foo { > { \ReverseBoolean } s m }
% {
% \IfBooleanTF #1
% { \DoSomethingWithoutStar {#2} }
@@ -600,7 +601,7 @@
% then \cs{NoValue} markers are added at the end of the processed
% argument.
% \begin{verbatim}
-% \DeclareDocumentCommand \foo
+% \NewDocumentCommand \foo
% { > { \SplitArgument { 2 } { ; } } m }
% { \InternalFunctionOfThreeArguments #1 }
% \end{verbatim}
@@ -618,7 +619,7 @@
% then wrapped in braces within |#1|. The result is that the
% processed argument can be further processed using a mapping function.
% \begin{verbatim}
-% \DeclareDocumentCommand \foo
+% \NewDocumentCommand \foo
% { > { \SplitList { ; } } m }
% { \MappingFunction #1 }
% \end{verbatim}
@@ -635,7 +636,7 @@
% 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}
-% \DeclareDocumentCommand \foo
+% \NewDocumentCommand \foo
% { > { \SplitList { ; } } m }
% { \ProcessList {#1} { \SomeDocumentFunction } }
% \end{verbatim}
@@ -651,7 +652,7 @@
% and category code~$10$) for the ends of the argument. Thus for example
% declaring a function
% \begin{verbatim}
-% \DeclareDocumentCommand \foo
+% \NewDocumentCommand \foo
% { > { \TrimSpaces } m }
% { \showtokens {#1} }
% \end{verbatim}
@@ -680,13 +681,13 @@
%
% \begin{function}
% {
-% \DeclareExpandableDocumentCommand ,
% \NewExpandableDocumentCommand ,
% \RenewExpandableDocumentCommand ,
-% \ProvideExpandableDocumentCommand
+% \ProvideExpandableDocumentCommand ,
+% \DeclareExpandableDocumentCommand
% }
% \begin{syntax}
-% \cs{DeclareExpandableDocumentCommand}
+% \cs{NewExpandableDocumentCommand}
% ~~~~\meta{function} \Arg{arg spec} \Arg{code}
% \end{syntax}
% This family of commands is used to create a document-level \meta{function},
@@ -3910,7 +3911,7 @@
%
% \begin{macro}{\@@_check_definable:nNT, \@@_check_definable_aux:nN}
% Check that a token list is appropriate as a first argument of
-% \cs{DeclareDocumentCommand} and similar functions and otherwise
+% \cs{NewDocumentCommand} and similar functions and otherwise
% produce an error. First trim whitespace to allow for spaces around
% the actual command to be defined. If the result has multiple
% tokens, it is not a valid argument. The single token is a control
@@ -4270,20 +4271,15 @@
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\DeclareDocumentCommand}
% \begin{macro}{\NewDocumentCommand}
% \begin{macro}{\RenewDocumentCommand}
% \begin{macro}{\ProvideDocumentCommand}
+% \begin{macro}{\DeclareDocumentCommand}
% The user macros are pretty simple wrappers around the internal ones.
% There is however a check that the first argument is a single token,
% possibly surrounded by spaces (hence the strange \cs{use:nnn}), and
% is definable.
% \begin{macrocode}
-\cs_new_protected:Npn \DeclareDocumentCommand #1#2#3
- {
- \@@_check_definable:nNT {#1} \DeclareDocumentCommand
- { \@@_declare_cmd:Nnn #1 {#2} {#3} }
- }
\cs_new_protected:Npn \NewDocumentCommand #1#2#3
{
\@@_check_definable:nNT {#1} \NewDocumentCommand
@@ -4315,20 +4311,23 @@
\@@_check_definable:nNT {#1} \ProvideDocumentCommand
{ \cs_if_exist:NF #1 { \@@_declare_cmd:Nnn #1 {#2} {#3} } }
}
+\cs_new_protected:Npn \DeclareDocumentCommand #1#2#3
+ {
+ \@@_check_definable:nNT {#1} \DeclareDocumentCommand
+ { \@@_declare_cmd:Nnn #1 {#2} {#3} }
+ }
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\DeclareDocumentEnvironment}
% \begin{macro}{\NewDocumentEnvironment}
% \begin{macro}{\RenewDocumentEnvironment}
% \begin{macro}{\ProvideDocumentEnvironment}
+% \begin{macro}{\DeclareDocumentEnvironment}
% Very similar for environments.
% \begin{macrocode}
-\cs_new_protected:Npn \DeclareDocumentEnvironment #1#2#3#4
- { \@@_declare_env:nnnn {#1} {#2} {#3} {#4} }
\cs_new_protected:Npn \NewDocumentEnvironment #1#2#3#4
{
\cs_if_exist:cTF {#1}
@@ -4343,23 +4342,20 @@
}
\cs_new_protected:Npn \ProvideDocumentEnvironment #1#2#3#4
{ \cs_if_exist:cF {#1} { \@@_declare_env:nnnn {#1} {#2} {#3} {#4} } }
+\cs_new_protected:Npn \DeclareDocumentEnvironment #1#2#3#4
+ { \@@_declare_env:nnnn {#1} {#2} {#3} {#4} }
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
-% \begin{macro}{\DeclareExpandableDocumentCommand}
% \begin{macro}{\NewExpandableDocumentCommand}
% \begin{macro}{\RenewExpandableDocumentCommand}
% \begin{macro}{\ProvideExpandableDocumentCommand}
+% \begin{macro}{\DeclareExpandableDocumentCommand}
% The expandable versions are essentially the same as the basic functions.
% \begin{macrocode}
-\cs_new_protected:Npn \DeclareExpandableDocumentCommand #1#2#3
- {
- \@@_check_definable:nNT {#1} \DeclareExpandableDocumentCommand
- { \@@_declare_expandable_cmd:Nnn #1 {#2} {#3} }
- }
\cs_new_protected:Npn \NewExpandableDocumentCommand #1#2#3
{
\@@_check_definable:nNT {#1} \NewExpandableDocumentCommand
@@ -4394,6 +4390,11 @@
{ \@@_declare_expandable_cmd:Nnn #1 {#2} {#3} }
}
}
+\cs_new_protected:Npn \DeclareExpandableDocumentCommand #1#2#3
+ {
+ \@@_check_definable:nNT {#1} \DeclareExpandableDocumentCommand
+ { \@@_declare_expandable_cmd:Nnn #1 {#2} {#3} }
+ }
% \end{macrocode}
% \end{macro}
% \end{macro}
More information about the latex3-commits
mailing list