[latex3-commits] [git/LaTeX3-latex3-latex3] master: Clearer wording on :D specifier (8a19cc0b2)
PhelypeOleinik
phelype.oleinik at latex-project.org
Tue Oct 27 18:04:34 CET 2020
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
More information about the latex3-commits
mailing list.