diff options
author | Norbert Preining <norbert@preining.info> | 2023-10-11 03:02:59 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-10-11 03:02:59 +0000 |
commit | 366cf31a771ded1f10860be3212058d48020398d (patch) | |
tree | 99ee483a9fd05dfd4ec908582abb44028bdffbd1 /macros/latex/contrib/l3kernel/expl3.dtx | |
parent | 48eedda2cb4d2644886b862409b24a1d8e9a136f (diff) |
CTAN sync 202310110302
Diffstat (limited to 'macros/latex/contrib/l3kernel/expl3.dtx')
-rw-r--r-- | macros/latex/contrib/l3kernel/expl3.dtx | 74 |
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: } |