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.dtx119
1 files changed, 80 insertions, 39 deletions
diff --git a/Master/texmf-dist/source/latex/l3kernel/expl3.dtx b/Master/texmf-dist/source/latex/l3kernel/expl3.dtx
index cc7493c71e3..8af4d9ce93f 100644
--- a/Master/texmf-dist/source/latex/l3kernel/expl3.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/expl3.dtx
@@ -21,7 +21,7 @@
% for those people who are interested.
%
%<*driver|generic|package>
-\def\ExplFileDate{2017/05/29}%
+\def\ExplFileDate{2017/07/15}%
%</driver|generic|package>
%<*driver>
\documentclass[full]{l3doc}
@@ -49,7 +49,7 @@
% }^^A
% }
%
-% \date{Released 2017/05/29}
+% \date{Released 2017/07/15}
%
% \maketitle
%
@@ -97,7 +97,7 @@
% 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 will need to become familiar with
+% 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
@@ -239,11 +239,11 @@
% \subsection{Formal naming syntax}
%
% We shall now look in more detail at the syntax of these names. A
-% function name in \LaTeX3 will have a name consisting of three parts:
+% 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 will have (up to) four distinct parts to its name:
+% while a variable has (up to) four distinct parts to its name:
% \begin{quote}
% |\|\meta{scope}|_|\meta{module}|_|\meta{description}|_|\meta{type}
% \end{quote}
@@ -262,7 +262,8 @@
% 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}.
+% \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
@@ -351,7 +352,7 @@
% \tl_new:N \l_@@_my_tl
% % \end{macrocode}
% \end{verbatim}
-% will be converted by \pkg{l3docstrip} to
+% is converted by \pkg{l3docstrip} to
% \begin{verbatim}
% \cs_new:Npn \__foo_function:n #1
% ...
@@ -383,7 +384,7 @@
% stack.\footnote{See \emph{The \TeX{}book}, p.\,301, for further
% information.}
%
-% The \meta{type} will be in the list of available
+% 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
@@ -461,7 +462,7 @@
% behaviour}. The \LaTeX3 coding convention is that all variables must
% be declared before use.
%
-% The \pkg{expl3} package can be loaded with the |check-declarations|
+% 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.
@@ -537,7 +538,7 @@
% \begin{quote}
% \cs{seq_gpush:Nn} |\g_ior_file_name_seq| |\l_ior_curr_file_tl|
% \end{quote}
-% we will not get the value of the variable pushed onto the stack,
+% 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
@@ -588,7 +589,7 @@
% \end{quote}
% Remember that \texttt{c} arguments are \emph{fully expanded} by
% \TeX{} when creating csnames. This means that (a) the entire
-% argument must be expandable and (b) any variables will be
+% argument must be expandable and (b) any variables are
% converted to their content. So the preceding examples are also
% equivalent to
% \begin{quote}
@@ -629,7 +630,7 @@
% list.\\ Almost the same as the |x| type except here the token list
% is expanded fully until the first unexpandable token is found and
% the rest is left unchanged. Note that if this function finds a
-% space at the beginning of the argument it will gobble it and not
+% space at the beginning of the argument it gobbles it and does not
% expand the next token.
% \end{description}
%
@@ -691,21 +692,21 @@
% 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 will be defined with the appropriate
-% argument types and its name will be |\tl_test_in:cV|. Now this code
-% fragment will be simply:
+% 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~|}| will be
+% 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 will provide variants
+% 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.
@@ -761,7 +762,7 @@
%
% 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 will be identical and thus no conflict will occur.
+% two definitions are identical and thus no conflict occurs.
%
% \section{The distribution}
%
@@ -836,7 +837,7 @@
% }
% \explpkg{l3quark}{
% A \enquote{quark} is a command that is defined to expand to
-% itself! Therefore they must never be expanded as this will generate
+% 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.
% }
@@ -919,21 +920,30 @@
% 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.
+% initialised. See also the function \cs{debug_check_declarations_on:}.
%
% \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 for \LaTeX3).
+% required by the bootstrap code for \LaTeX3). See also the function
+% \cs{debug_log_functions_on:}.
+%
+% \DescribeOption{enable-debug}
+% To allow more localized checking and logging than provided by
+% \texttt{check-declarations} and \texttt{log-functions}, \pkg{expl3}
+% provides a few \cs[no-index]{debug_\ldots{}} functions (described
+% elsewhere) that turn on the corresponding checks within a group.
+% These functions can only be used if \pkg{expl3} is loaded with the
+% \texttt{enable-debug} option.
%
% \DescribeOption{driver}
% Selects the driver to be used for color, graphics and related operations that
% are driver-dependent. Options available are
% \begin{itemize}[font = \texttt]
% \item[auto] Let \LaTeX3 determine the correct driver. With DVI output, this
-% will select the \texttt{dvips} back-end for \pdfTeX{} and \LuaTeX{}, and
+% selects the \texttt{dvips} back-end for \pdfTeX{} and \LuaTeX{}, and
% \texttt{dvipdfmx} for \pTeX{} and \upTeX{}. This is the standard setting.
% \item[latex2e] Use the \pkg{graphics} package to select the driver, rather
% than \LaTeX3 code.
@@ -952,17 +962,17 @@
% \begin{verbatim}
% \input expl3-generic %
% \end{verbatim}
-% This will enable the programming layer to work with the other formats.
+% 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 will automatically switch to the appropriate
+% 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} will be available.
-% Note that other \LaTeXe{} packages \emph{using} \pkg{expl3} will not
-% be loadable: package loading is dependent on the \LaTeXe{} package-management
+% 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{Engine/primitive requirements}
@@ -1174,14 +1184,19 @@
% \begin{variable}[int]
% {
% \l@expl@check@declarations@bool ,
-% \l@expl@log@functions@bool
+% \l@expl@log@functions@bool ,
+% \l@expl@enable@debug@bool
% }
% \begin{variable}[int]{\l@expl@options@clist}
-% Options to be set up.
-% These have to be done by hand as there is no \pkg{expl3} yet: the logging
-% option is needed before loading \pkg{l3basics}! Only a minimal set of
-% options are handled here: others are left for a proper key--value approach
-% once the kernel is loaded.
+% Options to be set up. These have to be done by hand as there is no
+% \pkg{expl3} yet: the logging option is needed before loading
+% \pkg{l3basics}! Only a minimal set of options are handled here:
+% others are left for a proper key--value approach once the kernel is
+% loaded. After processing the options we set the
+% \texttt{enable-debug} boolean so that the options
+% \texttt{check-declarations} and \texttt{log-functions} imply
+% \texttt{enable-debug}: otherwise the necessary debugging code would
+% not be set up properly.
% \begin{macrocode}
\newcommand\expl@create@bool@option[2]%
{%
@@ -1193,7 +1208,9 @@
}
\expl@create@bool@option{check-declarations}\l@expl@check@declarations@bool
\expl@create@bool@option{log-functions}\l@expl@log@functions@bool
+\expl@create@bool@option{enable-debug}\l@expl@enable@debug@bool
\let\expl@create@bool@option\@undefined
+\chardef\l@expl@enable@debug@bool=0 %
\newcommand*\l@expl@options@clist{}
\DeclareOption*
{%
@@ -1207,6 +1224,12 @@
\fi
}
\ProcessOptions\relax
+\ifodd\l@expl@check@declarations@bool
+ \chardef\l@expl@enable@debug@bool=1 %
+\fi
+\ifodd\l@expl@log@functions@bool
+ \chardef\l@expl@enable@debug@bool=1 %
+\fi
% \end{macrocode}
% \end{variable}
% \end{variable}
@@ -1238,7 +1261,7 @@
% \end{macrocode}
% \end{macro}
%
-% Load the business end: this will leave \cs{expl3} syntax on.
+% Load the business end: this leaves \cs{expl3} syntax on.
% \begin{macrocode}
\input{expl3-code.tex}
% \end{macrocode}
@@ -1268,7 +1291,7 @@
% \begin{variable}[int]{\l__expl_native_drivers_bool}
% With the code now loaded, options can be handled using a real key--value
% interpreter. The \enquote{faked} options are also included so that any
-% erroneous input will be mopped up (\emph{e.g.}~\texttt{log-function =
+% erroneous input is mopped up (\emph{e.g.}~\texttt{log-function =
% foo}). The checks on driver choice are set up here, so when actually
% the driver it's a straight forward operation.
% \begin{macrocode}
@@ -1509,6 +1532,11 @@
% \begin{macrocode}
\tl_put_left:Nn \@pushfilename
{
+ \exp_args:Nx \__file_input_push:n
+ {
+ \tl_to_str:N \@currname
+ \tl_to_str:N \@currext
+ }
\tl_put_left:Nx \l__expl_status_stack_tl
{
\bool_if:NTF \l__kernel_expl_bool
@@ -1517,8 +1545,19 @@
}
\ExplSyntaxOff
}
+\tl_put_right:Nn \@pushfilename { \@pushfilenameaux }
+% \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_set_protected:Npn \@pushfilenameaux #1#2#3
+ {
+ \str_gset:Nn \g_file_curr_name_str {#3}
+ #1 #2 {#3}
+ }
\tl_put_right:Nn \@popfilename
{
+ \__file_input_pop:
\tl_if_empty:NTF \l__expl_status_stack_tl
{ \ExplSyntaxOff }
{ \exp_after:wN \__expl_status_pop:w \l__expl_status_stack_tl \q_stop }
@@ -1572,7 +1611,7 @@
% \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} will close the file
+% 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}.
@@ -1622,14 +1661,16 @@
% \begin{variable}[int]
% {
% \l@expl@check@declarations@bool ,
-% \l@expl@log@functions@bool
+% \l@expl@log@functions@bool ,
+% \l@expl@enable@debug@bool
% }
% In generic mode, there is no convenient option handling and so instead
% the two variables are defined to do nothing.
-% appropriate value before input of the loader.
+% Appropriate value before input of the loader.
% \begin{macrocode}
\chardef \l@expl@check@declarations@bool = 0 %
\chardef \l@expl@log@functions@bool = 0 %
+\chardef \l@expl@enable@debug@bool = 0 %
% \end{macrocode}
% \end{variable}
%
@@ -1652,7 +1693,7 @@
% \end{macro}
% \end{macro}
%
-% Load the business end: this will leave \cs{expl3} syntax on.
+% Load the business end: this leaves \cs{expl3} syntax on.
% \begin{macrocode}
\input expl3-code.tex %
% \end{macrocode}