summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/expl3.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/expl3.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/expl3.dtx137
1 files changed, 121 insertions, 16 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/expl3.dtx b/Master/texmf-dist/source/latex/l3kernel/expl3.dtx
index e1a36c6db56..85284e594ac 100644
--- a/Master/texmf-dist/source/latex/l3kernel/expl3.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/expl3.dtx
@@ -24,7 +24,7 @@
%
%<*driver|generic|package|2ekernel>
%</driver|generic|package|2ekernel>
-\def\ExplFileDate{2020-07-17}%
+\def\ExplFileDate{2020-08-07}%
%<*driver>
\documentclass[full]{l3doc}
\usepackage{graphicx}
@@ -51,7 +51,7 @@
% }^^A
% }
%
-% \date{Released 2020-07-17}
+% \date{Released 2020-08-07}
%
% \maketitle
%
@@ -798,16 +798,14 @@
%
% \section{The distribution}
%
-% At present, the \pkg{expl3} modules are designed to be loaded on top
-% of \LaTeXe{}. In time, a \LaTeX3 format may be produced based on this
-% code.
+% The \pkg{expl3} modules are designed to be loaded on top of \LaTeXe{}.
%
% \begin{bfseries}
-% While \pkg{expl3} is still experimental, the bundle is now regarded
-% as broadly stable. The syntax conventions and functions provided
+% 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}.
+% \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
@@ -821,7 +819,9 @@
% 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}.
+% \texttt{interface3.pdf}. With an up-to-date \LaTeXe{} kernel, this
+% code is built into the format file and therefore can be used
+% without any further steps.
%
% The material in \pkg{l3packages} is also stable, but is not always
% at a programming level: most notably, \pkg{xparse} is stable and
@@ -834,9 +834,9 @@
% in terms of interface and functionality detail. Feedback on these
% modules is extremely valuable.
%
-% \section{Moving from \LaTeXe{} to \LaTeX3}
+% \section{Moving from \LaTeXe{} to \pkg{expl3}}
%
-% To help programmers to use \LaTeX3 code in existing \LaTeXe{} package,
+% 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.
@@ -845,11 +845,10 @@
% \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
-% is currently no native \LaTeX3 package loading module.
+% 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
-% \texttt{l3package} bundle, available from CTAN or the \LaTeX3 SVN
-% repository.
+% \texttt{l3package} bundle.
% \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}).
@@ -894,7 +893,7 @@
% updated in time.
%
% \DescribeOption{check-declarations}
-% All variables used in \LaTeX3 code should be declared. This is enforced
+% 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
@@ -907,7 +906,7 @@
% 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 for \LaTeX3). See also \cs{debug_on:n}
+% required by the bootstrap code). See also \cs{debug_on:n}
% \texttt{\{log-functions\}} in \pkg{l3candidates} for finer control.
%
% \DescribeOption{enable-debug}
@@ -936,6 +935,12 @@
% 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
@@ -1047,6 +1052,24 @@
% \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}).
+% \begin{macrocode}
+%<*2ekernel>
+\global\expandafter\let\csname\detokenize
+ {c__kernel_expl_date_tl}\endcsname\ExplFileDate
+%</2ekernel>
+% \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.
@@ -1220,6 +1243,88 @@
%<@@=expl>
% \end{macrocode}
%
+% Several times users reported this error when loading \pkg{expl3}:
+% \begin{verbatim}
+% ! Undefined control sequence.
+% l.67 \bool
+% _new:N \g__expl_reload_bool
+% \end{verbatim}
+% raised in the reload block below. This happens because the reload
+% check below assumes that if the boolean \cs{g_@@_reload_bool} doesn't
+% exist, this file is being loaded for the first time, and \pkg{expl3}
+% syntax is on. This is a bit of a stretch for assumptions, but it's
+% valid as long as everything's in sync. However the problem reported
+% happened because of a stray format file in the user tree which didn't
+% have the reload code defined here (commit \texttt{1d16336}), so the
+% \cs{g_@@_reload_bool} doesn't exist, but \pkg{expl3} syntax is off,
+% thus the error.
+%
+% At this point, if we have \cs{c__kernel_expl_date_tl} defined, the
+% situation is straightforward: if it matches \cs{ExplLoaderFileDate},
+% then everything's as expected, so no need to worry. If it doesn't,
+% then the current version of \pkg{expl3} differs from the one in the
+% format, so raise a fatal error: the bahaviour is too unpredictable to
+% continue safely. Also, if the error is to be raised, then we're
+% reloading, which means that \pkg{expl3} syntax is off, so we turn it
+% on for the message.
+% \begin{macrocode}
+\ifcsname\detokenize{c__kernel_expl_date_tl}\endcsname
+ \expandafter\ifx\csname\detokenize
+ {c__kernel_expl_date_tl}\endcsname\ExplLoaderFileDate
+ \else
+ \ExplSyntaxOn
+ \__kernel_msg_set:nnn { kernel } { mismatched-expl3 }
+ {
+ Mismatched~expl3~detected!~Loading~expl3~will~abort.
+ \\ \\
+ The~version~of~expl3~preloaded~in~LaTeX~is~
+ \c__kernel_expl_date_tl,~but~the~version~of~expl3~you~are~
+ trying~to~load~is~dated~\ExplLoaderFileDate.~This~is~most~
+ likely~due~to~a~stray~format~file~in~the~user~tree.~Please~
+ make~sure~that~your~LaTeX~format~is~updated.
+ }
+ \exp_after:wN \ExplSyntaxOff \use:n
+ {
+ \__kernel_msg_critical:nn { kernel } { mismatched-expl3 }
+ \use:c { fi: } \use:c { fi: }
+ }
+ \fi
+% \end{macrocode}
+% If \cs{c__kernel_expl_date_tl} does \emph{not} exist, then we're on
+% uncharted lands (that is, any time prior to the version that
+% introduced this token list :-). Two cases might be here, depending
+% whether \pkg{expl3} is loaded into the kernel or not. If we're loading
+% \pkg{expl3} \enquote{normally} as a package, \pkg{expl3} syntax is on.
+% Otherwise it's already loaded in the kernel and we're reloading
+% \file{expl3.sty} so (\file{expl3-code.tex} doesn't load again and)
+% \pkg{expl3} syntax is off.
+% \begin{macrocode}
+\else
+ \ifodd\csname\detokenize{l__kernel_expl_bool}\endcsname
+% \end{macrocode}
+% Package mode; all should be fine, since \file{expl3.sty} and
+% \file{expl3-code.tex} are both loaded in one go, so versions should
+% match (if they don't, it's detected above).
+% Also, we've just tested that \pkg{expl3} syntax is on, so the reload
+% test below will return false and \cs{bool_new:N} will run correctly.
+% \begin{macrocode}
+ \else
+% \end{macrocode}
+% In this branch we're reloading, but there are still two cases to
+% consider (sigh\ldots); whether the version preloaded in the format
+% is recent enough to have \cs{g_@@_reload_bool} (2020-06-18 and
+% later) or not. If the boolean is there, we have to do nothing
+% because right ahead we deal with this case.
+% If it is not, we just have to create it:
+% \begin{macrocode}
+ \ExplSyntaxOn
+ \bool_if_exist:NF \g_@@_reload_bool
+ { \bool_new:N \g_@@_reload_bool }
+ \ExplSyntaxOff
+ \fi
+\fi
+% \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