From 72eb6d17c919509372c3492c50d4b72ac347bc4a Mon Sep 17 00:00:00 2001
From: Bruno Le Floch <bruno@le-floch.fr>
Date: Mon, 27 Nov 2017 17:11:48 -0500
Subject: [PATCH] Document why N to o and n to c are deprecated, say what to do
 (see #418) [ci skip]

---
 l3kernel/l3expan.dtx | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/l3kernel/l3expan.dtx b/l3kernel/l3expan.dtx
index 7216ff472c..c36176e33b 100644
--- a/l3kernel/l3expan.dtx
+++ b/l3kernel/l3expan.dtx
@@ -146,16 +146,25 @@
 %   \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. Only |n|~and
-%   |N| arguments can be changed to other types, and |N|~can only be
-%   changed to~|c| while |n|~can only be changed to |V|, |v|, |o|,
-%   |f|, or~|x|, so that it is unambiguous what the \meta{parent} of
-%   a \meta{variant} is. If the \meta{parent
+%   the \meta{parent control sequence} is already defined. If the \meta{parent
 %   control sequence} is protected or if the \meta{variant} involves
 %   |x|~arguments, 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.
+%
+%   Only |n|~and |N| arguments can be changed to other types, and
+%   |N|~can only be changed to~|c| while |n|~can only be changed to |V|,
+%   |v|, |o|, |f|, or~|x|, so that it is unambiguous what the
+%   \meta{parent} of a \meta{variant} is.  For backwards-compatibility
+%   it is currently possible to make an |o|-type variant of an |N|-type
+%   argument or a |c|-type variant of an |n|-type argument.  Both are
+%   deprecated.  The first because an |o|-type argument may expand to
+%   more than one token.  The second because programmers who use that
+%   most often want to access the value of a variable given its name,
+%   hence should use a |v|-type variant instead of |c|-type.  In those
+%   cases, using the lower-level \cs{exp_args:No} or \cs{exp_args:Nc}
+%   functionns explicitly is preferred to defining confusing variants.
 % \end{function}
 %
 % \section{Introducing the variants}