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.dtx136
1 files changed, 49 insertions, 87 deletions
diff --git a/macros/latex/contrib/l3kernel/expl3.dtx b/macros/latex/contrib/l3kernel/expl3.dtx
index 89d18df298..7295b770db 100644
--- a/macros/latex/contrib/l3kernel/expl3.dtx
+++ b/macros/latex/contrib/l3kernel/expl3.dtx
@@ -2,7 +2,7 @@
%
%% File: expl3.dtx
%
-% Copyright (C) 1990-2019 The LaTeX3 Project
+% Copyright (C) 1990-2020 The LaTeX3 Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
@@ -24,7 +24,7 @@
%
%<*driver|generic|package|2ekernel>
%</driver|generic|package|2ekernel>
-\def\ExplFileDate{2019-11-07}%
+\def\ExplFileDate{2020-01-12}%
%<*driver>
\documentclass[full]{l3doc}
\usepackage{graphicx}
@@ -51,7 +51,7 @@
% }^^A
% }
%
-% \date{Released 2019-11-07}
+% \date{Released 2020-01-12}
%
% \maketitle
%
@@ -365,6 +365,23 @@
% 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
@@ -774,9 +791,8 @@
% \section{The distribution}
%
% At present, the \pkg{expl3} modules are designed to be loaded on top
-% of \LaTeXe{}. In time, a \LaTeX3 format will be produced based on this
-% code. This allows the code to be used in \LaTeXe{} packages \emph{now}
-% while a stand-alone \LaTeX3 is developed.
+% of \LaTeXe{}. In time, a \LaTeX3 format may be produced based on this
+% code.
%
% \begin{bfseries}
% While \pkg{expl3} is still experimental, the bundle is now regarded
@@ -786,87 +802,29 @@
% \pkg{expl3}.
% \end{bfseries}
%
-% New modules will be added to the distributed version of \pkg{expl3}
-% as they reach maturity. At present, the \pkg{expl3} bundle consists
-% of a number of modules, most of which are loaded by including the
-% line:
+% The distribution of \pkg{expl3} is split up into three packages on
+% CTAN: \pkg{l3kernel}, \pkg{l3packages} and \pkg{l3experimental}.
+% For historical reasons,
% \begin{verbatim}
% \RequirePackage{expl3}
% \end{verbatim}
-% in a \LaTeXe{} package, class or other file. The \pkg{expl3} modules
-% regarded as stable, and therefore suitable for basing real code on,
-% are as follows:
-%
-% \begin{description}
-% \providecommand\explpkg[2]{\item[#1]#2}
-% \explpkg{l3basics}{
-% This contains the basic definition modules used
-% by the other packages.
-% }
-% \explpkg{l3box}{
-% Primitives for dealing with boxes.
-% }
-% \explpkg{l3clist}{
-% Methods for manipulating comma-separated token lists.
-% }
-% \explpkg{l3coffins}{
-% Augmented box constructs for alignment operations.
-% }
-% \explpkg{l3expan}{
-% This is the argument expansion module discussed earlier in this
-% document.
-% }
-% \explpkg{l3int}{
-% This implements the integer data-type \texttt{int}.
-% }
-% \explpkg{l3keys}{
-% For processing lists of the form
-% \texttt{\{ key1=val1 , key2=val2 \}}, intended to work
-% as a \LaTeX3 version of \pkg{xkeyval}/\pkg{kvoptions}, although
-% with input syntax more like that of \pkg{pgfkeys}.
-% }
-% \explpkg{l3msg}{
-% Communicating with the user: includes low-level hooks to allow
-% messages to be filtered (higher-level interface for filtering
-% to be written!).
-% }
-% \explpkg{l3names}{
-% This sets up the basic naming scheme and renames all
-% the \TeX{} primitives.
-% }
-% \explpkg{l3prg}{
-% Program control structures such as boolean data type |bool|, generic
-% do-while loops, and conditional flow.
-% }
-% \explpkg{l3prop}{
-% This implements the data-type for \enquote{property lists} that are used, in
-% particular, for storing key/value pairs.
-% }
-% \explpkg{l3quark}{
-% A \enquote{quark} is a command that is defined to expand to
-% itself! Therefore they must never be expanded as this would generate an
-% infinite recursion; they do however have many uses, \emph{e.g.}~as
-% special markers and delimiters within code.
-% }
-% \explpkg{l3seq}{
-% This implements data-types such as queues and stacks.
-% }
-% \explpkg{l3skip}{
-% Implements the \enquote{rubber length} datatype \texttt{skip}, the
-% \enquote{rigid length} datatype |dim|, and the math mode
-% \enquote{rubber length} datatype \texttt{muskip}.
-% }
-% \explpkg{l3tl}{
-% This implements a basic data-type, called a \textit{token-list
-% variable} (|tl var.|), used for storing named token lists: these are
-% \TeX{} macros with no arguments.
-% }
-% \explpkg{l3token}{
-% Analysing token lists and token streams, including peeking ahead to
-% see what's coming next and inspecting tokens to detect which kind
-% they are.
-% }
-% \end{description}
+% loads the code now 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, but is not always
+% at a programming level: most notably, \pkg{xparse} is stable and
+% suitable for wider use.
+%
+% 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 \LaTeX3}
%
@@ -1171,7 +1129,7 @@
% \begin{macrocode}
%<*2ekernel>
\everyjob\expandafter{\the\everyjob
- \message{expl3 <\ExplFileDate> L3 programming layer}%
+ \message{L3 programming layer <\ExplFileDate>}%
}
%</2ekernel>
%<*!2ekernel>
@@ -1322,13 +1280,17 @@
}
% \end{macrocode}
%
-% A backend has to be in place by the start of the document.
+% 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 odd group stuff avoids
+% needing to actually patch \tn{document}.
% \begin{macrocode}
%<*2ekernel>
-\AtBeginDocument
+\tl_put_left:Nn \document
{
+ \endgroup
\str_if_exist:NF \c_sys_backend_str
{ \sys_load_backend:n { } }
+ \begingroup
}
%</2ekernel>
%<*!2ekernel>