diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/expl3.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/expl3.dtx | 136 |
1 files changed, 49 insertions, 87 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/expl3.dtx b/Master/texmf-dist/source/latex/l3kernel/expl3.dtx index 89d18df2987..7295b770db3 100644 --- a/Master/texmf-dist/source/latex/l3kernel/expl3.dtx +++ b/Master/texmf-dist/source/latex/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> |