diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/expl3.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/l3kernel/expl3.dtx | 119 |
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} |