[latex3-commits] [l3svn] r6645 - Tweak documentation of variants and of \cs_generate:Nn

[noreply at latex-project.org]

Author: bruno
Date: 2016-08-13 22:23:45 +0200 (Sat, 13 Aug 2016)
New Revision: 6645

Modified:
   trunk/l3kernel/l3expan.dtx
Log:
Tweak documentation of variants and of \cs_generate:Nn

For \cs_generate:Nn I simply documented what is currently
implemented.  No idea if that's the best choice.


Modified: trunk/l3kernel/l3expan.dtx
===================================================================
--- trunk/l3kernel/l3expan.dtx	2016-08-13 20:22:11 UTC (rev 6644)
+++ trunk/l3kernel/l3expan.dtx	2016-08-13 20:23:45 UTC (rev 6645)
@@ -123,6 +123,10 @@
 % \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?
+%
+% ^^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}
@@ -147,19 +151,22 @@
 %   \begin{verbatim}
 %     \cs_generate_variant:Nn \foo:Nn { NV , cV }
 %   \end{verbatim}
-%   would generate the functions |\foo:NV| and |\foo:cV| in the
-%   same way. The \cs{cs_generate_variant:Nn} function can only be
-%   applied if the \meta{parent control sequence} is already defined. If
-%   the \meta{parent control sequence} is protected then the new sequence
-%   will also be protected. The \meta{variant} is created globally, as
-%   is any \cs{exp_args:N\meta{variant}} function needed to carry out
-%  the expansion.
+%   would generate the functions |\foo:NV| and |\foo:cV| in the same
+%   way. The \cs{cs_generate_variant:Nn} function can only be applied if
+%   the \meta{parent control sequence} is already defined. Only |n|~and
+%   |N| arguments can be changed to other types. If the \meta{parent
+%   control sequence} is protected or if the \meta{variant} involves
+%   |x|~arguments, then the \meta{variant control sequence} will also be
+%   protected.  The \meta{variant} is created globally, as is any
+%   \cs{exp_args:N\meta{variant}} function needed to carry out the
+%   expansion.
 % \end{function}
 %
 % \section{Introducing the variants}
 %
 % The available internal functions for argument expansion come in two
-% flavours, some of them are faster then others. Therefore it is usually
+% flavours, some of them are faster then others. Therefore
+% (when speed is important) it is usually
 % best to follow the following guidelines when defining new functions
 % that are supposed to come with variant forms:
 % \begin{itemize}
@@ -184,15 +191,11 @@
 %     not expanded.
 % \end{itemize}
 %
-% ^^A Bruno: We should drop part of that paragraph eventually.
 % The |V| type returns the value of a register, which can be one of
-% |tl|, |num|, |int|, |skip|, |dim|, |toks|, or built-in \TeX{}
+% |tl|, |int|, |skip|, |dim|, |toks|, or built-in \TeX{}
 % registers. The |v| type is the same except it first creates a
 % control sequence out of its argument before returning the
-% value. This recent addition to the argument specifiers may shake
-% things up a bit as most places where |o| is used will be replaced by
-% |V|. The documentation you are currently reading will therefore
-% require a fair bit of re-writing.
+% value.
 %
 % In general, the programmer should not need to be concerned with
 % expansion control. When simply using the content of a variable,
@@ -242,13 +245,13 @@
 % At the same time, \texttt{f}-type expansion stops at the emph{first}
 % non-expandable token. This means for example that both
 % \begin{verbatim}
-%    \tl_set:No \l_tmpa_tl { { \l_tmpa_tl } }
+%    \tl_set:No \l_tmpa_tl { { \g_tmpb_tl } }
 % \end{verbatim}
 % and
 % \begin{verbatim}
-%    \tl_set:Nf \l_tmpa_tl { { \l_tmpa_tl } }
+%    \tl_set:Nf \l_tmpa_tl { { \g_tmpb_tl } }
 % \end{verbatim}
-% leave |\l_tmpa_tl| unchanged: |{| is the first token in the
+% leave |\g_tmpb_tl| unchanged: |{| is the first token in the
 % argument and is non-expandable.
 %
 % \section{Manipulating the first argument}