summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/expl3.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-10-11 03:02:59 +0000
committerNorbert Preining <norbert@preining.info>2023-10-11 03:02:59 +0000
commit366cf31a771ded1f10860be3212058d48020398d (patch)
tree99ee483a9fd05dfd4ec908582abb44028bdffbd1 /macros/latex/contrib/l3kernel/expl3.dtx
parent48eedda2cb4d2644886b862409b24a1d8e9a136f (diff)
CTAN sync 202310110302
Diffstat (limited to 'macros/latex/contrib/l3kernel/expl3.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/expl3.dtx74
1 files changed, 36 insertions, 38 deletions
diff --git a/macros/latex/contrib/l3kernel/expl3.dtx b/macros/latex/contrib/l3kernel/expl3.dtx
index 9adee097c5..ea13fbeacf 100644
--- a/macros/latex/contrib/l3kernel/expl3.dtx
+++ b/macros/latex/contrib/l3kernel/expl3.dtx
@@ -24,7 +24,7 @@
%
%<*driver|generic|package|2ekernel>
%</driver|generic|package|2ekernel>
-\def\ExplFileDate{2023-08-29}%
+\def\ExplFileDate{2023-10-10}%
%<*driver>
\documentclass[full]{l3doc}
\usepackage{graphicx}
@@ -51,7 +51,7 @@
% }^^A
% }
%
-% \date{Released 2023-08-29}
+% \date{Released 2023-10-10}
%
% \maketitle
%
@@ -311,8 +311,9 @@
% or private.
%
% To allow clear separation of these two cases, the following convention
-% is used. Private functions should be defined with |__| added to the beginning
-% of the module name. Thus
+% is used. In private functions and variables, two |_| characters are
+% added to the start of the module name. On the other hand, public
+% interfaces to not have these two |_| character. Thus
% \begin{verbatim}
% \module_foo:nnn
% \end{verbatim}
@@ -323,8 +324,9 @@
% is private to the module, and should \emph{not} be used outside of that
% module.
%
-% Similarly, private variables should use |__| to separate scope and
-% module name, such that
+% For variables, to avoid three |_| in a row, the separator for the variable
+% scope and any leading |_| for a private interface in the module part are
+% combined. Thus
% \begin{verbatim}
% \l_module_foo_tl
% \end{verbatim}
@@ -334,12 +336,12 @@
% \end{verbatim}
% is private.
%
-% \subsubsection{Using \texttt{@@} and \pkg{l3docstrip} to mark private code}
+% \subsubsection{Using \texttt{@@} and \pkg{DocStrip} to mark private code}
%
% The formal syntax for internal functions allows clear separation of public
% and private code, but includes redundant information (every internal function
% or variable includes \texttt{__\meta{module}}). To aid programmers, the
-% \pkg{l3docstrip} program introduces the syntax
+% \pkg{DocStrip} program introduces the syntax
% \begin{quote}
% \ttfamily
% |%<@@=|\meta{module}|>|
@@ -354,7 +356,7 @@
% \tl_new:N \l_@@_my_tl
% % \end{macrocode}
% \end{verbatim}
-% is converted by \pkg{l3docstrip} to
+% is converted by \pkg{DocStrip} to
% \begin{verbatim}
% \cs_new:Npn \__foo_function:n #1
% ...
@@ -365,13 +367,6 @@
% distinguish variables from functions in the source when the |@@|
% convention is used.
%
-% Please note that you have to use the \pkg{l3docstrip} and
-% \textbf{not} the \pkg{docstrip} program in your \texttt{.ins} files
-% to make this work---the original \LaTeXe{} \pkg{docstrip} doesn't
-% understand the \texttt{@@} and will just copy it into your code
-% unmodified!
-%
-%
% \subsubsection{Variables: declaration}
%
% In well-formed \pkg{expl3} code, variables should always be declared before
@@ -653,20 +648,10 @@
% variables which have a \cs{\meta{var}_use:N} function (other than
% boxes), and which therefore deliver a single
% \enquote{value}.
-% \item[x] Fully-expanded token or braced token list.\\
-% This means that the argument is expanded as in the replacement
-% text of an~\tn{edef}, and the expansion is passed to the function as
-% a braced token list. Expansion takes place until only unexpandable
-% tokens are left. |x|-type arguments cannot be nested.
% \item[e] Fully-expanded token or braced token list.\\
-% This expansion is very similar to |x|-type but may be nested and does
-% not require that |#| tokens are doubled. It uses \tn{expanded} primitive.
-% \item[f] Expanding the first token recursively in a braced token
-% list.\\ Almost the same as the |x| type except here the token list
-% is expanded fully until the first unexpandable token is found and
-% the rest is left unchanged. Note that if this function finds a
-% space at the beginning of the argument it gobbles it and does not
-% expand the next token.
+% This means that the argument is expanded as in the replacement
+% text of a~\tn{message}, and the expansion is passed to the function as
+% a braced token list.
% \item[o] One-level-expanded token or braced token list.\\
% This means that the argument is expanded one level, as by
% \tn{expandafter}, and the expansion is passed to the function as a
@@ -674,6 +659,19 @@
% token list then only the first token in that list is expanded.
% In general, using \texttt{V} should be preferred to using
% \texttt{o} for simple variable retrieval.
+% \item[f] Expanding the first token recursively in a braced token
+% list.\\ Almost the same as the |e| type except here the token list
+% is expanded fully until the first unexpandable token is found and
+% the rest is left unchanged. Note that if this function finds a
+% space at the beginning of the argument it gobbles it and does not
+% expand the next token.
+% \item[x] Fully-expanded token or braced token list.\\
+% This expansion is very similar to |e|-type but is not nestable,
+% can only be used to create non-expandable functions, and requires
+% that |#| tokens are doubled in the argument. In almost all cases,
+% |e|-type should be preferred: retained largely for historical
+% reasons, and should where possible be replaced by the |e|-type
+% equivalent.
% \end{description}
%
% \subsection{Simpler means better}
@@ -761,17 +759,17 @@
%
% To illustrate this let us suppose you have a \enquote{base function}
% |\demo_cmd:Nnn| that takes three normal arguments, and that you need
-% to construct the variant |\demo_cmd:cnx|, for which the first argument
+% to construct the variant |\demo_cmd:cne|, for which the first argument
% is used to construct the \emph{name} of a command, whilst the third
% argument must be fully expanded before being passed to
% |\demo_cmd:Nnn|.
% To produce the variant form from the base form, simply use this:
% \begin{verbatim}
-% \cs_generate_variant:Nn \demo_cmd:Nnn { cnx }
+% \cs_generate_variant:Nn \demo_cmd:Nnn { cne }
% \end{verbatim}
% This defines the variant form so that you can then write, for example:
% \begin{verbatim}
-% \demo_cmd:cnx { abc } { pq } { \rst \xyz }
+% \demo_cmd:cne { abc } { pq } { \rst \xyz }
% \end{verbatim}
% rather than \ldots\ well, something like this!
% \begin{verbatim}
@@ -793,13 +791,13 @@
% \end{verbatim}
%
% Another example: you may wish to declare a function
-% |\demo_cmd_b:xcxcx|, a variant of an existing function
+% |\demo_cmd_b:enene|, a variant of an existing function
% |\demo_cmd_b:nnnnn|, that fully
% expands arguments 1,~3 and~5, and produces commands to pass as
% arguments 2 and~4 using~\tn{csname}.
% The definition you need is simply
% \begin{verbatim}
-% \cs_generate_variant:Nn \demo_cmd_b:nnnnn { xcxcx }
+% \cs_generate_variant:Nn \demo_cmd_b:nnnnn { enene }
% \end{verbatim}
%
% This extension mechanism is written so that if the same new form of
@@ -854,7 +852,7 @@
% \begin{itemize}
% \item \pkg{expl3} is mainly focused on programming. This means that
% some areas still require the use of \LaTeXe{} internal macros.
-% For example, you may well need \tn{@ifpackageloaded}, as there
+% For example, you may well need \tn{IfPackageLoadedTF}, as there
% is currently no native \pkg{expl3} package loading module.
% \item User level macros should be generated using the mechanism
% available in the \pkg{xparse} package, which is part of the
@@ -1541,12 +1539,12 @@
}
\cs_gset_protected:Npn \@expl@push@filename@@@@
{
- \exp_args:Nx \__kernel_file_input_push:n
+ \exp_args:Ne \__kernel_file_input_push:n
{
\tl_to_str:N \@currname .
\tl_to_str:N \@currext
}
- \tl_put_left:Nx \l_@@_status_stack_tl
+ \tl_put_left:Ne \l_@@_status_stack_tl
{
\bool_if:NTF \l__kernel_expl_bool
{ 1 }
@@ -1742,7 +1740,7 @@
\cs_set_protected:Npn \ProvidesExplFileAux ##1##2##3##4
{
\group_end:
- \iow_log:x { File:~##1~##2~v##3~##4 }
+ \iow_log:e { File:~##1~##2~v##3~##4 }
}
\tex_input:D #1 .def \scan_stop:
}