diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex | 34 |
1 files changed, 31 insertions, 3 deletions
diff --git a/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex index 59ab7c95a99..b166c61d82a 100644 --- a/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex +++ b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex @@ -1,13 +1,13 @@ \iffalse meta-comment -File l3styleguide.tex Copyright (C) 2011,2012,2015-2017 The LaTeX3 Project +File l3styleguide.tex Copyright (C) 2011,2012,2014-2017 The LaTeX3 Project It may be distributed and/or modified under the conditions of the LaTeX Project Public License (LPPL), either version 1.3c of this license or (at your option) any later version. The latest version of this license is in the file - http://www.latex-project.org/lppl.txt + https://www.latex-project.org/lppl.txt This file is part of the "l3kernel bundle" (The Work in LPPL) and all files in that bundle must be distributed together. @@ -30,7 +30,7 @@ The released version of this bundle is available from CTAN. {latex-team@latex-project.org}% }% } -\date{Released 2017/11/14} +\date{Released 2017/12/05} \begin{document} @@ -271,4 +271,32 @@ scheme is \texttt{auxi}, \texttt{auxii} and so on. The use of \texttt{aux_i}, \texttt{aux_ii}, \emph{etc.}\ is discouraged as this conflicts with the convention used by \cs{use_i:nn} and related functions. +\section{Functions with `weird' arguments} + +When defining commands that do not follow the usual convention of accepting +arguments as single-tokens or braced-text, the \verb|w| argument specifier +is used to denote that the function signature cannot fully describe the syntax. +Two examples from the \LaTeX3 kernel are: +\begin{quote} +\verb|\use_none_delimit_by_q_stop:w| $\langle$\,\emph{text}\,$\rangle$ \verb|\q_stop|\\ +\verb|\use_i_delimit_by_q_stop:nw| \char`\{ $\langle$\,\emph{arg}\,$\rangle$\char`}\,$\langle$\,\emph{text}\,$\rangle$ \verb|\q_stop| +\end{quote} +More complex definitions are possible if commands are to parse tokens, +such as the internal kernel command +\begin{verbatim} + \cs_new_protected:Npn \__clist_get:wN #1 , #2 \q_stop #3 + { \tl_set:Nn #3 {#1} } +\end{verbatim} +When the \verb|w| specifier is being used, it is encouraged not to try +and complicate the rest of the signature too much---for example, it +would be considered poor style to have a function with a signature like +\verb|\foo_bar:wnw| unless there were very clear reasons of code clarity. +A signature such as \verb|:ww| would certainly be discouraged. + +Examining the examples above, it can be seen that there are scenarios in +which it may make logical sense for having a signature such as \verb|:wN| or +\verb|:nw|, but when in doubt the recommended approach is to simply use +\verb|:w| as a catch-all. + \end{document} + |