summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/expl3.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/expl3.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/expl3.dtx1798
1 files changed, 0 insertions, 1798 deletions
diff --git a/macros/latex/contrib/l3kernel/expl3.dtx b/macros/latex/contrib/l3kernel/expl3.dtx
deleted file mode 100644
index 76ef8ec919..0000000000
--- a/macros/latex/contrib/l3kernel/expl3.dtx
+++ /dev/null
@@ -1,1798 +0,0 @@
-% \iffalse meta-comment
-%
-%% File: expl3.dtx
-%
-% Copyright (C) 1990-2024 The LaTeX Project
-%
-% It may be distributed and/or modified under the conditions of the
-% LaTeX Project Public License (LPPL), either version 1.3c of this
-% license or (at your option) any later version. The latest version
-% of this license is in the file
-%
-% https://www.latex-project.org/lppl.txt
-%
-% This file is part of the "l3kernel bundle" (The Work in LPPL)
-% and all files in that bundle must be distributed together.
-%
-% -----------------------------------------------------------------------
-%
-% The development version of the bundle can be found at
-%
-% https://github.com/latex3/latex3
-%
-% for those people who are interested.
-%
-%<*driver|generic|package|2ekernel>
-%</driver|generic|package|2ekernel>
-\def\ExplFileDate{2024-03-14}%
-%<*driver>
-\documentclass[full]{l3doc}
-\usepackage{graphicx}
-\begin{document}
- \DocInput{\jobname.dtx}
-\end{document}
-%</driver>
-% \fi
-%
-% \providecommand\acro[1]{\textsc{\MakeLowercase{#1}}}
-% \newenvironment{arg-description}{%
-% \begin{itemize}\def\makelabel##1{\hss\llap{\bfseries##1}}}{\end{itemize}}
-%
-% \title{^^A
-% The \pkg{expl3} package and \LaTeX3 programming^^A
-% }
-%
-% \author{^^A
-% The \LaTeX{} Project\thanks
-% {^^A
-% E-mail:
-% \href{mailto:latex-team@latex-project.org}
-% {latex-team@latex-project.org}^^A
-% }^^A
-% }
-%
-% \date{Released 2024-03-14}
-%
-% \maketitle
-%
-% \begin{documentation}
-%
-% \begin{abstract}
-%
-% This document gives an introduction to a new set of programming
-% conventions that have been designed to meet the requirements of
-% implementing large scale \TeX{} macro programming projects such as
-% \LaTeX{}. These programming conventions are the base layer of \LaTeX3.
-%
-% The main features of the system described are:
-% \begin{itemize}
-% \item classification of the macros (or, in \LaTeX{} terminology,
-% commands) into \LaTeX{} functions and \LaTeX{} parameters, and also
-% into modules containing related commands;
-% \item a systematic naming scheme based on these classifications;
-% \item a simple mechanism for controlling the expansion of a function's
-% arguments.
-% \end{itemize}
-% This system is being used as the basis for \TeX{} programming within
-% The \LaTeX{} Project. Note that the language is not intended for either
-% document mark-up or style specification. Instead, it is intended that
-% such features will be built on top of the conventions described here.
-%
-% This document is an introduction to the ideas behind the \pkg{expl3}
-% programming interface. For the complete documentation of the programming
-% layer provided by The \LaTeX{} Project, see the accompanying
-% \texttt{interface3} document.
-%
-% \end{abstract}
-%
-% \section{Introduction}
-%
-% The first step to develop a \LaTeX{} kernel beyond \LaTeXe{} is to
-% address how the underlying system is programmed. Rather than the
-% current mix of \LaTeX{} and \TeX{} macros, the \LaTeX3 system provides
-% its own consistent interface to all of the functions needed to
-% control \TeX{}. A key part of this work is to ensure that everything
-% is documented, so that \LaTeX{} programmers and users can work
-% efficiently without needing to be familiar with the internal nature
-% of the kernel or with plain \TeX{}.
-%
-% The \pkg{expl3} bundle provides this new programming interface for
-% \LaTeX{}. To make programming systematic, \LaTeX3 uses some very
-% different conventions to \LaTeXe{} or plain \TeX{}. As a result,
-% programmers starting with \LaTeX3 need to become familiar with
-% the syntax of the new language.
-%
-% The next section shows where this language fits into a complete
-% \TeX{}-based document processing system. We then describe the major
-% features of the syntactic structure of command names, including the
-% argument specification syntax used in function names.
-%
-% The practical ideas behind this argument syntax will be explained,
-% together with the expansion control mechanism and the interface
-% used to define variant forms of functions.
-%
-% As we shall demonstrate, the use of a structured naming scheme and of
-% variant forms for functions greatly improves the readability of the
-% code and hence also its reliability. Moreover, experience has shown
-% that the longer command names which result from the new syntax do not
-% make the process of \emph{writing} code significantly harder.
-%
-% \section{Languages and interfaces}
-%
-% It is possible to identify several distinct languages related to the
-% various interfaces that are needed in a \TeX{}-based document processing
-% system. This section looks at those we consider most important for
-% the \LaTeX3 system.
-%
-% \begin{description}
-% \item[Document mark-up] This comprises those commands (often called
-% tags) that are to embedded in the document (the |.tex| file).
-%
-% It is generally accepted that such mark-up should be essentially
-% \emph{declarative}. It may be traditional \TeX{}-based mark-up such
-% as \LaTeXe{}, as described in~\cite{A-W:LLa94} and~\cite{A-W:GMS94},
-% or a mark-up language defined via \acro{HTML} or \acro{XML}.
-%
-% One problem with more traditional \TeX{} coding conventions (as
-% described in~\cite{A-W:K-TB}) is that the names and syntax of \TeX{}'s
-% primitive formatting commands are ingeniously designed to be
-% \enquote{natural} when used directly by the author as document mark-up
-% or in macros. Ironically, the ubiquity (and widely recognised
-% superiority) of logical mark-up has meant that such explicit
-% formatting commands are almost never needed in documents or in
-% author-defined macros. Thus they are used almost exclusively by
-% \TeX{} programmers to define higher-level commands, and their
-% idiosyncratic syntax is not at all popular with this community.
-% Moreover, many of them have names that could be very useful as
-% document mark-up tags were they not pre-empted as primitives
-% (\emph{e.g.}~\tn{box} or \tn{special}).
-%
-% \item[Designer interface] This relates a (human) typographic
-% designer's specification for a document to a program that
-% \enquote{formats
-% the document}. It should ideally use a declarative language that
-% facilitates expression of the relationship and spacing rules
-% specified for the layout of the various document elements.
-%
-% This language is not embedded in document text and it will be very
-% different in form to the document mark-up language. For \LaTeX{},
-% this level was almost completely missing from \LaTeX{}2.09; \LaTeXe{}
-% made some improvements in this area but it is still the case that
-% implementing a design specification in \LaTeX{} requires far more
-% \enquote{low-level} coding than is acceptable.
-%
-% \item[Programmer interface]
-% This language is the implementation language within which the
-% basic typesetting functionality is implemented, building upon the
-% primitives of \TeX{} (or a successor program). It may also be used
-% to implement the previous two languages \enquote{within} \TeX{}, as in
-% the
-% current \LaTeX{} system.
-%
-% \end{description}
-%
-% The last layer is covered by the conventions described in this
-% document, which describes a system aimed at providing a suitable
-% basis for coding \LaTeX3. Its main distinguishing features are
-% summarised here:
-% \begin{itemize}
-% \item A consistent naming scheme for all commands, including \TeX{}
-% primitives.
-% \item The classification of commands as \LaTeX{} functions or \LaTeX{}
-% parameters, and also their division into modules according to their
-% functionality.
-% \item A simple mechanism for controlling argument expansion.
-% \item Provision of a set of core \LaTeX{} functions that is sufficient
-% for handling programming constructs such as queues, sets, stacks,
-% property lists.
-% \item A \TeX{} programming environment in which, for example, all
-% white space is ignored.
-% \end{itemize}
-%
-% \section{The naming scheme}
-%
-% \LaTeX3 does not use |@| as a \enquote{letter} for defining
-% internal macros. Instead, the symbols |_| and |:|
-% are used in internal macro names to provide structure. In
-% contrast to the plain \TeX{} format and the \LaTeXe{} kernel, these
-% extra letters are used only between parts of a macro name (no
-% strange vowel replacement).
-%
-% While \TeX{} is actually a macro processor, by
-% convention for the \pkg{expl3} programming language we distinguish between
-% \emph{functions} and \emph{variables}. Functions can have arguments and they
-% are either expanded or executed. Variables can be assigned values and they
-% are used in arguments to functions; they are not used directly but are
-% manipulated by functions (including getting and setting functions).
-% Functions and variables with a related functionality (for example accessing
-% counters, or manipulating token lists, \emph{etc.})\ are collected together
-% into a
-% \emph{module}.
-%
-% \subsection{Examples}
-%
-% Before giving the details of the naming scheme, here are a few typical
-% examples to indicate the flavour of the scheme; first some variable
-% names.
-% \begin{quote}
-% \cs{l_tmpa_box} is a local variable (hence the~|l_| prefix)
-% corresponding to a box register.\\
-% \cs{g_tmpa_int} is a global variable (hence the~|g_| prefix)
-% corresponding to an integer register (i.e.~a \TeX{} count
-% register).\\
-% \cs{c_empty_tl} is the constant~(|c_|) token list variable
-% that is always empty.
-% \end{quote}
-%
-% Now here is an example of a typical function name.
-%
-% \cs{seq_push:Nn} is the function which puts the token list specified
-% by its second argument onto the stack specified by its first argument.
-% The different natures of the two arguments are indicated by the~|:Nn|
-% suffix. The first argument must be a single token which \enquote{names}
-% the stack parameter: such single-token arguments are denoted~|N|.
-% The second argument is a normal \TeX{} \enquote{undelimited argument},
-% which
-% may either be a single token or a balanced, brace-delimited token
-% list (which we shall here call a \textit{braced token list}): the~|n|
-% denotes such a \enquote{normal} argument form. The name of the function
-% indicates it belongs to the |seq| module.
-%
-% \subsection{Formal naming syntax}
-%
-% We shall now look in more detail at the syntax of these names. A
-% function name in \LaTeX3 has a name consisting of three parts:
-% \begin{quote}
-% |\|\meta{module}|_|\meta{description}|:|\meta{arg-spec}
-% \end{quote}
-% while a variable has (up to) four distinct parts to its name:
-% \begin{quote}
-% |\|\meta{scope}|_|\meta{module}|_|\meta{description}|_|\meta{type}
-% \end{quote}
-%
-% The syntax of all names contains
-% \begin{quote}
-% \meta{module} and \meta{description}
-% \end{quote}
-% these both give information about the command.
-%
-% A \emph{module} is a collection of closely related functions and
-% variables. Typical module names include~|int| for integer parameters
-% and related functions,~|seq| for sequences and~|box| for boxes.
-%
-% Packages providing new programming functionality will add new modules
-% as needed; the programmer can choose any unused name, consisting
-% of letters only, for a module. In general, the module name and module
-% prefix should be related: for example, the kernel module containing
-% \texttt{box} functions is called \texttt{l3box}. Module names and
-% programmers' contact details are listed in \pkg{l3prefixes.csv}.
-%
-% The \emph{description} gives more detailed information about the
-% function or parameter, and provides a unique name for it. It should
-% consist of letters and, possibly,~|_|~characters. In general, the
-% description should use |_| to divide up \enquote{words} or other easy to
-% follow parts of the name. For example, the \LaTeX3 kernel provides
-% \cs{if_cs_exist:N} which, as might be expected, tests if a command
-% name exists.
-%
-% Where functions for variable manipulation can perform assignments
-% either locally or globally, the latter case is indicated by the inclusion of
-% a |g| in the second part of the function name. Thus \cs{tl_set:Nn} is a local
-% function but \cs{tl_gset:Nn} acts globally. Functions of this type are
-% always documented together, and the scope of action may therefore be
-% inferred from the presence or absence of a |g|. See the next subsection for
-% more detail on variable scope.
-%
-% \subsubsection{Separating private and public material}
-%
-% One of the issues with the \TeX{} language is that it doesn't support
-% name spaces and encapsulation other than by convention. As a result
-% nearly every internal command in the \LaTeXe{} kernel has eventually
-% be used by extension packages as an entry point for modifications or
-% extensions. The consequences of this is that nowadays it is next to
-% impossible to change anything in the \LaTeXe{} kernel (even if it is
-% clearly just an internal command) without breaking something.
-%
-% In \pkg{expl3} we hope to improve this situation drastically by
-% clearly separating public interfaces (that extension packages can use
-% and rely on) and private functions and variables (that should not
-% appear outside of their module). There is (nearly) no way to enforce
-% this without severe computing overhead, so we implement it only
-% through a naming convention, and some support mechanisms. However, we
-% think that this naming convention is easy to understand and to follow,
-% so that we are confident that this will adopted and provides the
-% desired results.
-%
-% Functions created by a module may either be \enquote{public} (documented
-% with a defined interface) or \enquote{private} (to be used only within
-% that module, and thus not formally documented). It is important that
-% only documented interfaces are used; at the same time, it is necessary to
-% show within the name of a function or variable whether it is public
-% or private.
-%
-% To allow clear separation of these two cases, the following convention
-% is used. To denote a private function or a private variable (of the module),
-% two |_| characters are used in front of the module name, e.g.
-% \begin{verbatim}
-% \module_foo:nnn
-% \end{verbatim}
-% is a public function which should be documented while
-% \begin{verbatim}
-% \__module_foo:nnn
-% \end{verbatim}
-% is private to the module, and should \emph{not} be used outside of that
-% module.
-%
-% 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}
-% is a public variable and
-% \begin{verbatim}
-% \l__module_foo_tl
-% \end{verbatim}
-% is private.
-%
-% \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{DocStrip} program introduces the syntax
-% \begin{quote}
-% \ttfamily
-% |%<@@=|\meta{module}|>|
-% \end{quote}
-% which then allows |@@| (and |_@@| in case of variables) to be used as
-% a place holder for \texttt{__\meta{module}} in code. Thus for example
-% \begin{verbatim}
-% %<@@=foo>
-% % \begin{macrocode}
-% \cs_new:Npn \@@_function:n #1
-% ...
-% \tl_new:N \l_@@_my_tl
-% % \end{macrocode}
-% \end{verbatim}
-% is converted by \pkg{DocStrip} to
-% \begin{verbatim}
-% \cs_new:Npn \__foo_function:n #1
-% ...
-% \tl_new:N \l__foo_my_tl
-% \end{verbatim}
-% on extraction. As you can see both |_@@| and |@@| are mapped to
-% \texttt{__\meta{module}}, because we think that this helps to
-% distinguish variables from functions in the source when the |@@|
-% convention is used.
-%
-% \subsubsection{Variables: declaration}
-%
-% In well-formed \pkg{expl3} code, variables should always be declared before
-% assignment is attempted. This is true even for variable types where the
-% underlying \TeX{} implementation will allow direct assignment. This applies
-% both to setting directly (\cs{tl_set:Nn}, etc.) and to setting equal
-% (\cs{tl_set_eq:NN}, etc.).
-%
-% To help programmers to adhere to this approach, the debugging option
-% |check-declarations| may be given
-% \begin{verbatim}
-% \debug_on:n { check-declarations }
-% \end{verbatim}
-% and will issue an error whenever an assignment is made to a non-declared
-% variable. There is a performance implication, so this option should only
-% be used for testing.
-%
-% \subsubsection{Variables: scope and type}
-%
-% The \meta{scope} part of the name describes how the variable can be
-% accessed. Variables are classified as local, global or constant.
-% This \emph{scope} type appears as a code at the beginning of the name;
-% the codes used are:
-% \begin{arg-description}
-% \item[c] constants (global variables whose value should not be
-% changed);
-% \item[g] variables whose value should only be set globally;
-% \item[l] variables whose value should only be set locally.
-% \end{arg-description}
-%
-% Separate functions are provided to assign data to local and global
-% variables; for example, \cs{tl_set:Nn} and \cs{tl_gset:Nn} respectively
-% set the value of a local or global \enquote{token list} variable.
-% Note that it is a poor \TeX{} practice to intermix local and global
-% assignments to a variable; otherwise you risk exhausting the save
-% stack.\footnote{See \emph{The \TeX{}book}, p.\,301, for further
-% information.}
-%
-% The \meta{type} is in the list of available
-% \emph{data-types};\footnote{Of course, if a totally new data type is
-% needed then this will not be the case. However, it is hoped that only
-% the kernel team will need to create new data types.} these include the
-% primitive \TeX{} data-types, such as the various registers, but to
-% these are added data-types built within the \LaTeX{} programming
-% system.
-%
-% The data types in \LaTeX3 are:
-% \begin{description}
-% \item[bitset] a string of bits (\texttt{0} and \texttt{1} tokens) that are
-% accessed by position or by name;
-% \item[bool] either true or false (the \LaTeX3 implementation does
-% not use \tn{iftrue} or \tn{iffalse});
-% \item[box] box register;
-% \item[cctab] category code table;
-% \item[clist] comma separated list;
-% \item[coffin] a \enquote{box with handles} --- a higher-level data
-% type for carrying out |box| alignment operations;
-% \item[dim] \enquote{rigid} lengths;
-% \item[fp] floating-point values;
-% \item[fparray] fixed-size vector of floating-point values;
-% \item[int] integer-valued count register;
-% \item[intarray] fixed-size vector of integer values;
-% \item[ior] an input stream (for reading from a file);
-% \item[iow] an output stream (for writing to a file);
-% \item[muskip] math mode \enquote{rubber} lengths;
-% \item[prop] property list;
-% \item[regex] regular expression;
-% \item[seq] sequence: a data-type used to implement lists (with
-% access at both ends) and stacks;
-% \item[skip] \enquote{rubber} lengths;
-% \item[str] \TeX{} strings: a special case of |tl| in which all
-% characters have category \enquote{other} (catcode~$12$),
-% other than spaces which are category \enquote{space}
-% (catcode~$10$);
-% \item[token] equal to a single arbitrary token;
-% \item[tl] \enquote{token list variables}: placeholders for token lists.
-% \end{description}
-% When the \meta{type} and \meta{module} are identical (as often happens in
-% the more basic modules) the \meta{module} part is often omitted for
-% aesthetic reasons.
-%
-% The name \enquote{token list} may cause confusion, and so some
-% background is useful. \TeX{} works with tokens and lists of tokens,
-% rather than characters. It provides two ways to store these token
-% lists: within macros and as token registers (|toks|). The
-% implementation in \LaTeX3 means that |toks| are not required, and that
-% all operations for storing tokens can use the |tl| variable type.
-%
-% Experienced \TeX{} programmers will notice that some of the variable
-% types listed are native \TeX{} registers whilst others are not. In
-% general, the underlying \TeX{} implementation for a data structure may
-% vary but the \emph{documented interface} will be stable. For example,
-% the |prop| data type was originally implemented as a |toks|, but
-% is currently built on top of the |tl| data structure.
-%
-% \subsubsection{Variables: guidance}
-%
-% Both comma lists and sequences have similar characteristics.
-% They both use special delimiters to mark out one entry from the
-% next, and are both accessible at both ends. In general, it is
-% easier to create comma lists `by hand' as they can be typed
-% in directly. User input often takes the form of a comma separated
-% list and so there are many cases where this is the obvious
-% data type to use. On the other hand, sequences use special internal
-% tokens to separate entries. This means that they can be used to
-% contain material that comma lists cannot (such as items that may
-% themselves contain commas!). In general, comma lists should be
-% preferred for creating fixed lists inside programs and for
-% handling user input where commas will not occur. On the other
-% hand, sequences should be used to store arbitrary lists of
-% data.
-%
-% \pkg{expl3} implements stacks using the sequence data structure.
-% Thus creating stacks involves first creating a sequence, and
-% then using the sequence functions which work in a stack manner
-% (\cs{seq_push:Nn}, \emph{etc}.).
-%
-% Due to the nature of the underlying \TeX{} implementation, it is
-% possible to assign values to token list variables and comma lists
-% without first declaring them. However, this is \emph{not supported
-% behavior}. The \LaTeX3 coding convention is that all variables must
-% be declared before use.
-%
-% The \pkg{expl3} package can be loaded with the \texttt{check-declarations}
-% option to verify that all variables are declared before use. This has
-% a performance implication and is therefore intended for testing during
-% development and not for use in production documents.
-%
-% \subsubsection{Functions: argument specifications}
-%
-% Function names end with an \meta{arg-spec} after a colon. This
-% gives an indication of the types of argument that a function takes,
-% and provides a convenient method of naming similar functions that
-% differ only in their argument forms (see the next section for
-% examples).
-%
-% The \meta{arg-spec} consists of a (possibly empty) list of letters,
-% each denoting one argument of the function. The letter, including
-% its case, conveys information about the type of argument required.
-%
-% All functions have a base form with arguments using one of the
-% following argument specifiers:
-% \begin{arg-description}
-% \item[n] Unexpanded token or braced token list.\\
-% This is a standard \TeX{} undelimited macro argument.
-% \item[N] Single token (unlike~|n|, the argument must \emph{not} be
-% surrounded by braces).\\
-% A typical example of a command taking an~|N|
-% argument is~|\cs_set|, in which the command being defined must be
-% unbraced.
-% \item[p] Primitive \TeX{} parameter specification.\\
-% This can be something simple like~|#1#2#3|, but may use arbitrary
-% delimited argument syntax such as: |#1,#2\q_stop#3|. This is used
-% when defining functions.
-% \item[T,F]
-% These are special cases of~|n| arguments, used for the
-% true and false code in conditional commands.
-% \end{arg-description}
-% There are two other specifiers with more general meanings:
-% \begin{arg-description}
-% \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@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
-% delimited arguments and the boolean tests needed after certain
-% primitive |\if|\ldots{} commands.
-% \end{arg-description}
-%
-% In case of |n| arguments that consist of a single token the
-% surrounding braces can be omitted in nearly all
-% situations---functions that force the use of braces even for single
-% token arguments are explicitly mentioned. However, programmers are
-% encouraged to always use braces around \texttt{n} arguments, as this
-% makes the relationship between function and argument clearer.
-%
-% Further argument specifiers are available as part of the expansion
-% control system. These are discussed in the next section.
-%
-% \section{Expansion control}
-%
-% Let's take a look at some typical operations one might want to
-% perform. Suppose we maintain a stack of open files and we use the
-% stack |\g_ior_file_name_seq| to keep track of them (\texttt{ior} is
-% the prefix used for the file reading module). The basic operation here
-% is to push a name onto this stack which could be done by the operation
-% \begin{quote}
-% \cs{seq_gpush:Nn} |\g_ior_file_name_seq {#1}|
-% \end{quote}
-% where |#1| is the filename. In other words, this operation would
-% push the file name as is onto the stack.
-%
-% However, we might face a situation where the filename is stored in
-% a variable of some sort, say |\l_ior_curr_file_tl|. In this case we
-% want to retrieve the value of the variable. If we simply use
-% \begin{quote}
-% \cs{seq_gpush:Nn} |\g_ior_file_name_seq| |\l_ior_curr_file_tl|
-% \end{quote}
-% we do not get the value of the variable pushed onto the stack,
-% only the variable name itself. Instead a suitable number of
-% \cs{exp_after:wN} would be necessary (together with extra braces) to
-% change the order of expansion,\footnote{\cs{exp_after:wN} is
-% the \LaTeX3 name for the \TeX{} \tn{expandafter} primitive.} \emph{i.e.}
-% \begin{quote}
-% \cs{exp_after:wN} \\
-% | |\cs{seq_gpush:Nn} \\
-% \cs{exp_after:wN} \\
-% | \g_ior_file_name_seq| \\
-% \cs{exp_after:wN} \\
-% | { \l_ior_curr_file_tl }|
-% \end{quote}
-%
-% The above example is probably the simplest case but already shows
-% how the code changes to something difficult to understand.
-% Furthermore there is an assumption in this: that the storage bin
-% reveals its contents after exactly one expansion. Relying on this
-% means that you cannot do proper checking plus you have to know
-% exactly how a storage bin acts in order to get the correct number
-% of expansions. Therefore \LaTeX3 provides the programmer with a
-% general scheme that keeps the code compact and easy to understand.
-%
-% To denote that some argument to a function needs special treatment one
-% just uses different letters in the arg-spec part of the function to
-% mark the desired behavior. In the above example one would write
-% \begin{quote}
-% \cs{seq_gpush:NV} |\g_ior_file_name_seq \l_ior_curr_file_tl|
-% \end{quote}
-% to achieve the desired effect. Here the |V| (the second argument)
-% is for \enquote{retrieve the value of the variable} before passing it to
-% the base function.
-%
-% The following letters can be used to denote special treatment of
-% arguments before passing it to the base function:
-% \begin{description}
-% \item[c] Character string used as a command name.\\ The argument (a
-% token or braced token list) is \emph{fully expanded}; the result
-% must be a sequence of characters which is then used to construct a
-% command name (\emph{via}~\tn{csname} \ldots \tn{endcsname}). This
-% command name is a single token that is passed to the function as
-% the argument. Hence
-% \begin{quote}
-% \cs{seq_gpush:cV} |{ g_file_name_seq }| \cs{l_tmpa_tl}
-% \end{quote}
-% is equivalent to
-% \begin{quote}
-% \cs{seq_gpush:NV} |\g_file_name_seq| \cs{l_tmpa_tl}.
-% \end{quote}
-% Full expansion means that (a) the entire
-% argument must be expandable and (b) any variables are
-% converted to their content. So the preceding examples are also
-% equivalent to
-% \begin{quote}
-% \cs{tl_new:N} |\g_file_seq_name_tl| \\
-% \cs{tl_gset:Nn} |\g_file_seq_name_tl { g_file_name_seq }| \\
-% \cs{seq_gpush:cV} |{| \cs{tl_use:N} |\g_file_seq_name_tl }| \cs{l_tmpa_tl}.
-% \end{quote}
-% (Token list variables are expandable and we could omit the
-% accessor function \cs{tl_use:N}. Other variable types require the
-% appropriate \cs{\meta{var}_use:N} functions to be used in this
-% context.)
-% \item[V] Value of a variable.\\
-% This means that the contents of the register in question is used
-% as the argument, be it an integer, a length-type register, a token
-% list variable or similar. The value is passed to the function as a
-% braced token list. Can be applied to variables which have a
-% \cs{\meta{var}_use:N} function (other than boxes),
-% and which therefore deliver a single \enquote{value}.
-% \item[v] Value of a register, constructed from a character string
-% used as a command name.\\
-% This is a combination of |c| and |V| which first constructs a
-% control sequence from the argument and then passes the value of
-% the resulting register to the function. Can be applied to
-% variables which have a \cs{\meta{var}_use:N} function (other than
-% boxes), and which therefore deliver a single
-% \enquote{value}.
-% \item[e] Fully-expanded token or braced token list.\\
-% 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
-% braced token list. Note that if the original argument is a braced
-% 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}
-%
-% Anyone who programs in \TeX{} is frustratingly familiar with the
-% problem of arranging that arguments to functions are suitably expanded
-% before the function is called. To illustrate how expansion control
-% can bring instant relief to this problem we shall consider two
-% examples copied from \texttt{latex.ltx}.
-%
-% \begin{verbatim}
-% \global\expandafter\let
-% \csname\cf@encoding \string#1\expandafter\endcsname
-% \csname ?\string#1\endcsname
-% \end{verbatim}
-% This first piece of code is in essence simply a global \tn{let} whose
-% two arguments firstly have to be constructed before \tn{let} is
-% executed. The |#1| is a control sequence name such as
-% |\textcurrency|. The token to be defined is obtained by
-% concatenating the characters of the current font encoding stored in
-% |\cf@encoding|, which has to be fully expanded, and the name of the
-% symbol. The second token is the same except it uses the default
-% encoding |?|. The result is a mess of interwoven \tn{expandafter}
-% and \tn{csname} beloved of all \TeX{} programmers, and the code is
-% essentially unreadable.
-%
-% Using the conventions and functionality outlined here, the task would
-% be achieved with code such as this:
-% \begin{verbatim}
-% \cs_gset_eq:cc
-% { \cf@encoding \token_to_str:N #1 } { ? \token_to_str:N #1 }
-% \end{verbatim}
-% The command \cs{cs_gset_eq:cc} is a global~\tn{let} that generates
-% command names out of both of its arguments before making the
-% definition. This produces code that is far more readable and more
-% likely to be correct first time. (\cs{token_to_str:N} is the \LaTeX3
-% name for \tn{string}.)
-%
-% Here is the second example.
-% \begin{verbatim}
-% \expandafter
-% \in@
-% \csname sym#3%
-% \expandafter
-% \endcsname
-% \expandafter
-% {%
-% \group@list}%
-% \end{verbatim}
-% This piece of code is part of the definition of another function. It
-% first produces two things: a token list, by expanding |\group@list| once;
-% and a token whose name comes from~`|sym#3|'. Then the function~\cs{in@}
-% is called and this tests if its first argument occurs in the token list
-% of its second argument.
-%
-% Again we can improve enormously on the code. First we shall rename
-% the function~\cs{in@}, which tests if its first argument appears
-% within its second argument, according to our conventions. Such a
-% function takes two normal \enquote{\texttt{n}} arguments and operates
-% on token lists: it might reasonably be named |\tl_test_in:nn|. Thus
-% the variant function we need would be defined with the appropriate
-% argument types and its name would be |\tl_test_in:cV|. Now this code
-% fragment would be simply:
-% \begin{verbatim}
-% \tl_test_in:cV { sym #3 } \group@list
-% \end{verbatim}
-% This code could be improved further by using a sequence |\l_group_seq|
-% rather than the bare token list |\group@list|. Note that, in addition
-% to the lack of \tn{expandafter}, the space after the~|}| is
-% silently ignored since all white space is ignored in this programming
-% environment.
-%
-% \subsection{New functions from old}
-%
-% For many common functions the \LaTeX3 kernel provides variants
-% with a range of argument forms, and similarly it is expected that
-% extension packages providing new functions will make them available in
-% all the commonly needed forms.
-%
-% However, there will be occasions where it is necessary to construct a
-% new such variant form; therefore the expansion module provides a
-% straightforward mechanism for the creation of functions with any
-% required argument type, starting from a function that takes \enquote{normal}
-% \TeX{} undelimited arguments.
-%
-% 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: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 { cne }
-% \end{verbatim}
-% This defines the variant form so that you can then write, for example:
-% \begin{verbatim}
-% \demo_cmd:cne { abc } { pq } { \rst \xyz }
-% \end{verbatim}
-% rather than \ldots\ well, something like this!
-% \begin{verbatim}
-% \def \tempa {{pq}}%
-% \edef \tempb {\rst \xyz}%
-% \expandafter
-% \demo@cmd:nnn
-% \csname abc%
-% \expandafter
-% \expandafter
-% \expandafter
-% \endcsname
-% \expandafter
-% \tempa
-% \expandafter
-% {%
-% \tempb
-% }%
-% \end{verbatim}
-%
-% Another example: you may wish to declare a 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 { enene }
-% \end{verbatim}
-%
-% This extension mechanism is written so that if the same new form of
-% some existing command is implemented by two extension packages then the
-% two definitions are identical and thus no conflict occurs.
-%
-% \section{The distribution}
-%
-% The \pkg{expl3} modules are designed to be loaded on top of \LaTeXe{}.
-%
-% \begin{bfseries}
-% The core \pkg{expl3} language is broadly stable, and thus
-% the syntax conventions and functions provided
-% are now ready for wider use. There may still be changes to some
-% functions, but these will be minor when compared to the scope of
-% \pkg{expl3}. A robust mechanism is in place for such deprecations.
-% \end{bfseries}
-%
-% The distribution of \pkg{expl3} is split up into three packages on
-% CTAN: \pkg{l3kernel}, \pkg{l3packages} and \pkg{l3experimental}.
-% The core programming layer provided by \pkg{l3kernel} has been loaded
-% as part of the \LaTeX{} since 2020-02-02. For historical reasons, in
-% older kernel releases
-% \begin{verbatim}
-% \RequirePackage{expl3}
-% \end{verbatim}
-% loads the code distributed as \pkg{l3kernel}. This monolithic
-% package contains all of the modules regarded by the team as stable,
-% and any changes in this code are very limited. This material is
-% therefore suitable for use in third-party packages without concern
-% about changes in support. All of this code is documented in
-% \texttt{interface3.pdf}.
-%
-% The material in \pkg{l3packages} is also stable; this bundle provides
-% user-level commands, some of which have been integrated in the
-% \LaTeX{} kernel.
-%
-% Finally, \pkg{l3experimental} contains modules ready for public use
-% but not yet integrated into \pkg{l3kernel}. These modules have to
-% be loaded explicitly. The team anticipate that all of these modules
-% will move to stable status over time, but they may be more flexible
-% in terms of interface and functionality detail. Feedback on these
-% modules is extremely valuable.
-%
-% \section{Moving from \LaTeXe{} to \pkg{expl3}}
-%
-% To help programmers to use \pkg{expl3} code in existing \LaTeXe{} package,
-% some short notes on making the change are probably desirable.
-% Suggestions for inclusion here are welcome! Some of the following
-% is concerned with code, and some with coding style.
-%
-% \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{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{ltcmd} module, which is part of the
-% the \LaTeX{} kernel since 2020-10-01.
-% \item At an internal level, most functions should be generated
-% \tn{long} (using \cs{cs_new:Npn}) rather than \enquote{short} (using
-% \cs{cs_new_nopar:Npn}).
-% \item Where possible, declare all variables and functions (using
-% \cs{cs_new:Npn}, \cs{tl_new:N}, etc.) before use.
-% \item Prefer \enquote{higher-level} functions over \enquote{lower-level},
-% where possible. So for example use \cs{cs_if_exist:NTF} and not
-% \cs{if_cs_exist:N}.
-% \item Use space to make code readable. In general, we recommend
-% a layout such as:
-% \begin{verbatim}
-% \cs_new:Npn \foo_bar:Nn #1#2
-% {
-% \cs_if_exist:NTF #1
-% { \__foo_bar:n {#2} }
-% { \__foo_bar:nn {#2} { literal } }
-% }
-% \end{verbatim}
-% where spaces are used around |{| and |}| except for isolated
-% |#1|, |#2|, \emph{etc.}
-% \item Put different code items on separate lines: readability is
-% much more useful than compactness.
-% \item Use long, descriptive names for functions and variables,
-% and for auxiliary functions use the parent function name plus
-% |aux|, |auxi|, |auxii| and so on.
-% \item If in doubt, ask the team via the LaTeX-L list: someone will
-% soon get back to you!
-% \end{itemize}
-%
-% \section{Load-time options for \pkg{expl3}}
-%
-% To support code authors, the \pkg{expl3} package for \LaTeXe{} includes
-% a small number of load-time options. These all work in a key--value
-% sense, recognising the \texttt{true} and \texttt{false} values. Giving
-% the option name alone is equivalent to using the option with the
-% \texttt{true} value.
-%
-% \DescribeOption{check-declarations}
-% All variables used in \pkg{expl3} code should be declared. This is enforced
-% by \TeX{} for variable types based on \TeX{} registers, but not for those
-% which are constructed using macros as the underlying storage system. The
-% \texttt{check-declarations} option enables checking for all variable
-% assignments, issuing an error if any variables are assigned without being
-% initialised. See also \cs{debug_on:n} \texttt{\{check-declarations\}}
-% in \pkg{interface3} for finer control.
-%
-% \DescribeOption{log-functions}
-% The \texttt{log-functions} option is used to enable recording of every new
-% function name in the \texttt{.log} file. This is useful for debugging
-% purposes, as it means that there is a complete list of all functions
-% created by each module loaded (with the exceptions of a very small number
-% required by the bootstrap code). See also \cs{debug_on:n}
-% \texttt{\{log-functions\}} in \pkg{interface3} for finer control.
-%
-% \DescribeOption{backend}
-% Selects the backend to be used for color, graphics and related operations that
-% are backend-dependent. Options available are
-% \begin{itemize}[font = \texttt]
-% \item[dvips] Use the \texttt{dvips} driver.
-% \item[dvipdfmx] Use the \texttt{dvipdfmx} driver.
-% \item[dvisvgm] Use the \texttt{dvisvgm} driver.
-% \item[luatex] Use the direct PDF output mode of \LuaTeX{}
-% \item[pdftex] Use the direct PDF output mode of \pdfTeX{}
-% \item[xetex] Use the \XeTeX{} version of the \texttt{dvipdfmx} driver.
-% \end{itemize}
-% For historical reasons, there is also \texttt{pdfmode} as an equivalent of
-% \texttt{luatex} or \texttt{pdftex}, and \texttt{xdvipdfmx} as
-% an equivalent to \texttt{xetex}, but these are deprecated
-%
-% \DescribeOption{suppress-backend-headers}
-% The \texttt{suppress-backend-headers} option suppresses loading of
-% backend-specific header files; currently this only affects \texttt{dvips}.
-% This option is available to support DVI-based routes that do not
-% support the |header| line used by \texttt{dvips}.
-%
-% The debugging options may also be given using
-% \verb|\keys_set:nn { sys } { ... }|; the \texttt{backend} option can be
-% given in this way \emph{only} if a backend has not already been loaded.
-% This method of setting options is useful where \pkg{expl3} is pre-loaded
-% by the \LaTeXe{} format.
-%
-% \section{Using \pkg{expl3} with formats other than \LaTeXe{}}
-%
-% As well as the \LaTeXe{} package \pkg{expl3}, there is also a
-% \enquote{generic} loader for the code, \texttt{expl3-generic.tex}.
-% This may be loaded using the plain \TeX{} syntax
-% \begin{verbatim}
-% \input expl3-generic %
-% \end{verbatim}
-% This enables the programming layer to work with the other formats.
-% As no options are available loading in this way, the \enquote{native}
-% drivers are automatically used. If this \enquote{generic} loader is
-% used with \LaTeXe{} the code automatically switches to the appropriate
-% package route.
-%
-% After loading the programming layer using the generic interface, the
-% commands \cs{ExplSyntaxOn} and \cs{ExplSyntaxOff} and the code-level
-% functions and variables detailed in \pkg{interface3} are available.
-% Note that other \LaTeXe{} packages \emph{using} \pkg{expl3} are not
-% loadable: package loading is dependent on the \LaTeXe{} package-management
-% mechanism.
-%
-% \section{Getting the version of \pkg{expl3}}
-%
-% \begin{function}{\ExplLoaderFileDate}
-% Once the programming layer is loaded by one of the loaders, you can access
-% its version in the ISO date format \meta{year}-\meta{month}-\meta{day},
-% through \cs{ExplLoaderFileDate}.
-%
-% The current version of \pkg{expl3} is \ExplLoaderFileDate.
-% \end{function}
-%
-% \section{Engine/primitive requirements}
-%
-% To use \pkg{expl3} and the higher level packages provided by the
-% team, the minimal set of primitive requirements is currently described
-% in \href{README.md}{README.md}.
-%
-% Practically, these requirements are met by the engines
-% \begin{itemize}
-% \item \pdfTeX{} v1.40.20 or later.
-% \item \XeTeX{} v0.999991 or later.
-% \item \LuaTeX{} v1.10 or later.
-% \item e-(u)\pTeX{} v3.8.2 or later.
-% \item Prote (2021) or later.
-% \end{itemize}
-%
-% Additional modules beyond the core of \pkg{expl3} may require additional
-% primitives. In particular, third-party authors may significantly
-% extend the primitive coverage requirements.
-%
-% \section{The \LaTeX{} Project}
-%
-% Development of \LaTeX3 is carried out by The \LaTeX{} Project:
-% \url{https://www.latex-project.org/latex3/}.
-%
-% \begin{thebibliography}{1}
-%
-% \bibitem{A-W:K-TB}
-% Donald E Knuth
-% \newblock \emph{The \TeX{}book}.
-% \newblock Addison-Wesley, Reading, Massachusetts, 1984.
-%
-% \bibitem{A-W:GMS94}
-% Goossens, Mittelbach and Samarin.
-% \newblock \emph{ The \LaTeX{} Companion}.
-% \newblock Addison-Wesley, Reading, Massachusetts, 1994.
-%
-% \bibitem{A-W:LLa94}
-% Leslie Lamport.
-% \newblock \emph{\LaTeX{}: A Document Preparation System}.
-% \newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994.
-%
-% \bibitem{tub:MR97-1}
-% Frank Mittelbach and Chris Rowley.
-% \newblock \enquote{The \LaTeX{} Project}.
-% \newblock \emph{TUGboat},
-% Vol.\,18, No.\,3, pp.\,195--198, 1997.
-%
-% \end{thebibliography}
-%
-% \end{documentation}
-%
-% \begin{implementation}
-%
-% \section{\pkg{expl3} implementation}
-%
-% The implementation here covers several things. There are two
-% \enquote{loaders} to define: the parts of the code that are specific to
-% \LaTeXe{} or to non-\LaTeXe{} formats. These have to cover the same
-% concepts as each other but in rather different ways: as a result, much
-% of the code is given in separate blocks. There is also a short piece of
-% code for the start of the \enquote{payload}: this is to ensure that
-% loading is always done in the right way.
-%
-% \subsection{Loader interlock}
-%
-% A short piece of set up to check that the loader and \enquote{payload}
-% versions match.
-%
-% \begin{macro}{\ExplLoaderFileDate}
-% As DocStrip is used to generate \cs{ExplFileDate}
-% for all files from the same source, it has to match. Thus the loaders
-% simply save this information with a new name.
-% \begin{macrocode}
-%<*loader>
-\let\ExplLoaderFileDate\ExplFileDate
-%</loader>
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\c__kernel_expl_date_tl}
-% The \LaTeXe{} loader stores a private copy of \cs{ExplFileDate},
-% which is fixed when the format is build and cannot be changed later.
-% While \cs{ExplFileDate} ensures that the loader (either
-% \texttt{2ekernel} or \texttt{package}) version matches the version
-% of \file{expl3-code.tex}, this one ensures that the version of an
-% eventual |\usepackage{expl3}| matches the version from the format.
-% It seems to be common to have stray format files in the user tree
-% which trigger errors due to mismatched versions (\emph{e.g.}
-% \url{https://github.com/latex3/latex3/issues/781}).
-%
-% This block also goes to the generic loader, as \pkg{expl3} isn't
-% preloaded there, so the kernel date should be equal to the loader
-% date.
-% \begin{macrocode}
-%<*2ekernel|generic>
-\begingroup
- \catcode`\_=11
- \expandafter
- \ifx\csname c__kernel_expl_date_tl\endcsname\relax
- \global\let\c__kernel_expl_date_tl\ExplFileDate
- \fi
-\endgroup
-%</2ekernel|generic>
-% \end{macrocode}
-% \end{macro}
-%
-% The interlock test itself is simple: \cs{ExplLoaderFileDate} must be
-% defined and identical to \cs{ExplFileDate}. As this has to work for
-% both \LaTeXe{} and other formats, there is some auto-detection involved.
-% (Done this way avoids having two very similar blocks for \LaTeXe{} and
-% other formats.)
-% \begin{macrocode}
-%<*!loader>
-\begingroup
- \def\next{\endgroup}%
- \expandafter\ifx\csname PackageError\endcsname\relax
- \begingroup
- \def\next{\endgroup\endgroup}%
- \def\PackageError#1#2#3%
- {%
- \endgroup
- \errhelp{#3}%
- \errmessage{#1 Error: #2!}%
- }%
- \fi
- \expandafter\ifx\csname ExplLoaderFileDate\endcsname\relax
- \def\next
- {%
- \PackageError{expl3}{No expl3 loader detected}
- {%
- You have attempted to use the expl3 code directly rather than using
- the correct loader. Loading of expl3 will abort.
- }%
- \endgroup
- \endinput
- }
- \else
- \ifx\ExplLoaderFileDate\ExplFileDate
- \else
- \def\next
- {%
- \PackageError{expl3}{Mismatched expl3 files detected}
- {%
- You have attempted to load expl3 with mismatched files:
- probably you have one or more files 'locally installed' which
- are in conflict. Loading of expl3 will abort.
- }%
- \endgroup
- \endinput
- }%
- \fi
-\fi
-\next
-%</!loader>
-% \end{macrocode}
-%
-% A reload test for the payload, just in case.
-% \begin{macrocode}
-%<*!loader>
-\begingroup\expandafter\expandafter\expandafter\endgroup
-\expandafter\ifx\csname ver@expl3-code.tex\endcsname\relax
- \expandafter\edef\csname ver@expl3-code.tex\endcsname
- {%
- \ExplFileDate\space
- L3 programming layer
- }%
-\else
- \expandafter\endinput
-\fi
-%</!loader>
-% \end{macrocode}
-%
-% All good: log the version of the code used (for log completeness). As this
-% is more-or-less \cs{ProvidesPackage} without a separate file and as this also
-% needs to work without \LaTeXe{}, just write the information directly to the
-% log.
-% \begin{macrocode}
-%<*!loader>
-\immediate\write-1 %
- {%
- Package: expl3
- \ExplFileDate\space
- L3 programming layer (code)%
- }%
-%</!loader>
-% \end{macrocode}
-%
-% \subsection{\LaTeXe{} loaders}
-%
-% Loading with \LaTeXe{} may be as part of the format (pre-loading)
-% or as a package. We have to allow for both possible paths, and of
-% course the package being loaded on to of the pre-load. That means
-% the code here must be safe against re-loading.
-%
-% \begin{macrocode}
-%<*package&loader|2ekernel>
-% \end{macrocode}
-%
-% Identify the package or add to the format message.
-% \begin{macrocode}
-%<*2ekernel>
-\ifdefined\LaTeXReleaseInfo
- \LaTeXReleaseInfo\expandafter{\the\LaTeXReleaseInfo
- \show@release@info{L3 programming layer <\ExplFileDate>}%
- }%
-\else
- \everyjob\expandafter{\the\everyjob
- \message{L3 programming layer <\ExplFileDate>}%
- }%
-\fi
-%</2ekernel>
-%<*!2ekernel>
-\ProvidesPackage{expl3}
- [%
- \ExplFileDate\space
- L3 programming layer (loader)
- ]%
-%</!2ekernel>
-% \end{macrocode}
-%
-% \begin{macro}{\ProvidesExplPackage, \ProvidesExplClass, \ProvidesExplFile}
-% For other packages and classes building on this one it is convenient
-% not to need \cs{ExplSyntaxOn} each time. All macros use the same
-% internal one with the proper \LaTeXe{} command.
-% \begin{macrocode}
-\protected\def\ProvidesExplPackage
- {\@expl@provides@file@@Nnnnnn\ProvidesPackage{Package}}
-\protected\def\ProvidesExplClass
- {\@expl@provides@file@@Nnnnnn\ProvidesClass{Document Class}}
-\protected\def\ProvidesExplFile
- {\@expl@provides@file@@Nnnnnn\ProvidesFile{File}}
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\@expl@provides@file@@Nnnnnn}
-% \begin{macro}{\@expl@provides@file@@N}
-% \begin{macro}{\@expl@provides@generic@@wnnw}
-% We need to check the existence of the
-% \cs[no-index]{Provides\meta{thing}}, since we need to load this very
-% early in the \LaTeXe{} kernel. The gymnastics with the version identifier
-% argument allow for the case where it starts with a \texttt{v} and the one
-% where it does not: formally the \texttt{v} is not part of the version,
-% but a lot of people include it.
-% \begin{macrocode}
-\protected\long\def\@expl@provides@file@@Nnnnnn#1#2#3#4#5#6%
- {%
- \ifnum0%
- \ifdefined#11\fi
- \ifx\relax#1\else1\fi
- =11
- \expandafter#1%
- \else
- \@expl@provides@generic@@wnnw{#2}%
- \fi
- {#3}[{#4 \ifx\relax#5\relax\else\@expl@provides@file@@N#5\space\fi #6}]%
- \ExplSyntaxOn
- }
-\long\def\@expl@provides@file@@N#1{v\if#1v\else#1\fi}
-\protected\long\def\@expl@provides@generic@@wnnw#1\fi#2[#3]%
- {%
- \immediate\write-1{#1: #2 #3}%
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% Load the business end: this leaves \cs{expl3} syntax on.
-% The test ensures we only load once without needing to know if
-% there was a preloading step.
-% \begin{macrocode}
-\begingroup\expandafter\expandafter\expandafter\endgroup
-\expandafter\ifx\csname tex\string _let:D\endcsname\relax
- \expandafter\@firstofone
-\else
- \expandafter\@gobble
-\fi
- {\input expl3-code.tex }%
-% \end{macrocode}
-%
-% A check that the bootstrap code did not abort loading: if it did,
-% bail out silently here.
-% \begin{macrocode}
-\begingroup\expandafter\expandafter\expandafter\endgroup
-\expandafter\ifx\csname tex\string _let:D\endcsname\relax
- \expandafter\endinput
-\fi
-% \end{macrocode}
-%
-% \begin{macrocode}
-%<@@=expl>
-% \end{macrocode}
-%
-% At this point, if we have \cs{c__kernel_expl_date_tl} defined, just
-% call the \cs{__kernel_dependency_version_check:Nn} auxiliary to check
-% if it matches \cs{ExplLoaderFileDate}. Here the test is performed
-% only if \cs{c__kernel_expl_date_tl} exists because this file can be
-% loaded in a \LaTeXe{} format without \pkg{expl3} preloaded, where that
-% token list doesn't exist.
-%
-% This is all done in the \texttt{package} \pkg{docstrip} guard because
-% it doesn't apply to \pkg{expl3.ltx}.
-% \begin{macrocode}
-%<*package>
-\ifcsname\detokenize{c__kernel_expl_date_tl}\endcsname
- \expandafter\@firstofone
-\else
-% \end{macrocode}
-% If \cs{c__kernel_expl_date_tl} does \emph{not} exist we may be loading
-% in a format without \pkg{expl3} preloaded or in the earlier (although
-% still compatible) version in which the error mentioned above showed
-% up. If loading as a package, \file{expl3-code.tex} got read and here
-% the \pkg{expl3} syntax is on. Otherwise it was already loaded in a
-% sligtly older kernel, so we fire the incompatibility error message and
-% abort loading.
-% \begin{macrocode}
- \ifodd\csname\detokenize{l__kernel_expl_bool}\endcsname
-% \end{macrocode}
-% In package mode all files are loaded in one go, so versions will
-% match. We just have to set \cs{c__kernel_expl_date_tl} so that
-% further dependencies don't break:
-% \begin{macrocode}
- \global\expandafter\let\csname\detokenize
- {c__kernel_expl_date_tl}\endcsname\ExplLoaderFileDate
- \expandafter\expandafter
- \expandafter\@gobble
- \else
-% \end{macrocode}
-% And reloading in an incompatible version is an error:
-% \begin{macrocode}
- \expandafter\expandafter
- \expandafter\@firstofone
- \fi
-\fi
- {\csname\detokenize{__kernel_dependency_version_check:Nn}\endcsname
- \ExplLoaderFileDate{expl3.sty}}%
-%</package>
-% \end{macrocode}
-%
-% Here we can also detect whether we're reloading. This code goes into
-% \texttt{expl3.ltx} and \texttt{expl3.sty}, the former loaded into the
-% \LaTeXe{} format. When this code is loaded for the first time, the
-% \cs{g_@@_reload_bool} boolean doesn't exist (\cs{else} branch of the
-% \cs{ifcsname} below), so we create it. If the \cs{ifcsname} is true,
-% then we do \cs{ExplSyntaxOn} (because when reloading,
-% \texttt{expl3-code.tex} isn't read again), and set
-% \cs{g_@@_reload_bool} to true.
-% \begin{macrocode}
-\ifcsname\detokenize{g_@@_reload_bool}\endcsname
- \ExplSyntaxOn
- \bool_gset_true:N \g_@@_reload_bool
-\else
- \bool_new:N \g_@@_reload_bool
-\fi
-% \end{macrocode}
-%
-% \begin{variable}{\c_@@_def_ext_tl}
-% Needed by \LaTeXe{}, and avoiding a re-load issue. Variables are
-% best checked explicitly, rather than with \cs{g_@@_reload_bool}
-% because some appear only in one of the code files, so
-% \cs{g_@@_reload_bool} doesn't necessarily mean that the variable
-% is already declared.
-% \begin{macrocode}
-\tl_if_exist:NF \c_@@_def_ext_tl
- { \tl_const:Nn \c_@@_def_ext_tl { def } }
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{macro}
-% {\__kernel_sys_configuration_load:n,\__kernel_sys_configuration_load_std:n}
-% To load configurations, we have the following cases
-% \begin{itemize}
-% \item \pkg{expl3} is pre-loaded: by the time any configuration loads,
-% we have the full file loading stack, and only need the standard
-% version of the code here.
-% \item The package is loaded with pre-loading: we again use the standard
-% version, but we don't test just yet.
-% \item The package is used without pre-loaded code: we need to manually
-% manage \pkg{expl3} syntax.
-% \end{itemize}
-% \begin{macrocode}
-\cs_gset_protected:Npn \__kernel_sys_configuration_load:n #1
-%<*!2ekernel>
- {
- \ExplSyntaxOff
- \cs_undefine:c { ver@ #1 .def }
- \@onefilewithoptions {#1} [ ] [ ]
- \c_@@_def_ext_tl
- \ExplSyntaxOn
- }
-\cs_gset_protected:Npn \__kernel_sys_configuration_load_std:n #1
-%</!2ekernel>
- {
- \cs_undefine:c { ver@ #1 .def }
- \@onefilewithoptions {#1} [ ] [ ]
- \c_@@_def_ext_tl
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{variable}{\l_@@_options_clist}
-% \begin{macrocode}
-%<*!2ekernel>
-\clist_if_exist:NF \l_@@_options_clist
- { \clist_new:N \l_@@_options_clist }
-\DeclareOption*
- { \clist_put_right:NV \l_@@_options_clist \CurrentOption }
-\ProcessOptions \relax
-%</!2ekernel>
-% \end{macrocode}
-% \end{variable}
-%
-% Pretty standard setting creation.
-% \begin{macrocode}
-\keys_define:nn { sys }
- {
- backend .choices:nn =
- { dvipdfmx , dvips , dvisvgm , luatex , pdftex , pdfmode , xdvipdfmx , xetex }
- { \sys_load_backend:n {#1} } ,
- check-declarations .choice: ,
- check-declarations / true .code:n =
- { \debug_on:n { check-declarations } } ,
- check-declarations / false .code:n =
- {
- \__kernel_if_debug:TF
- { \debug_off:n { check-declarations } }
- { }
- } ,
- check-declarations .default:n = true ,
- driver .meta:n = { backend = #1 } ,
- enable-debug .code:n = {} , % A stub
- log-functions .choice: ,
- log-functions / true .code:n =
- { \debug_on:n { log-functions } } ,
- log-functions / false .code:n =
- {
- \__kernel_if_debug:TF
- { \debug_off:n { log-functions } }
- { }
- } ,
- log-functions .default:n = true ,
- suppress-backend-headers .bool_gset_inverse:N
- = \g__kernel_backend_header_bool ,
- suppress-backend-headers .initial:n = false ,
- undo-recent-deprecations .code:n = {} % A stub
- }
-% \end{macrocode}
-%
-% \begin{macro}{\@expl@sys@load@backend@@@@}
-% A backend has to be in place by the start of the document: this has
-% to be before global options are checked for use.
-%
-% The \cs[no-index]{@expl@...@@@@} macros defined in this package are
-% interfaces for \LaTeXe{}. There are currently (this will change
-% with the next release of \LaTeXe{}) two possible cases, at this
-% point of the code: either \cs{@expl@sys@load@backend@@@@} (and the
-% others) already exist because they were defined in
-% \texttt{ltexpl.ltx} (in \texttt{2ekernel} mode) or in
-% \texttt{expl3.ltx} (in \texttt{package} mode).
-%
-% In \texttt{2ekernel} mode, if they exist we are using a future
-% (2020-10-01) release of \LaTeXe{} and we don't need (and can't)
-% patch \LaTeXe's internals because these commands are already there.
-% Though if they don't exist in \texttt{2ekernel} mode, we're using
-% an older version of the kernel, so we \emph{must} patch.
-%
-% In \texttt{package} mode, if these commands exist, then we are using
-% a version of \LaTeXe{} with \pkg{expl3} preloaded (any version)
-% and in any case patching is already done or the macros are in the
-% format itself, so nothing to do.
-% But if in \texttt{package} mode these macros don't exist, we have an
-% even older version of \LaTeXe{} which doesn't even have
-% \pkg{expl3} preloaded, so patching is necessary.
-%
-% All this means that in both \texttt{2ekernel} and \texttt{package}
-% mode we have to check whether \cs{@expl@sys@load@backend@@@@}
-% exists, and patch some \LaTeXe{} internals if it doesn't.
-%
-% In newer \LaTeXe{}, these macros have an empty definition in
-% \texttt{ltexpl.dtx} in case something wrong happens while loading
-% this file (\texttt{expl3.ltx}), so they can safely be used in the
-% \LaTeXe{} kernel.
-%
-% \cs{@expl@sys@load@backend@@@@} is inserted right at the beginning
-% of \cs{document}, but after closing the group started by \cs{begin}.
-% When using \cs{tl_put_left:Nn} to patch the backend loading in
-% \cs{document}, we need to make sure that it happens at group level
-% zero, thus the strange |\endgroup...\begingroup| thing.
-%
-% This chunk of code should only be executed when loading
-% \texttt{expl3.sty} in a \LaTeXe{} without \pkg{expl3} preloaded, so
-% we check if \cs{@expl@sys@load@backend@@@@} exists.
-% \begin{macrocode}
-\cs_if_exist:NF \@expl@sys@load@backend@@@@
- {
- \tl_put_left:Nn \document
- {
- \endgroup
- \@expl@sys@load@backend@@@@
- \begingroup
- }
- }
-% \end{macrocode}
-%
-% Now we define it anyhow.
-% \begin{macrocode}
-\cs_gset_protected:Npn \@expl@sys@load@backend@@@@
- {
- \str_if_exist:NF \c_sys_backend_str
- { \sys_load_backend:n { } }
- }
-% \end{macrocode}
-% \end{macro}
-%
-% Process package options.
-% \begin{macrocode}
-%<*!2ekernel>
-\keys_set:nV { sys } \l_@@_options_clist
-\str_if_exist:NF \c_sys_backend_str
- { \sys_load_backend:n { } }
-%</!2ekernel>
-% \end{macrocode}
-%
-% \begin{macrocode}
-%<*!2ekernel>
-\bool_if:NT \g_@@_reload_bool
- {
- \cs_gset_eq:NN \__kernel_sys_configuration_load:n
- \__kernel_sys_configuration_load_std:n
- \ExplSyntaxOff
- \file_input_stop:
- }
-%</!2ekernel>
-% \end{macrocode}
-%
-% Load the dynamic part of the code, either now or during the next run.
-% \begin{macrocode}
-\cs_if_free:cTF { ver@expl3.sty }
- {
- \tex_everyjob:D \exp_after:wN
- {
- \tex_the:D \tex_everyjob:D
- \__kernel_sys_everyjob:
- }
- }
- { \__kernel_sys_everyjob: }
-% \end{macrocode}
-%
-% \begin{variable}{\s_@@_stop}
-% Internal scan marks. This code has to be reload-safe, so this one
-% has to be guarded with \cs{if_cs_exist:N} (\cs{cs_if_exist:NF}) wouldn't
-% do because it returns false for control sequences equal to \cs{scan_stop:}.
-% \begin{macrocode}
-\reverse_if:N \if_cs_exist:N \s_@@_stop
- \scan_new:N \s_@@_stop
-\fi:
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{macro}{\@pushfilename, \@popfilename}
-% \begin{macro}{\@@_status_pop:w}
-% \begin{macro}{\@expl@push@filename@@@@}
-% \begin{macro}{\@expl@push@filename@aux@@@@}
-% \begin{macro}{\@expl@pop@filename@@@@}
-% The idea here is to use \LaTeXe{}'s \tn{@pushfilename} and
-% \tn{@popfilename} to track the current syntax status. This can be
-% achieved by saving the current status flag at each push to a stack,
-% then recovering it at the pop stage and checking if the code
-% environment should still be active.
-%
-% Here the code follows the same patching logic than above for
-% \cs{@expl@sys@load@backend@@@@}.
-% \begin{macrocode}
-\cs_if_exist:NF \@expl@push@filename@@@@
- {
- \tl_put_left:Nn \@pushfilename { \@expl@push@filename@@@@ }
- \tl_put_right:Nn \@pushfilename { \@expl@push@filename@aux@@@@ }
- }
-\cs_gset_protected:Npn \@expl@push@filename@@@@
- {
- \exp_args:Ne \__kernel_file_input_push:n
- {
- \tl_to_str:N \@currname .
- \tl_to_str:N \@currext
- }
- \tl_put_left:Ne \l_@@_status_stack_tl
- {
- \bool_if:NTF \l__kernel_expl_bool
- { 1 }
- { 0 }
- }
- \ExplSyntaxOff
- }
-% \end{macrocode}
-% This bit of trickery is needed to grab the name of the file being loaded
-% so we can record it.
-% \begin{macrocode}
-\cs_gset_protected:Npn \@expl@push@filename@aux@@@@ #1#2#3
- {
- \str_gset:Nn \g_file_curr_name_str {#3}
- #1 #2 {#3}
- }
-% \end{macrocode}
-%
-% \begin{macrocode}
-\cs_if_exist:NF \@expl@pop@filename@@@@
- {
- \tl_put_right:Nn \@popfilename
- { \@expl@pop@filename@@@@ }
- }
-\cs_gset_protected:Npn \@expl@pop@filename@@@@
- {
- \__kernel_file_input_pop:
- \tl_if_empty:NTF \l_@@_status_stack_tl
- { \ExplSyntaxOff }
- { \exp_after:wN \@@_status_pop:w \l_@@_status_stack_tl \s_@@_stop }
- }
-% \end{macrocode}
-% The pop auxiliary function removes the first item from the stack,
-% saves the rest of the stack and then does the test. The flag here
-% is not a proper \texttt{bool}, so a low-level test is used.
-% \begin{macrocode}
-\cs_gset_protected:Npn \@@_status_pop:w #1#2 \s_@@_stop
- {
- \tl_set:Nn \l_@@_status_stack_tl {#2}
- \int_if_odd:nTF {#1}
- { \ExplSyntaxOn }
- { \ExplSyntaxOff }
- }
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-%
-% \begin{variable}{\l_@@_status_stack_tl}
-% As \pkg{expl3} itself cannot be loaded with the code environment
-% already active, at the end of the package \cs{ExplSyntaxOff} can
-% safely be called.
-% \begin{macrocode}
-\tl_if_exist:NF \l_@@_status_stack_tl
- {
- \tl_new:N \l_@@_status_stack_tl
- \tl_set:Nn \l_@@_status_stack_tl { 0 }
- }
-% \end{macrocode}
-% \end{variable}
-%
-% Tidy up configuration loading, as promised.
-% \begin{macrocode}
-%<*!2ekernel>
-\cs_gset_eq:NN \__kernel_sys_configuration_load:n
- \__kernel_sys_configuration_load_std:n
-%</!2ekernel>
-% \end{macrocode}
-%
-% For pre-loading, we have to manually disable the syntax.
-% \begin{macrocode}
-%<*2ekernel>
-\ExplSyntaxOff
-%</2ekernel>
-% \end{macrocode}
-%
-% \begin{macrocode}
-%</package&loader|2ekernel>
-% \end{macrocode}
-%
-% \subsection{Generic loader}
-%
-% \begin{macrocode}
-%<*generic>
-% \end{macrocode}
-%
-% The generic loader starts with a test to ensure that the current format is
-% not \LaTeXe{}!
-% \begin{macrocode}
-\begingroup
- \def\tempa{LaTeX2e}%
- \def\next{}%
- \ifx\fmtname\tempa
- \def\next
- {%
- \PackageInfo{expl3}{Switching from generic to LaTeX2e loader}%
-% \end{macrocode}
-% The \cs{relax} stops \cs{RequirePackage} from scanning for a date
-% argument. Putting \tn{endinput} \emph{after} loading the package is
-% crucial, as otherwise \tn{endinput} would close the file
-% \file{expl3.sty} at the end of its first line: indeed, as long as
-% \file{expl3.sty} is open it is impossible to close the file
-% \file{expl3-generic.tex}.
-% \begin{macrocode}
- \RequirePackage{expl3}\relax \endinput
- }%
- \fi
-\expandafter\endgroup
-\next
-% \end{macrocode}
-%
-% Reload check and identify the package:
-% no \LaTeXe{} mechanism so this is all pretty basic.
-% \begin{macrocode}
-\begingroup\expandafter\expandafter\expandafter\endgroup
-\expandafter\ifx\csname ver@expl3-generic.tex\endcsname\relax
-\else
- \immediate\write-1
- {%
- Package expl3 Info: The package is already loaded.%
- }%
- \expandafter\endinput
-\fi
-\immediate\write-1
- {%
- Package: expl3
- \ExplFileDate\space
- L3 programming layer (loader)%
- }%
-\expandafter\edef\csname ver@expl3-generic.tex\endcsname
- {\ExplFileDate\space L3 programming layer}%
-% \end{macrocode}
-%
-% \begin{macrocode}
-\ifnum\currentgrouplevel=0 %
-\else
- \errhelp{expl3 cannot be loaded inside a group:
- reading the code has been aborted.}%
- \errmessage{expl3 Error: Loading attempted inside a group!}%
- \expandafter\endinput
-\fi
-% \end{macrocode}
-%
-% \begin{variable}[int]{\l@expl@tidy@tl}
-% Save the category code of |@| and then set it to \enquote{letter}.
-% \begin{macrocode}
-\expandafter\edef\csname l@expl@tidy@tl\endcsname
- {%
- \catcode64=\the\catcode64\relax
- \let\expandafter\noexpand\csname l@expl@tidy@tl\endcsname
- \noexpand\undefined
- }%
-\catcode64=11 %
-% \end{macrocode}
-% \end{variable}
-%
-% \begin{macro}{\AtBeginDocument}
-% \begin{macro}[int]{\expl@AtBeginDocument}
-% There are a few uses of \cs{AtBeginDocument} in the package code: the
-% easiest way around that is to simply do the code \enquote{now}. As
-% bundles such as \pkg{miniltx} may have defined \cs{AtBeginDocument}
-% any existing definition is saved for restoration after the payload.
-% \begin{macrocode}
-\let\expl@AtBeginDocument\AtBeginDocument
-\def\AtBeginDocument#1{#1}%
-\expandafter\def\expandafter\l@expl@tidy@tl\expandafter
- {%
- \l@expl@tidy@tl
- \let\AtBeginDocument\expl@AtBeginDocument
- \let\expl@AtBeginDocument\undefined
- }%
-% \end{macrocode}
-% \end{macro}
-% \end{macro}
-%
-% Load the business end: this leaves \cs{expl3} syntax on.
-% \begin{macrocode}
-\input expl3-code.tex %
-% \end{macrocode}
-%
-% A check that the bootstrap code did not abort loading: if it did,
-% bail out silently here.
-% \begin{macrocode}
-\begingroup\expandafter\expandafter\expandafter\endgroup
-\expandafter\ifx\csname tex\string _let:D\endcsname\relax
- \expandafter\endinput
-\fi
-% \end{macrocode}
-%
-% \begin{macro}{\__kernel_sys_configuration_load:n}
-% Very basic.
-% \begin{macrocode}
-\cs_gset_protected:Npn \__kernel_sys_configuration_load:n #1
- {
- \group_begin:
- \cs_set_protected:Npn \ProvidesExplFile
- {
- \char_set_catcode_space:n { `\ }
- \ProvidesExplFileAux
- }
- \cs_set_protected:Npn \ProvidesExplFileAux ##1##2##3##4
- {
- \group_end:
- \iow_log:e { File:~##1~##2~v##3~##4 }
- }
- \tex_input:D #1 .def \scan_stop:
- }
-% \end{macrocode}
-% \end{macro}
-%
-% \begin{macro}{\g__kernel_backend_header_bool}
-% Load the dynamic code and standard back-end.
-% \begin{macrocode}
-\__kernel_sys_everyjob:
-\bool_new:N \g__kernel_backend_header_bool
-\bool_gset_true:N \g__kernel_backend_header_bool
-\sys_load_backend:n { }
-% \end{macrocode}
-% \end{macro}
-%
-% For the generic loader, a few final steps to take. Turn of \cs{expl3}
-% syntax and tidy up the small number of temporary changes.
-% \begin{macrocode}
-\ExplSyntaxOff
-\l@expl@tidy@tl
-% \end{macrocode}
-%
-% \begin{macrocode}
-%</generic>
-% \end{macrocode}
-%
-% \end{implementation}
-%
-% \PrintIndex