summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/expl3.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-09-16 22:35:41 +0000
committerKarl Berry <karl@freefriends.org>2011-09-16 22:35:41 +0000
commit6d95b4a2c1bbdaea1a3802c822808f476ac5703b (patch)
tree1abf9117bf53f2de53fbcc62c352acc92780365b /Master/texmf-dist/source/latex/l3kernel/expl3.dtx
parentb7f762397f5df2d732326713423e31e1bf91b903 (diff)
l3kernel 2828 (15sep11)
git-svn-id: svn://tug.org/texlive/trunk@23983 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/expl3.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/expl3.dtx397
1 files changed, 196 insertions, 201 deletions
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|package>
%<*driver>
\documentclass[full]{l3doc}
@@ -47,17 +47,17 @@
\end{document}
%</driver>
% \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}
%</package>
% \end{macrocode}
%
% \end{implementation}
-%
+%
% \PrintIndex