summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/expl3/expl3.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-06-09 23:31:15 +0000
committerKarl Berry <karl@freefriends.org>2009-06-09 23:31:15 +0000
commit215b9a864d5829070bdc66ba736986eb72e5143e (patch)
treefe0882c81fc4ec945cee4b512f72eaa21ea5f791 /Master/texmf-dist/source/latex/expl3/expl3.dtx
parentdf90ec06321940c2f066b05e12f1b5ab099105da (diff)
expl3 1407 (9jun09)
git-svn-id: svn://tug.org/texlive/trunk@13686 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/expl3.dtx')
-rw-r--r--Master/texmf-dist/source/latex/expl3/expl3.dtx970
1 files changed, 970 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/expl3.dtx b/Master/texmf-dist/source/latex/expl3/expl3.dtx
new file mode 100644
index 00000000000..a22e1b53417
--- /dev/null
+++ b/Master/texmf-dist/source/latex/expl3/expl3.dtx
@@ -0,0 +1,970 @@
+% \iffalse
+%% File: expl3.dtx Copyright (C) 1990-2009 LaTeX3 project
+%%
+%% It may be distributed and/or modified under the conditions of the
+%% LaTeX Project Public License (LPPL), either version 1.3c of this
+%% license or (at your option) any later version. The latest version
+%% of this license is in the file
+%%
+%% http://www.latex-project.org/lppl.txt
+%%
+%% This file is part of the ``expl3 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.
+%%
+%% -----------------------------------------------------------------------
+%%
+%% The development version of the bundle can be found at
+%%
+%% http://www.latex-project.org/svnroot/experimental/trunk/
+
+%%
+%% for those people who are interested.
+%%
+%%%%%%%%%%%
+%% NOTE: %%
+%%%%%%%%%%%
+%%
+%% Snapshots taken from the repository represent work in progress and may
+%% not work or may contain conflicting material! We therefore ask
+%% people _not_ to put them into distributions, archives, etc. without
+%% prior consultation with the LaTeX Project Team.
+%%
+%% -----------------------------------------------------------------------
+%
+%<*driver|package>
+\RequirePackage{l3names}
+%</driver|package>
+%\fi
+\GetIdInfo$Id: expl3.dtx 1381 2009-06-01 20:36:02Z joseph $
+ {L3 Experimental code bundle wrapper}%
+%\iffalse
+%<*driver>
+%\fi
+\ProvidesFile{\filename.\filenameext}
+ [\filedate\space v\fileversion\space\filedescription]
+%\iffalse
+\documentclass{l3doc}
+\usepackage{shortvrb,hypdoc}
+\MakeShortVerb{\|}
+\hyphenation{para-meters para-meter}
+% I have found at least 3 other hyphenations of this in various refs,
+% but I did also find this, which is my personal favourite ---chris
+\hyphenation{ignore ignored ignores}
+\begin{document}
+\DocInput{\filename.\filenameext}
+\end{document}
+%</driver>
+% \fi
+%
+% \providecommand\acro[1]{\textsc{\MakeLowercase{#1}}}
+% \providecommand\ie{i.e.,~}
+% \providecommand\eg{e.g.,~}
+% \newenvironment{arg-description}{%
+% \begin{itemize}\def\makelabel##1{\hss\llap{\bfseries##1}}}{\end{itemize}}
+%
+% \title{The \textsf{expl3} package and philosophy\thanks{This file
+% has version number \fileversion, last
+% revised \filedate.}}
+% \author{\Team}
+% \date{\filedate}
+%
+% \maketitle
+%
+% \begin{documentation}
+%
+% \begin{abstract}
+%
+% This paper gives a brief 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.
+%
+% The main features of the system described are:
+% \begin{itemize}
+% \item classification of the macros (or, in \LaTeX{} terminology,
+% commands) into \LaTeX{} functions and \LaTeX{} parameters, and also
+% into modules containing related commands;
+% \item a systematic naming scheme based on these
+% classifications;
+% \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 the \LaTeX3 project.
+% Note that the language is not intended for either
+% document mark-up or style specification.
+%
+% An earlier description of the \LaTeX3 programming language is
+% available from \url{http://www.latex-project.org/papers}.
+% \end{abstract}
+%
+%
+% \section{Introduction}
+%
+% This paper describes the conventions for a \TeX-based programming
+% language which is intended to provide a more consistent and rational
+% environment for the construction of large scale systems, such as
+% \LaTeX, using \TeX{} macros.
+%
+% Variants of this language have been in use by The \LaTeX3 Project Team
+% since around 1990 but the syntax specification to be outlined here
+% should \emph{not} be considered final. This is an experimental
+% language thus many aspects, such as the syntax conventions and naming
+% schemes, may (and probably will) change as more experience is gained
+% with using the language in practice.
+%
+% 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 semantics of the expansion control mechanism and the
+% interface used to define variant forms of functions. The paper also
+% discusses some advantages of the syntax for parameter names.
+%
+% 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
+% (especially when using a reasonably intelligent editor).
+%
+% The final section gives some details of our plans to distribute parts
+% of this system. Although the paper is now a little dated, more general
+% information concerning the work of the \LaTeX3 Project can be found
+% in Ref.~\cite{tub:MR97-1}.
+%
+%
+% \section{Languages and interfaces}
+% \label{sec:langs}
+%
+% 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 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{SGML} 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
+% `natural' when used directly by the author as document mark-up or in
+% macros. Ironically, the ubiquity (and widely recognised
+% superiority) of logical mark-up has meant that such explicit
+% formatting commands are almost never needed in documents or in
+% author-defined macros. Thus they are used almost exclusively by
+% \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 (\eg
+% |\box| or |\special|).
+%
+% \item[Designer interface] This relates a (human) typographic
+% designer's specification for a document to a program that `formats
+% the document'. It should ideally use a declarative language that
+% 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
+% \acro{SGML}-based systems the \acro{DSSSL} language may come to play
+% this role. 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 `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 primitives of \TeX\ (or a
+% successor program).
+% It may also be used to implement the previous
+% two languages `within' \TeX, as in the current \LaTeX\ system.
+% \end{description}
+%
+% Only the last of these three interfaces is covered by this paper,
+% which describes a system aimed at providing a suitable basis for
+% coding large scale projects in \TeX{} (but this should not preclude its
+% use for smaller projects). Its main distinguishing features are
+% summarised here.
+%
+% \begin{itemize}
+% \item A consistent naming scheme for all commands, including \TeX\
+% primitives.
+% \item The classification of commands as \LaTeX{} functions or \LaTeX{}
+% parameters, and also their division into modules according to their
+% 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, property lists.
+% \item A \TeX{} programming environment in which, for example, all
+% white space is ignored.
+% \end{itemize}
+%
+% \section{The naming scheme}
+% \label{sec:scheme}
+%
+% The naming conventions for this programming language distinguish
+% between \textit{functions} and \textit{parameters}. Functions can have
+% arguments and they are executed. Parameters can be assigned values
+% and they are used in arguments to functions; they are not directly
+% executed but are manipulated by mutator and accessor functions.
+% Functions and parameters with a related functionality (for example
+% accessing counters, or manipulating token-lists, etc.)\ are collected
+% together into a
+% \textit{module}.
+%
+%
+% Note that all these terms are only \LaTeX{} terminology and are not,
+% for example, intended to indicate that the commands have these
+% properties when considered in the context of basic \TeX{} or in any
+% more general programming context.
+%
+%
+% \subsection{Examples}
+% \label{sec:ex}
+%
+% Before giving the details of the naming scheme, here are a few typical
+% examples to indicate the flavour of the scheme; first some parameter
+% names.
+% \begin{quote}
+% |\l_tmpa_box| is a local parameter (hence the~|l_| prefix)
+% corresponding to a box register.\\
+% |\g_tmpa_int| is a global parameter (hence the~|g_| prefix)
+% corresponding to an integer register (\ie a \TeX{} count register).\\
+% |\c_empty_toks|
+% is the constant~(|c_|) token register parameter that is for ever empty.
+% \end{quote}
+% Now here is an example of a typical function name.
+%
+% |\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 `names'
+% the stack parameter: such single-token arguments are denoted~|N|.
+% The second argument is a normal \TeX\ `undelimited argument', which
+% may either be a single token or a balanced, brace-delimited token
+% list (which we shall here call a \textit{braced token list}): the~|n|
+% denotes such a `normal' argument form. The name of the function
+% indicates it belongs to the |seq| module.
+%
+%^^A |\seq_push:cn| would be similar to the above, but in this case the~|c|
+%^^A means that the stack-name is specified in the first argument by a
+%^^A token list that expands, using |\csname...|, to a control sequence that
+%^^A is the \emph{name} of the stack parameter.
+%^^A
+%^^A \noindent
+%^^A The names of these two functions also indicate that they are in the
+%^^A module called |seq|.
+%
+%
+% \subsection{Formal syntax of the conventions}
+% \label{sec:namesyn}
+%
+% We shall now look in more detail at the syntax of these names.\\
+% The syntax of parameter names is as follows:
+% \begin{quote}
+% |\|\m{access}|_|\m{module}|_|\m{description}|_|\m{type}
+% \end{quote}
+% The syntax of function names is as follows:
+% \begin{quote}
+% |\|\m{module}|_|\m{description}|:|\m{arg-spec}
+% \end{quote}
+%
+%
+% \subsection{Modules and descriptions}
+% \label{sec:modules}
+%
+% The syntax of all names contains
+% \begin{quote}
+% \m{module} and \m{description}:
+% \end{quote}
+% these both give information about the command.
+%
+% A \textit{module} is a collection of
+% closely related functions and parameters.
+% 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.
+%
+% The \textit{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.
+%
+% As a semi-formalized concept the letter |g| is sometimes used to
+% prefix certain parts of the \m{description}
+% to mark the function as ``globally acting'', e.g., |\int_set:Nn| is
+% a local operation while |\int_gset:Nn| is a global operation. This
+% of course goes hand in hand with when to use |\l_| and |\g_|
+% variable prefixes.
+%
+% \subsection{Parameters: access and type}
+% \label{sec:parms}
+%
+% The \m{access} part of the name describes how the parameter can be
+% accessed. Parameters are primarily classified as local, global or
+% constant (there are further, more technical, classes). This
+% \textit{access} type appears as a code at the beginning of the name;
+% the codes used include:
+% \begin{arg-description}
+% \item[c]
+% constants (global parameters whose value should not be changed);
+% \item[g]
+% parameters whose value should only be set globally;
+% \item[l]
+% parameters whose value should only be set locally.
+% \end{arg-description}
+%
+% The \m{type} will normally (except when introducing a new data-type)
+% be in the list of available \textit{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.
+%
+% Here are some typical data-type names:
+% \begin{description}
+% \item[int] integer-valued count register;
+% \item[tl] token list variables: placeholders for token lists;
+% \item[toks] token register;
+% \item[box] box register;
+% \item[skip] `rubber' lengths;
+% \item[dim] `rigid' lengths;
+% \item[num] A `fake' integer type using only macros. Useful for
+% setting up allocation routines;
+% \item[seq] `sequence': a data-type used to implement lists
+% (with access at both ends) and stacks;
+% \item[prop] property list;
+% \item[clist] comma separated list;
+% \item[stream] an input or output stream (for reading from or writing to, respectively);
+% \item[bool] either true or false.
+% \end{description}
+% When the \m{type} and \m{module} are identical (as often happens in
+% the more basic modules) the \m{module} part is often omitted for
+% aesthetic reasons.
+%
+%
+% \subsection{Functions: basic argument specifications}
+% \label{sec:args}
+%
+% Function names end with an \m{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 \m{arg-spec} consists of a (possibly empty) list of characters,
+% each denoting one argument of the function. It is important to
+% understand that `argument' here refers to the effective argument of
+% the \LaTeX{} function, not to an argument at the \TeX-level. Indeed,
+% the top level \TeX\ macro that has this name typically has no
+% arguments. This is an extension of the existing \LaTeX\ convention
+% where one says that |\section| has an optional argument and a
+% mandatory argument, whereas the \TeX\ macro |\section| actually has
+% zero parameters at the \TeX\ level, it merely calls an internal \LaTeX\
+% command which in turn calls others that look ahead for star forms and
+% optional arguments.
+%
+% All functions have a base form with arguments using one of the
+% following argument specifiers.
+% \begin{arg-description}
+% \item[n] Unexpanded token or braced token list.\\
+% This is a standard \TeX\ undelimited macro argument.
+% \item[N] Single token (unlike~|n|, the argument must \emph{not} be
+% surrounded by braces).\\
+% A typical example of a command taking an~|N|
+% argument is~|\cs_set|, in which the command being defined must be
+% unbraced.
+% \item[p] Primitive \TeX\ parameter specification.\\
+% This can be something simple like~|#1#2#3|, but may use arbitrary
+% delimited argument syntax such as: |#1,#2\q_stop#3|. This is used
+% when defining functions.
+% \item[T,F]
+% These are special cases of~|n| arguments, used for the
+% true and false code in conditional commands.
+% \end{arg-description}
+% There are two other specifiers with more general meanings:
+% \begin{arg-description}
+% \item[D] This means: \textbf{Do not
+% use}. This special case is used
+% for \TeX\ primitives and other commands that are provided for use
+% only while bootstrapping the \LaTeX\ kernel. If the \TeX\ primitive
+% needs to be used in other contexts it will be given an alternative,
+% more appropriate, name with a useful argument specification. The
+% argument syntax of these is often weird, in the sense described next.
+% \item[w] This means that the argument syntax is `weird' in that it
+% does not follow any standard rule. It is used for functions with
+% arguments that take non standard forms: examples are \TeX-level
+% 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 surrounding braces can be omitted in nearly all
+% situations---functions that force the use of braces even for single
+% token arguments are explicitly mentioned. For example, "\seq_gpush:Nn"
+% is a function that takes two arguments, the first is a single token
+% (the sequence) and the second may consist of several tokens surrounded
+% by braces.
+%
+% This concept of argument specification makes it easy to read the code
+% and should be followed when defining new functions.
+%
+%
+%
+%
+% \section{Expansion control}
+% \label{sec:exp}
+%
+% 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_io_file_name_seq| to keep track of them (|io| is the
+% input-output file module). 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_io_file_name_seq" \\
+% " {#1}"
+% \end{quote}
+% where |#1| is the filename. In other words, this operation would
+% push the file name as is.
+%
+% However, we might face a situation where
+% the filename is stored in a register of some sort, say
+% |\l_io_curr_file_tl|. In this case we want to retrieve the value of
+% the register. If we simply use
+% \begin{quote}
+% "\seq_gpush:Nn" \\
+% " \g_io_file_name_seq" \\
+% " \l_io_curr_file_tl "
+% \end{quote}
+% we will not get the value of the register pushed onto the stack,
+% only the register name itself. Instead a suitable number of
+% "\exp_after:wN" would be necessary (together with extra braces) to
+% change the order of execution, i.e.
+% \begin{quote}
+% "\exp_after:wN" \\
+% " \seq_gpush:Nn" \\
+% "\exp_after:wN" \\
+% " \g_io_file_name_seq" \\
+% "\exp_after:wN" \\
+% " {\l_io_curr_file_tl}"
+% \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 exactly how a storage bin acts in order to get
+% the correct number 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
+% just uses different letters in the argument part of the function to
+% mark the desired behavior. In the above example one would write
+% \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" is for ``retrieve the
+% value of the register'' (the second argument) before passing it to
+% the base function.
+%
+%
+% The following letters can be used to denote special treatment of
+% arguments before passing it to the base function:
+% \begin{description}
+% \item[c] Character string used as a command name.\\ The argument (a
+% token or braced token list) must, when fully expanded, produce a
+% sequence of characters which is then used to construct a command
+% name (via~|\csname|, |\endcsname|). This command name is the
+% single token that is passed to the function as the argument. Hence
+% \begin{quote}
+% "\seq_gpush:cV {g_file_name_stack} \l_tmpa_tl"
+% \end{quote}
+% is equivalent to
+% \begin{quote}
+% "\seq_gpush:NV \g_file_name_stack \l_tmpa_tl".
+% \end{quote}
+%
+% \item[V] Value of a register.\\
+% This means that the register in question is returned, be it an
+% integer, a length type register, a macro storage register or
+% similar. The value is returned to the function as a braced token list.
+%
+% \item[v] Value of a register, constructed from a character string
+% used as a command name.\\
+% This is a combination of |c| and |V| which first constructs a
+% control sequence from the argument and then returns the value.
+%
+% \item[x] Fully-expanded token or braced token list.\\
+% This means that the argument is expanded as in the replacement
+% 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.\\
+% This means that the argument is expanded one level, as by
+% |\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.
+%
+% \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
+% 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
+% expand the next argument.
+% \end{description}
+%
+%
+% \subsection{Simpler means better}
+% \label{sec;simpler}
+%
+% 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
+% \csname ?\string#1\endcsname
+% \end{verbatim}
+% This first piece of code is in essence simply a global |\let| whose
+% two arguments firstly have to be constructed before |\let| is
+% executed. The |#1| is a control sequence name such as
+% |\textcurrency|. The token to be defined is obtained by
+% concatenating the characters of the current font encoding stored in
+% |\cf@encoding|, which has to be fully expanded, and the name of the
+% symbol. The second token is the same except it uses the default
+% 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 {\cf@encoding \string #1}
+% {?\string #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.
+%
+% Here is the second example.
+% \begin{verbatim}
+% \expandafter
+% \in@
+% \csname sym#3%
+% \expandafter
+% \endcsname
+% \expandafter
+% {%
+% \group@list}%
+% \end{verbatim}
+% This piece of code is part of the definition of another function. It
+% first produces two things: a token list, by expanding |\group@list| once;
+% 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 `\texttt{n}' arguments might reasonably be
+% named |\seq_test_in:Nn|; thus the variant function we need will be
+% defined with the appropriate argument types and its name will be
+% |\seq_test_in:cV|. Now this code fragment will be simply:
+% \begin{verbatim}
+% \seq_test_in:cV {sym#3} \l_group_seq
+% \end{verbatim}
+% 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}
+% \label{sec:newfunc}
+%
+% 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 `normal'
+% \TeX\ undelimited arguments.
+%
+% To illustrate this let us suppose you have a `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
+% is used to construct the \emph{name} of a command, whilst the third
+% argument must be fully expanded before being passed to
+% |\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}
+% \end{verbatim}
+% This defines the variant form so that you can then write, for example:
+% \begin{verbatim}
+% \demo_cmd:cnx {abc} {pq} {\rst \xyz }
+% \end{verbatim}
+% rather than \ldots\ well, something like this!
+% \begin{verbatim}
+% \def \tempa {{pq}}%
+% \edef \tempb {\rst \xyz}%
+% \expandafter
+% \demo@cmd:nnn
+% \csname abc%
+% \expandafter
+% \expandafter
+% \expandafter
+% \endcsname
+% \expandafter
+% \tempa
+% \expandafter
+% {%
+% \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
+% expands arguments 1,~3 and~5, and produces commands to pass as
+% arguments 2 and~4 using~|\csname|.
+% The definition you need is simply
+% \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
+% some existing command is implemented by two extension packages then the
+% two definitions will be identical and thus no conflict will occur.
+%
+%
+% \section{Parameter assignments and accessor functions}
+% \label{sec:access}
+%
+% \subsection{Checking assignments}
+% \label{sec:check}
+%
+% One of the advantages of having a consistent scheme is that the system
+% can provide more extensive error-checking and debugging facilities.
+% For example, an accessor function that makes a \emph{global}
+% assignment of a value to a parameter can check that it is not passed
+% the name of a \emph{local} parameter as that argument: it does this by
+% checking that the name starts with~|\g_|.
+%
+% Such checking is probably too slow for normal use, but the code can
+% have hooks built in that allow a format to be made in which all
+% functions perform this kind of check.
+%
+% A typical section of the source^^A
+% \footnote{This code uses the \textsf{docstrip}
+% system described in~\cite{A-W:GMS94}, Section~14.3.}
+% for such code might look like this
+% (recall that all white space is ignored):
+%
+% \begin{verbatim}
+% %<*!check>
+% \cs_new_eq:NN
+% \toks_gset:Nn \tex_global:D
+% %</!check>
+% %<*check>
+% \cs_new_nopar:Npn
+% \toks_gset:Nn #1
+% {
+% \chk_global:N #1
+% \tex_global:D #1
+% }
+% %</check>
+% \end{verbatim}
+% In the above code the function |\toks_gset:Nn| takes a single
+% token~(|N|) specifying a token register, and globally sets it to the
+% value passed in the second argument.
+%
+% A typical use of it would be:
+% \begin{verbatim}
+% \toks_gset:Nn \g_xxx_toks {<some value>}
+% \end{verbatim}
+% In the normal definition, |\toks_gset:Nn| can be simply~|\let|
+% to~|\global| because the primitive \TeX{} token register does not
+% require any explicit assignment function:
+% this is done by the |%<*!check>| code above.
+%
+% The alternative definition first checks that the argument
+% passed as~|#1| is the name of a global parameter and raises an error
+% if it is not. It does this by taking apart the command name passed
+% as~|#1| and checking that it starts~|\g_|.
+%
+% \subsection{Consistency}
+% \label{sec:cons}
+%
+% The primitive \TeX\ syntax for register assignments has a very minimal
+% syntax and, apart from box functions, there are no explicit functions
+% for assigning values to these registers.
+%
+% This makes it impossible to implement alternative data-types with a
+% syntax that is both consistent and at all similar to the syntax for
+% the primitives; moreover, it encourages a coding style that is very
+% error prone.
+%
+% As in the |\toks_gset:Nn| example given above, all \LaTeX\ data-types
+% are provided with explicit functions for assignment and for use, even
+% when these have essentially empty definitions. This allows for better
+% error-checking as described above; it also allows the construction of
+% further data-types with a similar interface, even when the
+% implementation of the associated functions is very complex.
+%
+% For example, the `fake-integer' (\texttt{num}) data-type mentioned
+% above will appear at the \LaTeX{} programming level to be exactly like
+% the data-type based on primitive count registers; however, internally
+% it makes no use of count registers. Typical functions in this module
+% are illustrated here.
+%
+% \begin{verbatim}
+% \num_new:N \l_tmpa_num
+% \end{verbatim}
+% This declares the local parameter |\l_example_num| as a fake-counter.
+%
+% \begin{verbatim}
+% \num_add:Nn \l_example_num \c_thirty_two
+% \end{verbatim}
+% This increments the value of this fake-counter by 32.
+%
+%
+% \section{The experimental distribution}
+% \label{sec:dist}
+%
+% The initial implementations of a \LaTeX\ programming language using
+% this kind of syntax remain unreleased (and not completely functional);
+% they partly pre-date \LaTeXe! The planned distribution will provide a
+% subset of the functionality of those implementations, in the form of
+% packages to be used on top of \LaTeXe.
+%
+% The intention is to allow experienced \TeX\ programmers to experiment
+% with the system and to comment on the interface. This means that
+% \textbf{\itshape the interface will change}. No part of this system,
+% including the name of anything, should be relied upon as being
+% available in a later release. Please do \emph{experiment} with these
+% packages, but do \emph{not} use them for code that you expect to keep
+% unchanged over a long period.
+%
+% In view of the intended experimental use for this distribution we
+% shall, in the first instance, produce only a few modules for use with
+% \LaTeXe. These will set up the conventions and the basic functionality
+% of, for example, the expansion mechanism; they will also implement some
+% of the basic programming constructs, such as token-lists and sequences.
+% They are intended only to give a flavour of the code: the full \LaTeX3
+% kernel will provide a very rich set of programming constructs so that
+% packages can efficiently share code, in contrast with the situation in
+% the current \LaTeX\ where every large package must implement its own
+% version of queues, stacks, etc., as necessary.
+%
+% At time of writing the \textsf{expl3} bundle consists of the
+% following modules.
+%
+% This distribution will also contain the \LaTeX\ source for the latest
+% version of this document, a docstrip install file and three small test
+% files.
+%
+% \begin{description}
+% \providecommand\explpkg[2]{\item[#1]#2}
+% \explpkg{l3basics}{
+% This contains the basic definition modules used
+% by the other packages.
+% }
+% \explpkg{l3box}{
+% Primitives for dealing with boxes.
+% }
+% \explpkg{l3calc}{
+% A re-implementation of the \LaTeXe\ package \pkg{calc} package in
+% \pkg{expl3} that provides extended methods for numeric and dimensional
+% calculations and assignments.
+% }
+% \explpkg{l3chk}{
+% A module that provides functionality comparable to
+% \LaTeX's \cmd{\newcommand} and \cmd{\renewcommand}, and also the
+% extra level of
+% checking for ensure internal consistency in the code.
+% }
+% \explpkg{l3clist}{
+% Methods for manipulating comma-separated token lists.
+% }
+% \explpkg{l3expan}{
+% This is the argument expansion module discussed above.
+% }
+% \explpkg{l3int}{
+% This implements the integer data-type \texttt{int}.
+% }
+% \explpkg{l3io}{
+% A module providing low level input and output functions.
+% }
+% \explpkg{l3keyval}{
+% A re-implementation of the \LaTeXe\ package \pkg{keyval};
+% provides low-level macros for dealing with lists of the form
+% \texttt{\{ key1=val1 , key2=val2 \}}.
+% }
+% \explpkg{l3messages/l3msg}{
+% Communicating with the user.
+% }
+% \explpkg{l3names}{
+% This sets up the basic naming scheme and renames all
+% the \TeX\ primitives. If it is loaded with the option
+% \texttt{[removeoldnames]} then the old primitive names such as~\cmd{\box}
+% become \emph{undefined} and are thus available for user
+% definition. Caution: use of this option will certainly break existing
+% \TeX\ code!
+% }
+% \explpkg{l3num}{
+% This implements the `fake integer' datatype \texttt{num}.
+% }
+% \explpkg{l3precom}{
+% A `pre-compilation' module that provides functions dealing with pointer
+% creation and handling, and using external files to record the state of the current
+% definitions.
+% }
+% \explpkg{l3prg}{
+% Program control structures such as boolean data type |bool|, generic
+% do-while loops, case-switches, sorting routines and stepwise loops.
+% }
+% \explpkg{l3prop}{
+% This implements the data-type for `property lists' that are used, in
+% particular, for storing key/value pairs.
+% }
+% \explpkg{l3quark}{
+% A `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, \eg as
+% special markers and delimiters within code.
+% }
+% \explpkg{l3seq}{
+% This implements data-types such as queues and stacks.
+% }
+% \explpkg{l3skip}{
+% Implements the `rubber length' datatype \texttt{skip} and the
+% `rigid length' datatype |dim|.
+% }
+% \explpkg{l3tl}{
+% This implements a basic data-type, called a \textit{token-list
+% variable} (|tl var.|), used for storing named token lists: these are
+% essentially \TeX{} macros with no arguments.
+% }
+% \explpkg{l3token}{
+% Analysing token lists and token streams, including peeking ahead to
+% see what's coming next and inspecting tokens to detect which kind
+% they are.
+% }
+% \explpkg{l3toks}{
+% A data-type corresponding to \TeX's primitive token registers.
+% }
+% \explpkg{l3xref}{
+% Data structure for low-level document cross-referencing. This
+% provided the foundation for Heiko Oberdiek's \pkg{zref} package.
+% }
+% \end{description}
+%
+% \begin{thebibliography}{1}
+%
+% \bibitem{A-W:K-TB}
+% Donald E Knuth
+% \newblock {\em The {\TeX}book}.
+% \newblock Addison-Wesley, Reading, Massachusetts, 1984.
+%
+% \bibitem{A-W:GMS94}
+% Goossens, Mittelbach and Samarin.
+% \newblock {\em The {\LaTeX} Companion}.
+% \newblock Addison-Wesley, Reading, Massachusetts, 1994.
+%
+% \bibitem{A-W:LLa94}
+% Leslie Lamport.
+% \newblock {\em {\LaTeX:} A Document Preparation System}.
+% \newblock Addison-Wesley, Reading, Massachusetts, second edition, 1994.
+%
+% \bibitem{tub:MR97-1}
+% Frank Mittelbach and Chris Rowley.
+% \newblock `The {\LaTeX3} Project'.
+% \newblock {\em {TUG}boat},
+% Vol.\,18, No.\,3, pp.\,195--198, 1997.
+%
+% \end{thebibliography}
+%
+% \end{documentation}
+%
+% \begin{implementation}
+%
+% \subsection{\pkg{expl3} implementation}
+%
+% Well, it's not complicated |:)|
+%
+%<*package>
+% \begin{macrocode}
+\ProvidesExplPackage
+ {\filename}{\filedate}{\fileversion}{\filedescription}
+% \end{macrocode}
+%
+% We already loaded \pkg{l3names} at the beginning of the \acro{dtx} file.
+%
+% The \pkg{l3chk} package is omitted since it is only used for conditional
+% processing with full error-checking turned on. Most users will generally
+% not need to do this, and we haven't set it up yet, anyway.
+%
+% Fundamentals:
+% \begin{macrocode}
+\RequirePackage{
+ l3basics,
+ l3expan,
+ l3tl,
+ l3num,
+ l3intexpr,
+ l3quark,
+ l3seq,
+ l3toks,
+ l3int,
+ l3prg,
+ l3clist,
+ l3token,
+ l3io,
+ l3prop,
+ l3msg,
+ l3skip,
+}
+% \end{macrocode}
+% All the rest:
+% \begin{macrocode}
+\RequirePackage{
+ l3box,
+ l3keyval,
+ l3precom,
+ l3calc,
+ l3xref,
+ l3file
+}
+% \end{macrocode}
+%</package>
+%
+% \end{implementation}
+%
+% \endinput