[latex3-commits] [l3svn] r7389 - Add a reminder of variants near \cs_generate_variant:Nn

[noreply at latex-project.org]

Author: bruno
Date: 2017-07-17 04:43:07 +0200 (Mon, 17 Jul 2017)
New Revision: 7389

Modified:
   trunk/l3kernel/l3expan.dtx
Log:
Add a reminder of variants near \cs_generate_variant:Nn


Modified: trunk/l3kernel/l3expan.dtx
===================================================================
--- trunk/l3kernel/l3expan.dtx	2017-07-17 02:24:51 UTC (rev 7388)
+++ trunk/l3kernel/l3expan.dtx	2017-07-17 02:43:07 UTC (rev 7389)
@@ -102,10 +102,23 @@
 % \section{Methods for defining variants}
 % \label{sec:l3expan:variants-method}
 %
-% ^^A Bruno: Should we put a table of variant types (N, c, n, V, v, o, f, x) for reference here?
+% We recall the set of available argument specifiers.
+% \begin{itemize}
+% \item |N|~is used for single-token arguments while |c|~constructs a
+%   control sequence from its name and passes it to a parent function as
+%   an |N|-type argument.
+% \item Many argument types extract or expand some tokens and provide it
+%   as an |n|-type argument, namely a braced multiple-token argument:
+%   |V|~extracts the value of a variable, |v|~extracts the value from
+%   the name of a variable, |n|~uses the argument as it is, |o|~expands
+%   once, |f|~expands fully the first token, |x|~expands fully all
+%   tokens at the price of being non-expandable.
+% \item A few odd argument types remain: |T|~and |F|~for conditional
+%   processing, otherwise identical to~|n|, |p|~for the parameter text
+%   in definitions, |w|~for arguments with a specific syntax, and |D|~to
+%   denote primitives that should not be used directly.
+% \end{itemize}
 %
-% ^^A Bruno: Should \cs_generate_variant:Nn \foo:n { c } and \foo:N { o } really be ok?
-%
 % \begin{function}[updated = 2015-08-06]{\cs_generate_variant:Nn}
 %   \begin{syntax}
 %     \cs{cs_generate_variant:Nn} \meta{parent control sequence} \Arg{variant argument specifiers}
@@ -139,6 +152,11 @@
 %   protected.  The \meta{variant} is created globally, as is any
 %   \cs[no-index]{exp_args:N\meta{variant}} function needed to carry out the
 %   expansion.
+%
+%   While \cs{cs_generate_variant:Nn} |\foo:N { o }| is currently
+%   allowed, one must know that it will break if the result of the
+%   expansion is more than one token or if |\foo:N| requires its
+%   argument not to be braced.
 % \end{function}
 %
 % \section{Introducing the variants}