[latex3-commits] [latex3/latex3] main: Enhance docs for \cs_generate_variant:Nn (closes #1061) (ae2556dc3)

[github at latex-project.org]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/ae2556dc39871e735920772eb89c0322aa648cfb

>---------------------------------------------------------------

commit ae2556dc39871e735920772eb89c0322aa648cfb
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Mon May 22 17:15:38 2023 +0100

    Enhance docs for \cs_generate_variant:Nn (closes #1061)


>---------------------------------------------------------------

ae2556dc39871e735920772eb89c0322aa648cfb
 l3kernel/l3expan.dtx | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/l3kernel/l3expan.dtx b/l3kernel/l3expan.dtx
index 28ac1c812..d69d17b04 100644
--- a/l3kernel/l3expan.dtx
+++ b/l3kernel/l3expan.dtx
@@ -148,13 +148,17 @@
 %     \cs_generate_variant:Nn \foo:Nn { NV , cV }
 %   \end{verbatim}
 %   generates 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
+%   way. The \cs{cs_generate_variant:Nn} function should only be applied if
+%   the \meta{parent control sequence} is already defined. (This is only
+%   enforced if debugging support is enabled.)
+%   If the \meta{parent
 %   control sequence} is protected or if the \meta{variant} involves any
 %   |x|~argument, then the \meta{variant control sequence} is also
 %   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.
+%   expansion. There is no need to re-apply \cs{cs_generate_variant:Nn} after
+%   changing the definition of the parent function: the variant will always
+%   use the current definition of the parent.
 %
 %   Only |n|~and |N| arguments can be changed to other types.  The only
 %   allowed changes are
@@ -168,6 +172,10 @@
 %   |N|-type parent exist, such as for \cs{tl_count:n} and
 %   \cs{tl_count:N}.
 %
+%   When creating variants for conditional functions,
+%   \cs{prg_generate_conditional_variant:Nnn} provides a convenient way
+%   of handling the related function set.
+%
 %   For backward compatibility it is currently possible to make |n|,
 %   |o|, |V|, |v|, |f|, |e|, or |x|-type variants of an |N|-type argument or
 %   |N| or |c|-type variants of an |n|-type argument.  Both are