[latex3-commits] [git/LaTeX3-latex3-latex3] master: Clearer wording on :D specifier (8a19cc0b2)

[PhelypeOleinik]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/8a19cc0b29177fed827df99e36b3eb89a36ee427

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

commit 8a19cc0b29177fed827df99e36b3eb89a36ee427
Author: PhelypeOleinik <phelype.oleinik at latex-project.org>
Date:   Tue Oct 27 14:04:34 2020 -0300

    Clearer wording on :D specifier


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

8a19cc0b29177fed827df99e36b3eb89a36ee427
 l3kernel/doc/source3body.tex | 18 +++++++++++++++---
 l3kernel/expl3.dtx           | 17 ++++++++++++++---
 2 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/l3kernel/doc/source3body.tex b/l3kernel/doc/source3body.tex
index 5586d7379..483054416 100644
--- a/l3kernel/doc/source3body.tex
+++ b/l3kernel/doc/source3body.tex
@@ -192,10 +192,22 @@ following argument specifiers:
     \emph{weird} arguments. This covers everything else, but mainly
     applies to delimited values (where the argument must be terminated
     by some specified string).
-  \item[\texttt{D}] The \texttt{D} specifier means \emph{do not use}.
+  \item[\texttt{D}] The \texttt{D} stands for \textbf{Do not use}.
     All of the \TeX{} primitives are initially \cs{let} to a \texttt{D}
-    name, and some are then given a second name.  Only the kernel
-    team should use anything with a \texttt{D} specifier!
+    name, and some are then given a second name.
+    These functions have no standardized syntax, they are engine
+    dependent and their name can change without warning, thus their
+    use is \emph{strongly discouraged} in package code: programmers
+    should instead use the interfaces documented in
+    \href{interface3.pdf}{interface3.pdf}%^^A
+    \footnote{If a primitive offers a functionality not yet in the
+      kernel, programmers and users are encouraged to write to the
+      \texttt{LaTeX-L} mailing list
+      (\url{mailto:LATEX-L at listserv.uni-heidelberg.de}) describing
+      their use-case and intended behaviour, so that a possible
+      interface can be discussed.  Temporarily, while an interface is
+      not provided, programmers may use the procedure described in the
+      \href{l3styleguide.pdf}{l3styleguide.pdf}.}.
 \end{description}
 Notice that the argument specifier describes how the argument is
 processed prior to being passed to the underlying function. For example,
diff --git a/l3kernel/expl3.dtx b/l3kernel/expl3.dtx
index 59b8cad3a..87b08ab49 100644
--- a/l3kernel/expl3.dtx
+++ b/l3kernel/expl3.dtx
@@ -526,9 +526,20 @@
 % \end{arg-description}
 % There are two other specifiers with more general meanings:
 % \begin{arg-description}
-%   \item[D] This means: \textbf{Do not use}. This special case is used
-%     for \TeX{} primitives.  Programmers outside the kernel team should
-%     not use these functions!
+%   \item[D] Stands for \textbf{Do not use}.  This special case is used
+%     for \TeX{} primitives.  These functions have no standardized
+%     syntax, they are engine dependent and their name can change
+%     without warning, thus their use is \emph{strongly discouraged} in
+%     package code: programmers should instead use the interfaces
+%     documented in \href{interface3.pdf}{interface3.pdf}%^^A
+%     \footnote{If a primitive offers a functionality not yet in the
+%       kernel, programmers and users are encouraged to write to the
+%       \texttt{LaTeX-L} mailing list
+%       (\url{mailto:LATEX-L at listserv.uni-heidelberg.de}) describing
+%       their use-case and intended behaviour, so that a possible
+%       interface can be discussed.  Temporarily, while an interface is
+%       not provided, programmers may use the procedure described in the
+%       \href{l3styleguide.pdf}{l3styleguide.pdf}.}.
 %   \item[w] This means that the argument syntax is \enquote{weird} in that it
 %     does not follow any standard rule.  It is used for functions with
 %     arguments that take non standard forms: examples are \TeX{}-level