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 | 58 |
1 files changed, 53 insertions, 5 deletions
diff --git a/Master/texmf-dist/doc/latex-dev/base/usrguide3.tex b/Master/texmf-dist/doc/latex-dev/base/usrguide3.tex index 249b708943c..efec9ad2a2c 100644 --- a/Master/texmf-dist/doc/latex-dev/base/usrguide3.tex +++ b/Master/texmf-dist/doc/latex-dev/base/usrguide3.tex @@ -37,7 +37,7 @@ \author{\copyright~Copyright 2020-2022, \LaTeX\ Project Team.\\ All rights reserved.} -\date{2022-01-03} +\date{2022-02-19} \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}} \NewDocumentCommand\marg{m}{\arg{#1}} @@ -356,6 +356,8 @@ defaults with testing for missing values. Optional arguments make use of dedicated variables to return information about the nature of the argument received. + + \begin{decl} |\IfNoValueTF| \arg{arg} \arg{true code} \arg{false code} \\ |\IfNoValueT| \arg{arg} \arg{true code} \\ @@ -391,11 +393,12 @@ 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. Rather than testing separately for emptiness and for +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 simply test for emptiness using the -\pkg{expl3} conditional \cs{tl_if_blank:nTF} or its \pkg{etoolbox} -analogue \cs{ifblank}. +empty default value, and then test for emptiness using the +conditional \cs{IfBlankTF} (described below) instead. \begin{decl} |\IfValueTF| \arg{arg} \arg{true code} \arg{false code} \\ @@ -406,6 +409,51 @@ 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. + + + + +\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 \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} + +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. + + + + \begin{decl} |\BooleanFalse| \\ |\BooleanTrue| |