From 6d95b4a2c1bbdaea1a3802c822808f476ac5703b Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 16 Sep 2011 22:35:41 +0000 Subject: l3kernel 2828 (15sep11) git-svn-id: svn://tug.org/texlive/trunk@23983 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/source/latex/l3kernel/expl3.dtx | 397 +++++++++++----------- 1 file changed, 196 insertions(+), 201 deletions(-) (limited to 'Master/texmf-dist/source/latex/l3kernel/expl3.dtx') diff --git a/Master/texmf-dist/source/latex/l3kernel/expl3.dtx b/Master/texmf-dist/source/latex/l3kernel/expl3.dtx index fc8efd3c193..9f9b88667ef 100644 --- a/Master/texmf-dist/source/latex/l3kernel/expl3.dtx +++ b/Master/texmf-dist/source/latex/l3kernel/expl3.dtx @@ -9,7 +9,7 @@ %% %% http://www.latex-project.org/lppl.txt %% -%% This file is part of the "expl3 bundle" (The Work in LPPL) +%% This file is part of the "l3kernel bundle" (The Work in LPPL) %% and all files in that bundle must be distributed together. %% %% The released version of this bundle is available from CTAN. @@ -37,8 +37,8 @@ \RequirePackage{l3names} \def\ExplFileName{expl3} \def\ExplFileDescription{L3 Experimental code bundle wrapper} -\def\ExplFileDate{2011/09/05} -\def\ExplFileVersion{2729} +\def\ExplFileDate{2011/09/15} +\def\ExplFileVersion{2828} % %<*driver> \documentclass[full]{l3doc} @@ -47,17 +47,17 @@ \end{document} % % \fi -% +% % \providecommand\acro[1]{\textsc{\MakeLowercase{#1}}} % \newenvironment{arg-description}{% % \begin{itemize}\def\makelabel##1{\hss\llap{\bfseries##1}}}{\end{itemize}} -% +% % \title{^^A % The \textsf{expl3} package and \LaTeX3 programming^^A % \thanks{This file describes v\ExplFileVersion, % last revised \ExplFileDate.}^^A % } -% +% % \author{^^A % The \LaTeX3 Project\thanks % {^^A @@ -74,12 +74,12 @@ % \begin{documentation} % % \begin{abstract} -% +% % This document gives an introduction to a new set of programming % conventions that have been designed to meet the requirements of % implementing large scale \TeX{} macro programming projects such as % \LaTeX{}. These programming conventions are the base layer of \LaTeX3. -% +% % The main features of the system described are: % \begin{itemize} % \item classification of the macros (or, in \LaTeX{} terminology, @@ -89,7 +89,7 @@ % \item a simple mechanism for controlling the expansion of a function's % arguments. % \end{itemize} -% This system is being used as the basis for \TeX{} programming within +% This system is being used as the basis for \TeX{} programming within % the \LaTeX3 project. Note that the language is not intended for either % document mark-up or style specification. Instead, it is intended that % such features will be built on top of the conventions described here. @@ -99,56 +99,56 @@ % layer provided by the \LaTeX3 Project, see the accompanying \texttt{source3} % document. % -% \end{abstract} -% +% \end{abstract} +% % \section{Introduction} -% +% % The first step to develop a \LaTeX{} kernel beyond \LaTeXe{} is to -% address how the underlying system is programmed. Rather than the -% current mix of \LaTeX{} and \TeX{} macros, the \LaTeX3 system provides -% its own consistent interface to all of the functions needed to +% address how the underlying system is programmed. Rather than the +% current mix of \LaTeX{} and \TeX{} macros, the \LaTeX3 system provides +% its own consistent interface to all of the functions needed to % control \TeX{}. A key part of this work is to ensure that everything -% is documented, so that \LaTeX{} programmers and users can work +% is documented, so that \LaTeX{} programmers and users can work % efficiently without needing to be familiar with the internal nature % of the kernel or with plain \TeX{}. -% +% % 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 % the syntax of the new language. -% +% % The next section shows where this language fits into a complete % \TeX{}-based document processing system. We then describe the major % features of the syntactic structure of command names, including the % argument specification syntax used in function names. -% +% % The practical ideas behind this argument syntax will be explained, -% together with the expansion control mechanism and the interface -% used to define variant forms of functions. -% +% together with the expansion control mechanism and the interface +% used to define variant forms of functions. +% % As we shall demonstrate, the use of a structured naming scheme and of % variant forms for functions greatly improves the readability of the % code and hence also its reliability. Moreover, experience has shown % that the longer command names which result from the new syntax do not % make the process of \emph{writing} code significantly harder. -% +% % \section{Languages and interfaces} -% +% % It is possible to identify several distinct languages related to the % various interfaces that are needed in a \TeX{}-based document processing % system. This section looks at those we consider most important for % the \LaTeX3 system. -% +% % \begin{description} -% \item[Document mark-up] This comprises those commands (often called +% \item[Document mark-up] This comprises those commands (often called % tags) that are to embedded in the document (the |.tex| file). -% +% % It is generally accepted that such mark-up should be essentially % \emph{declarative}. It may be traditional \TeX{}-based mark-up such % as \LaTeXe{}, as described in~\cite{A-W:LLa94} and~\cite{A-W:GMS94}, % or a mark-up language defined via \acro{HTML} or \acro{XML}. -% +% % One problem with more traditional \TeX{} coding conventions (as % described in~\cite{A-W:K-TB}) is that the names and syntax of \TeX{}'s % primitive formatting commands are ingeniously designed to be @@ -160,37 +160,37 @@ % \TeX{} programmers to define higher-level commands, and their % idiosyncratic syntax is not at all popular with this community. % Moreover, many of them have names that could be very useful as -% document mark-up tags were they not pre-empted as primitives -% (\emph{e.g.}~\cs{box} or \cs{special}). -% +% document mark-up tags were they not pre-empted as primitives +% (\emph{e.g.}~\tn{box} or \tn{special}). +% % \item[Designer interface] This relates a (human) typographic -% designer's specification for a document to a program that +% designer's specification for a document to a program that % \enquote{formats % the document}. It should ideally use a declarative language that -% facilitates expression of the relationship and spacing rules +% facilitates expression of the relationship and spacing rules % specified for the layout of the various document elements. -% +% % This language is not embedded in document text and it will be very -% different in form to the document mark-up language. For \LaTeX, -% this level was almost completely missing from \LaTeX2.09; \LaTeXe{} -% made some improvements in this area but it is still the case that -% implementing a design specification in \LaTeX{} requires far more +% different in form to the document mark-up language. For \LaTeX, +% this level was almost completely missing from \LaTeX2.09; \LaTeXe{} +% made some improvements in this area but it is still the case that +% implementing a design specification in \LaTeX{} requires far more % \enquote{low-level} coding than is acceptable. -% -% \item[Programmer interface] -% This language is the implementation language within which the -% basic typesetting functionality is implemented, building upon the +% +% \item[Programmer interface] +% This language is the implementation language within which the +% basic typesetting functionality is implemented, building upon the % primitives of \TeX{} (or a successor program). It may also be used % to implement the previous two languages \enquote{within} \TeX{}, as in % the % current \LaTeX{} system. -% +% % \end{description} -% -% The last layer is covered by the conventions described in this -% document, which describes a system aimed at providing a suitable +% +% The last layer is covered by the conventions described in this +% document, which describes a system aimed at providing a suitable % basis for coding \LaTeX3. Its main distinguishing features are -% summarised here: +% summarised here: % \begin{itemize} % \item A consistent naming scheme for all commands, including \TeX{} % primitives. @@ -199,14 +199,14 @@ % functionality. % \item A simple mechanism for controlling argument expansion. % \item Provision of a set of core \LaTeX{} functions that is sufficient -% for handling programming constructs such as queues, sets, stacks, +% for handling programming constructs such as queues, sets, stacks, % property lists. % \item A \TeX{} programming environment in which, for example, all % white space is ignored. % \end{itemize} -% +% % \section{The naming scheme} -% +% % \LaTeX3 does not use |@| as a \enquote{letter} for defining % internal macros. Instead, the symbols |_| and |:| % are used in internal macro names to provide structure. In @@ -226,7 +226,7 @@ % \emph{module}. % % \subsection{Examples} -% +% % Before giving the details of the naming scheme, here are a few typical % examples to indicate the flavour of the scheme; first some variable % names. @@ -234,15 +234,15 @@ % \cs{l_tmpa_box} is a local variable (hence the~|l_| prefix) % corresponding to a box register.\\ % \cs{g_tmpa_int} is a global variable (hence the~|g_| prefix) -% corresponding to an integer register (i.e.~a \TeX{} count +% corresponding to an integer register (i.e.~a \TeX{} count % register).\\ % \cs{c_empty_tl} is the constant~(|c_|) token list variable % that is always empty. % \end{quote} % % Now here is an example of a typical function name. -% -% \cs{seq_push:Nn} is the function which puts the token list specified +% +% \cs{seq_push:Nn} is the function which puts the token list specified % by its second argument onto the stack specified by its first argument. % The different natures of the two arguments are indicated by the~|:Nn| % suffix. The first argument must be a single token which \enquote{names} @@ -253,9 +253,9 @@ % list (which we shall here call a \textit{braced token list}): the~|n| % denotes such a \enquote{normal} argument form. The name of the function % indicates it belongs to the |seq| module. -% +% % \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: % \begin{quote} @@ -271,25 +271,25 @@ % \meta{module} and \meta{description} % \end{quote} % these both give information about the command. -% -% A \emph{module} is a collection of closely related functions and +% +% A \emph{module} is a collection of closely related functions and % variables. Typical module names include~|int| for integer parameters % and related functions,~|seq| for sequences and~|box| for boxes. -% +% % Packages providing new programming functionality will add new modules % 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}. -% +% % The \emph{description} gives more detailed information about the % function or parameter, and provides a unique name for it. It should -% consist of letters and, possibly,~|_|~characters. In general, the -% description should use |_| to divide up \enquote{words} or other easy to +% consist of letters and, possibly,~|_|~characters. In general, the +% description should use |_| to divide up \enquote{words} or other easy to % follow parts of the name. For example, the \LaTeX3 kernel provides % \cs{if_cs_exist:N} which, as might be expected, tests if a command % name exists. -% +% % As a semi-formalized concept the letter |g| is sometimes used to % prefix certain parts of the \meta{description} % to mark the function as \enquote{globally acting}, \emph{e.g.}, @@ -299,13 +299,13 @@ % variable prefixes. % % \subsubsection{Variables: scope and type} -% +% % The \meta{scope} part of the name describes how the variable can be -% accessed. Variables are classified as local, global or constant. +% accessed. Variables are classified as local, global or constant. % This \emph{scope} type appears as a code at the beginning of the name; % the codes used are: % \begin{arg-description} -% \item[c] constants (global variables whose value should not be +% \item[c] constants (global variables whose value should not be % changed); % \item[g] variables whose value should only be set globally; % \item[l] variables whose value should only be set locally. @@ -318,19 +318,19 @@ % assignments to a variable; otherwise you risk exhausting the save stack. % \unskip\footnote{See \emph{The \TeX{}book}, p.\,301, for further % information.} -% -% The \meta{type} will be in the list of available +% +% The \meta{type} will be 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 % primitive \TeX{} data-types, such as the various registers, but to % these will be added data-types built within the \LaTeX{} programming % system. -% +% % The data types in \LaTeX3 are: % \begin{description} % \item[bool] either true or false (the \LaTeX3 implementation does -% not use \cs{iftrue} or \cs{iffalse}); +% not use \tn{iftrue} or \tn{iffalse}); % \item[box] box register; % \item[clist] comma separated list; % \item[coffin] a \enquote{box with handles} --- a higher-level data @@ -339,34 +339,34 @@ % \item[fp] floating-point values; % \item[int] integer-valued count register; % \item[prop] property list; -% \item[seq] sequence: a data-type used to implement lists (with +% \item[seq] sequence: a data-type used to implement lists (with % access at both ends) and stacks; % \item[skip] \enquote{rubber} lengths; -% \item[stream] an input or output stream (for reading from or writing +% \item[stream] an input or output stream (for reading from or writing % to, respectively); % \item[tl] \enquote{token list variables}: placeholders for token lists. % \end{description} % When the \meta{type} and \meta{module} are identical (as often happens in % the more basic modules) the \meta{module} part is often omitted for % aesthetic reasons. -% -% The name \enquote{token list} may cause confusion, and so some background is -% useful. \TeX{} works with tokens and lists of tokens, rather than -% characters. It provides two ways to store these token lists: within +% +% The name \enquote{token list} may cause confusion, and so some background is +% useful. \TeX{} works with tokens and lists of tokens, rather than +% characters. It provides two ways to store these token lists: within % macros and as token registers (|toks|). The implementation in \LaTeX3 means % that % |toks| are not required, and that all operations for storing tokens can us % the |tl| variable type. -% +% % Experienced \TeX{} programmers will notice that some of the variable % types listed are native \TeX{} registers whilst others are not. In % general, the underlying \TeX{} implementation for a data structure may % vary but the \emph{documented interface} will be stable. For example, % the |prop| data type was originally implemented as a |toks|, but % is currently built on top of the |tl| data structure. -% +% % \subsubsection{Variables: guidance} -% +% % Both comma lists and sequences both have similar characteristics. % They both use special delimiters to mark out one entry from the % next, and are both accessible at both ends. In general, it is @@ -381,31 +381,31 @@ % handling user input where commas will not occur. On the other % hand, sequences should be used to store arbitrary lists of % data. -% +% % \pkg{expl3} implements stacks using the sequence data structure. -% Thus creating stacks involves first creating a sequence, and +% Thus creating stacks involves first creating a sequence, and % then using the sequence functions which work in a stack manner % (\cs{seq_push:Nn}, \emph{etc}.). -% -% Due to the nature of the underlying \TeX{} implementation, it is -% possible to assign values to token list variables and comma lists +% +% Due to the nature of the underlying \TeX{} implementation, it is +% possible to assign values to token list variables and comma lists % without first declaring them. However, this is \emph{not supported % 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| 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. -% +% The \pkg{expl3} package can be loaded with the |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. +% % \subsubsection{Functions: argument specifications} -% +% % Function names end with an \meta{arg-spec} after a colon. This % gives an indication of the types of argument that a function takes, % and provides a convenient method of naming similar functions that % differ only in their argument forms (see the next section for % examples). -% +% % The \meta{arg-spec} consists of a (possibly empty) list of letters, % each denoting one argument of the function. The letter, including % its case, conveys information about the type of argument required. @@ -440,34 +440,34 @@ % delimited arguments and the boolean tests needed after certain % primitive |\if|\ldots\ commands. % \end{arg-description} -% -% In case of |n| arguments that consist of a single token the +% +% In case of |n| arguments that consist of a single token the % surrounding braces can be omitted in nearly all % situations---functions that force the use of braces even for single % token arguments are explicitly mentioned. However, programmers are -% encouraged to always use braces around \texttt{n} arguments, as this +% encouraged to always use braces around \texttt{n} arguments, as this % makes the relationship between function and argument clearer. -% +% % Further argument specifiers are available as part of the expansion % control system. These are discussed in the next section. -% +% % \section{Expansion control} % % Let's take a look at some typical operations one might want to % perform. Suppose we maintain a stack of open files and we use the % stack |\g_ior_file_name_seq| to keep track of them (|io| is the % file reading and writing module: it uses the module prefix -% \texttt{ior} for reading functions and variables). The basic -% operation here is to push a name onto this stack which could be -% done by the operation +% \texttt{ior} for reading functions and variables). The basic +% operation here is to push a name onto this stack which could be +% done by the operation % \begin{quote} % |\seq_gpush:Nn \g_ior_file_name_seq {#1}| % \end{quote} % where |#1| is the filename. In other words, this operation would % push the file name as is onto the stack. % -% However, we might face a situation where the filename is stored in -% a variable of some sort, say |\l_ior_curr_file_tl|. In this case we +% However, we might face a situation where the filename is stored in +% a variable of some sort, say |\l_ior_curr_file_tl|. In this case we % want to retrieve the value of the variable. If we simply use % \begin{quote} % |\seq_gpush:Nn \g_io_file_name_seq \l_io_curr_file_tl| @@ -476,7 +476,7 @@ % only the variable name itself. Instead a suitable number of % |\exp_after:wN| would be necessary (together with extra braces) to % change the order of expansion,\footnote{\cs{exp_after:wN} is -% the \LaTeX3 name for the \TeX{} \cs{expandafter} primitive.}, \emph{i.e.} +% the \LaTeX3 name for the \TeX{} \tn{expandafter} primitive.}, \emph{i.e.} % \begin{quote} % |\exp_after:wN| \\ % | \seq_gpush:Nn| \\ @@ -487,12 +487,12 @@ % \end{quote} % % The above example is probably the simplest case but already shows -% how the code changes to something difficult to understand. -% Furthermore there is an assumption in this: that the storage bin -% reveals its contents after exactly one expansion. Relying on this -% means that you cannot do proper checking plus you have to know +% how the code changes to something difficult to understand. +% Furthermore there is an assumption in this: that the storage bin +% reveals its contents after exactly one expansion. Relying on this +% means that you cannot do proper checking plus you have to know % exactly how a storage bin acts in order to get the correct number -% of expansions. Therefore \LaTeX3 provides the programmer with a +% of expansions. Therefore \LaTeX3 provides the programmer with a % general scheme that keeps the code compact and easy to understand. % % To denote that some argument to a function needs special treatment one @@ -501,7 +501,7 @@ % \begin{quote} % |\seq_gpush:NV \g_io_file_name_seq \l_io_curr_file_tl| % \end{quote} -% to achieve the desired effect. Here the |V| (the second argument) +% to achieve the desired effect. Here the |V| (the second argument) % is for \enquote{retrieve the value of the variable} before passing it to % the base function. % @@ -516,13 +516,13 @@ % \begin{quote} % |\seq_gpush:cV { g_file_name_seq } \l_tmpa_tl| % \end{quote} -% is equivalent to +% is equivalent to % \begin{quote} % |\seq_gpush:NV \g_file_name_seq \l_tmpa_tl"| % \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 +% \TeX{} when creating csnames. This means that (a) the entire +% argument must be expandable and (b) any variables will be % converted to their content. So the preceding examples are also % equivalent to % \begin{quote} @@ -547,12 +547,12 @@ % text of an~|\edef|, and the expansion is passed to the function as % a braced token list. This means that expansion takes place until % only unexpandable tokens are left. -% \item[o] One-level-expanded token or braced token list.\\ +% \item[o] One-level-expanded token or braced token list.\\ % This means that the argument is expanded one level, as by -% \cs{expandafter}, and the expansion is passed to the function as a +% \tn{expandafter}, and the expansion is passed to the function as a % braced token list. Note that if the original argument is a braced % token list then only the first token in that list is expanded. -% In general, using \texttt{V} should be preferred to using +% In general, using \texttt{V} should be preferred to using % \texttt{o} for simple variable retrieval. % \item[f] Almost the same as the |x| type except here the token list % is expanded fully until the first unexpandable token is found and @@ -562,13 +562,13 @@ % \end{description} % % \subsection{Simpler means better} -% +% % Anyone who programs in \TeX{} is frustratingly familiar with the % problem of arranging that arguments to functions are suitably expanded % before the function is called. To illustrate how expansion control % can bring instant relief to this problem we shall consider two % examples copied from \texttt{latex.ltx}. -% +% % \begin{verbatim} % \global\expandafter\let % \csname\cf@encoding \string#1\expandafter\endcsname @@ -584,19 +584,19 @@ % encoding |?|. The result is a mess of interwoven |\expandafter| % and |\csname| beloved of all \TeX{} programmers, and the code is % essentially unreadable. -% +% % Using the conventions and functionality outlined here, the task would % be achieved with code such as this: % \begin{verbatim} -% \cs_gset_eq:cc +% \cs_gset_eq:cc % { \cf@encoding \token_to_str:N #1 } { ? \token_to_str:N #1 } % \end{verbatim} % The command |\cs_gset_eq:cc| is a global~|\let| that generates % command names out of both of its arguments before making the % definition. This produces code that is far more readable and more % likely to be correct first time. (\cs{token_to_str:N} is the \LaTeX3 -% name for \cs{string}.) -% +% name for \tn{string}.) +% % Here is the second example. % \begin{verbatim} % \expandafter @@ -613,7 +613,7 @@ % and a token whose name comes from~`|sym#3|'. Then the function~|\in@| % is called and this tests if its first argument occurs in the token list % of its second argument. -% +% % Again we can improve enormously on the code. First we shall rename % the function~|\in@| according to our conventions. A function such as % this but taking two normal \enquote{\texttt{n}} arguments might reasonably be @@ -626,20 +626,20 @@ % Note that, in addition to the lack of |\expandafter|, the space after % the~|}| will be 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 % with a range of argument forms, and similarly it is expected that % extension packages providing new functions will make them available in % the all the commonly needed forms. -% +% % However, there will be occasions where it is necessary to construct a % new such variant form; therefore the expansion module provides a % straightforward mechanism for the creation of functions with any % required argument type, starting from a function that takes \enquote{normal} % \TeX{} undelimited arguments. -% +% % To illustrate this let us suppose you have a \enquote{base function} % |\demo_cmd:Nnn| that takes three normal arguments, and that you need % to construct the variant |\demo_cmd:cnx|, for which the first argument @@ -648,7 +648,7 @@ % |\demo_cmd:Nnn|. % To produce the variant form from the base form, simply use this: % \begin{verbatim} -% \cs_generate_variant:Nn \demo_cmd:Nnn { cnx } +% \cs_generate_variant:Nn \demo_cmd:Nnn { cnx } % \end{verbatim} % This defines the variant form so that you can then write, for example: % \begin{verbatim} @@ -659,7 +659,7 @@ % \def \tempa {{pq}}% % \edef \tempb {\rst \xyz}% % \expandafter -% \demo@cmd:nnn +% \demo@cmd:nnn % \csname abc% % \expandafter % \expandafter @@ -672,7 +672,7 @@ % \tempb % }% % \end{verbatim} -% +% % Another example: you may wish to declare a function % |\demo_cmd_b:xcxcx|, a variant of an existing function % |\demo_cmd_b:nnnnn|, that fully @@ -682,37 +682,37 @@ % \begin{verbatim} % \cs_generate_variant:Nn \demo_cmd_b:nnnnn { xcxcx } % \end{verbatim} -% -% This extension mechanism is written so that if the same new form of +% +% 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. -% +% % \section{The distribution} -% -% At present, the \pkg{expl3} modules are designed to be loaded on top +% +% 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. -% +% % \begin{bfseries} -% While \pkg{expl3} is still experimental, the bundle is now regarded -% as broadly stable. 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 +% While \pkg{expl3} is still experimental, the bundle is now regarded +% as broadly stable. 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}. % \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 +% 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: % \begin{verbatim} % \RequirePackage{expl3} -% \end{verbatim} +% \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}{ @@ -728,7 +728,7 @@ % \explpkg{l3coffins}{ % Augmented box constructs for alignment operations. % } -% \explpkg{l3expan}{ +% \explpkg{l3expan}{ % This is the argument expansion module discussed earlier in this % document. % } @@ -749,19 +749,19 @@ % messages to be filtered (higher-level interface for filtering % to be written!). % } -% \explpkg{l3names}{ +% \explpkg{l3names}{ % This sets up the basic naming scheme and renames all -% the \TeX{} primitives. +% the \TeX{} primitives. % } % \explpkg{l3prg}{ % Program control structures such as boolean data type |bool|, generic -% do-while loops, case-switches, sorting routines and stepwise loops. +% do-while loops, case-switches, sorting routines and stepwise loops. % } % \explpkg{l3prop}{ % This implements the data-type for \enquote{property lists} that are used, in % particular, for storing key/value pairs. % } -% \explpkg{l3quark}{ +% \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 % infinite recursion; they do however have many uses, \emph{e.g.}~as @@ -772,7 +772,7 @@ % } % \explpkg{l3skip}{ % Implements the \enquote{rubber length} datatype \texttt{skip} and the -% \enquote{rigid length} datatype |dim|. +% \enquote{rigid length} datatype |dim|. % } % \explpkg{l3tl}{ % This implements a basic data-type, called a \textit{token-list @@ -789,32 +789,32 @@ % \section{Moving from \LaTeXe{} to \LaTeX3} % % To help programmers to use \LaTeX3 code in existing \LaTeXe{} package, -% some short notes on making the change are probably desirable. +% 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. -% +% % \begin{itemize} % \item \pkg{expl3} is mainly focussed on programming. This means that % some areas still require the use of \LaTeXe{} internal macros. -% For example, you may well need \cs{@ifpackageloaded}, as there +% For example, you may well need \tn{@ifpackageloaded}, as there % is currently no native \LaTeX3 package loading module. -% \item User level macros should be generated using the mechanism +% \item User level macros should be generated using the mechanism % available in the \pkg{xparse} package, which is available from CTAN % or the \LaTeX3 SVN repository. -% \item At an internal level, most functions should be generated -% \cs{long} (using \cs{cs_new:Npn}) rather than \enquote{short} (using +% \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}). The exceptions are: % \begin{itemize} % \item Functions which take no arguments; -% \item Functions which are used with pre-set arguments which -% therefore cannot be \cs{long}: this is mainly the case with +% \item Functions which are used with pre-set arguments which +% therefore cannot be \tn{long}: this is mainly the case with % auxiliary functions. % \end{itemize} -% \item Where possible, declare all variables and functions (using +% \item Where possible, declare all variables and functions (using % \cs{cs_new:Npn}, \cs{tl_new:N}, etc.) before use. % \item Prefer \enquote{higher-level} functions over \enquote{lower-level}, % where -% possible. So for example use \cs{cs_if_exist:N(TF)} in preference +% possible. So for example use \cs{cs_if_exist:N(TF)} in preference % \cs{if_cs_exist:N}. % \item Use space to make code readable. In general, we recommend % a layout such as: @@ -830,15 +830,15 @@ % |#1|, |#2|, etc. % \item Put different code items on separate lines: readability is % much more useful than compactness. -% \item Use long, descriptive names for functions and variables, +% \item Use long, descriptive names for functions and variables, % and for auxiliary functions use the parent function name plus % |aux|, |aux_i|, |aux_ii| and so on. % \item If in doubt, ask the team via the LaTeX-L list: someone will -% soon get back to you! -% \end{itemize} -% +% soon get back to you! +% \end{itemize} +% % \section{The \LaTeX3 Project} -% +% % Development of \LaTeX3 is carried out by The \LaTeX3 Project. Over time, % the membership of this team has naturally varied. Currently, the members % are @@ -862,32 +862,32 @@ % \item Alan Jeffrey % \item Martin Schr{\"o}der % \end{itemize} -% +% % \begin{thebibliography}{1} -% +% % \bibitem{A-W:K-TB} % Donald E Knuth % \newblock \emph{The \TeX{}book}. % \newblock Addison-Wesley, Reading, Massachusetts, 1984. -% +% % \bibitem{A-W:GMS94} % Goossens, Mittelbach and Samarin. % \newblock \emph{ The \LaTeX{} Companion}. % \newblock Addison-Wesley, Reading, Massachusetts, 1994. -% +% % \bibitem{A-W:LLa94} % Leslie Lamport. % \newblock \emph{\LaTeX{}: A Document Preparation System}. % \newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994. -% +% % \bibitem{tub:MR97-1} % Frank Mittelbach and Chris Rowley. % \newblock \enquote{The \LaTeX3 Project}. -% \newblock \emph{TUGboat}, +% \newblock \emph{TUGboat}, % Vol.\,18, No.\,3, pp.\,195--198, 1997. -% +% % \end{thebibliography} -% +% % \end{documentation} % % \begin{implementation} @@ -897,7 +897,7 @@ % \begin{macrocode} %<*package> % \end{macrocode} -% +% % Load \pkg{etex} as otherwise we are likely to get into trouble % with registers. Some inserts are reserved also as these have to % be from the standard pool. @@ -905,7 +905,7 @@ \RequirePackage{etex} \reserveinserts{32} % \end{macrocode} -% +% % We want \pkg{calc} to allow \LaTeXe{} to do \eTeX{}-like setting (which will % be native in \LaTeX3). % \begin{macrocode} @@ -925,7 +925,7 @@ \ProvidesExplPackage {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription} % \end{macrocode} -% +% % \begin{macro}{\@l@expl@check@declarations@bool} % \begin{macro}{\@l@expl@log@functions@bool} % A couple of package options to be provided. @@ -942,8 +942,8 @@ \ProcessOptions \relax % \end{macrocode} % \end{macro} -% \end{macro} -% +% \end{macro} +% % We already loaded \pkg{l3names} at the beginning of the \texttt{dtx} file. % We now load the base of \LaTeX3, stopping once token list variables are % defined. @@ -959,30 +959,30 @@ % the appropriate definitions. % \begin{macrocode} \ifodd \@l@expl@check@declarations@bool \relax - \cs_new_protected:Npn \tl_check_exists:N #1 - { - \cs_if_exist:NF #1 - { + \cs_new_protected:Npn \tl_check_exists:N #1 + { + \cs_if_exist:NF #1 + { \msg_kernel_error:nnx { check } { non-declared-variable } { \token_to_str:N #1 } - } + } } - \cs_set_protected:Npn \tl_set:Nn #1#2 + \cs_set_protected:Npn \tl_set:Nn #1#2 { \tl_check_exists:N #1 \cs_set_nopar:Npx #1 { \exp_not:n {#2} } } - \cs_set_protected:Npn \tl_set:Nx #1#2 + \cs_set_protected:Npn \tl_set:Nx #1#2 { \tl_check_exists:N #1 \cs_set_nopar:Npx #1 {#2} } - \cs_set_protected:Npn \tl_gset:Nn #1#2 + \cs_set_protected:Npn \tl_gset:Nn #1#2 { \tl_check_exists:N #1 \cs_gset_nopar:Npx #1 { \exp_not:n {#2} } } - \cs_set_protected:Npn \tl_gset:Nx #1#2 + \cs_set_protected:Npn \tl_gset:Nx #1#2 { \tl_check_exists:N #1 \cs_gset_nopar:Npx #1 {#2} @@ -1001,8 +1001,8 @@ } \fi % \end{macrocode} -%\end{macro} -% +% \end{macro} +% % The rest of the code can now be loaded. % \begin{macrocode} \RequirePackage{ @@ -1015,7 +1015,7 @@ l3prop, l3msg, l3io, - l3file, + l3file, l3skip, l3keys, l3fp, @@ -1025,12 +1025,7 @@ l3luatex } % \end{macrocode} -% -% Depreciated, but loaded for the moment. -% \begin{macrocode} -\RequirePackage{l3toks} -% \end{macrocode} -% +% % The error message for variables cannot be created before now: this means that % \pkg{expl3} itself may cause some odd errors. % \begin{macrocode} @@ -1038,15 +1033,15 @@ { \msg_kernel_new:nnnn { check } { non-declared-variable } { The~variable~#1~has~not~been~declared~\msg_line_context:. } - { + { Checking~is~active,~and~you~have~tried~do~so~something~like: \\ \ \ \tl_set:Nn #1 ~ \iow_char:N \{ ~ ... ~ \iow_char:N \} \\ without~first~having: \\ - \ \ \tl_new:N #1 \\ - \\ + \ \ \tl_new:N #1 \\ + \\ LaTeX~will~create~the~variable~and~continue. - } + } } % \end{macrocode} % @@ -1054,7 +1049,7 @@ % These are redefined here to reduce unnecessary work when switching. % The definition for \cs{ExplSyntaxOff} copies the code from earlier, % so that category codes are restored. -% \begin{macrocode} +% \begin{macrocode} \cs_set_protected_nopar:Npn \ExplSyntaxOn { \bool_if:NF \l_expl_status_bool @@ -1083,7 +1078,7 @@ \char_set_catcode_math_superscript:n { 94 } % circumflex \char_set_catcode_letter:n { 95 } % underscore \char_set_catcode_other:n { 124 } % pipe - \char_set_catcode_space:n { 126 } % tilde + \char_set_catcode_space:n { 126 } % tilde \tex_endlinechar:D = 32 \scan_stop: \bool_set_true:N \l_expl_status_bool } @@ -1094,11 +1089,11 @@ } % \end{macrocode} % \end{macro} -% +% % \begin{macrocode} % % \end{macrocode} % % \end{implementation} -% +% % \PrintIndex -- cgit v1.2.3