path: root/Master/texmf-dist/source/latex/expl3/expl3.dtx

% \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 2156 2011-02-17 15:40:23Z will $
       {L3 Experimental code bundle wrapper}%
%\iffalse
%<*driver>
%\fi
\ProvidesFile{\filename.\filenameext}
  [\filedate\space v\fileversion\space\filedescription]
%\iffalse
\documentclass[full]{l3doc}
\begin{document}
  \DocInput{expl3.dtx}
\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{The \textsf{expl3} package and \LaTeX3 programming^^A
%   \thanks{This file has version number \fileversion, last
%         revised \filedate.}}
% \author{\Team}
% \date{\filedate}
%
% \maketitle
%
% \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,
%   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. Instead, it is intended that
% such features will be built on top of the conventions described here.
%
% This document is an introduction to the ideas behind the \pkg{expl3}
% programming interface. For the complete documentation of the programming
% layer provided by the \LaTeX3 Project, see the accompanying \texttt{source3}
% document.
%
% \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 
% control \TeX.  A key part of this work is to ensure that everything
% 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.  
% 
% 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 
%   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
%   `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 
%   (e.g.~\cs{box} or \cs{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 \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}
% 
% The last layer is covered by the conventions described in this 
% doucment, which describes a system aimed at providing a suitable 
% basis for coding \LaTeX3. 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}
% 
% \LaTeX3 does not use \texttt{@} as a `letter' for defining
% internal macros.  Instead, the symbols \texttt{_} and \texttt{:}
% are used in internal macro names to provide structure. In
% contrast to the plain \TeX\ format and the \LaTeXe\ kernel, these
% extra letters are used only between parts of a macro name (no
% strange vowel replacement).
%
% While \TeX\ is actually a macro processor, by
% convention for the \pkg{expl3} programming language we distinguish between
% \emph{functions} and \emph{variables}. Functions can have arguments and they
% are either expanded or executed.  Variables can be assigned values and they
% are used in arguments to functions; they are not used directly but are
% manipulated by functions (including getting and setting functions).
% Functions and variables with a related functionality (for example accessing
% counters, or manipulating token lists, etc.)\ are collected together into a
% \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.
%\begin{quote}
%  \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 
%    register).\\
%  \cs{c_empty_toks} is the constant~(|c_|) token register 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 
% 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.
% 
% \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}
%  |\|\m{module}|_|\m{description}|:|\m{arg-spec}
%\end{quote}
% while a variable will have (up to) four distinct parts to its name:
%\begin{quote}
%  |\|\m{scope}|_|\m{module}|_|\m{description}|_|\m{type}
%\end{quote}
%
% The syntax of all names contains
% \begin{quote}
%   \m{module} and \m{description}
% \end{quote}
% these both give information about the command.
% 
% 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 `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 \m{description}
% to mark the function as `globally acting', e.g., \cs{int_set:Nn} is
% a local operation while \cs{int_gset:Nn} is a global operation. This
% of course goes hand in hand with when to use \cs{l_} and \cs{g_}
% variable prefixes.
%
%\subsubsection{Variables: scope and type}
% 
% The \m{scope} part of the name describes how the variable can be
% 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 
%    changed);
%  \item[g] variables whose value should only be set globally;
%  \item[l] variables whose value should only be set locally.
%\end{arg-description}
% 
% The \m{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[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[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 (the \LaTeX3 implementation does
%    not use \cs{iftrue} or \cs{iffalse}).
%\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.
% 
% The name `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). \LaTeX3 retains the name `toks' 
% for the later, and adopts the name `token list variables' (tl vars)
% for macros used to store tokens.
% 
%\subsubsection{Variables: guidance}
% 
% Although \TeX\ provides token registers for certain programming
% tasks, \LaTeX3 is written so that token list variables can be used
% for all stored lists of tokens. The \cs{toks_\ldots} functions are
% therefore for internal use within \LaTeX3 and for supporting
% \LaTeXe, and should not be needed in new \LaTeX3-based code.
% 
% 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
% easier to create comma lists `by hand' as they can be typed
% in directly. User input often takes the form of a comma separated
% list and so there are many cases where this is the obvious
% data type to use. On the other hand, sequences use special internal
% tokens to separate entries. This means that they can be used to
% contain material that comma lists cannot (such as items that may
% themselves contain commas!). In general, comma lists should be
% preferred for creating fixed lists inside programs and for
% 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 
% 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 
%  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 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 \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 letters,
% each denoting one argument of the function. The letter, including
% its case, conveys information about the type of argument required.
%
% 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.  Programmers outside
%    the kernel team should not use these functions!
%  \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. However, programmers are
% 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 prefixe
% \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 
% 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 "
% \end{quote}
% we will not get the value of the variable pushed onto the stack,
% 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.} 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 arg-spec part of the function to
% mark the desired behaviour. 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" (the second argument) 
% is for `retrieve the value of the variable' 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| \ldots |\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_seq } \l_tmpa_tl"
%    \end{quote}
%    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 
%    converted to their content. So the preceding examples are also
%    equivalent to
%    \begin{quote}
%     "\tl_new:N \g_file_seq_name_tl" \\
%     "\tl_gset:Nn \g_file_seq_name_tl { g_file_name_seq }" \\
%     "\seq_gpush:cV { \g_file_seq_name_tl } \l_tmpa_tl".
%    \end{quote}
%    (Token list variables are expandable and do not require an
%    accessor function. Other variable types require the appropriate
%    \cs{<var>_use:N} functions to be used in this context.)
%  \item[V]  Value of a variable.\\
%    This means that the contents of the register in question is used as the
%    argument, be it an integer, a length-type register, a token list variable
%    or similar. The value is passed 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 passes the value of the
%    resulting register to the function.
%  \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
%    \cs{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 
%    \texttt{o} for simple variable retrival.
%  \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}
% 
% 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 \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}.)
% 
% 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}
% 
% 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{The distribution}
% 
% 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 
%  \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 
%  of a number of modules, most of which are loaded by including the
%  line:
%\begin{verbatim}
%  \RequirePackage{expl3}
%\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}{
% 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{l3clist}{
% Methods for manipulating comma-separated token lists.
% }
% \explpkg{l3expan}{ 
% This is the argument expansion module discussed earlier in this
% document.
% }
% \explpkg{l3int}{
% This implements the integer data-type \texttt{int}.
% }
% \explpkg{l3intexpr}{
% For carring out integer expression calculations and comparisons, 
% whether the input is stored in \texttt{int}, \texttt{tl} or
% other variable types, or is given literally.
% }
% \explpkg{l3io}{
% A module providing low level input and output functions.
% }
% \explpkg{l3keyval}{
% Low-level implementation for processing lists of the form
% \texttt{\{ key1=val1 , key2=val2 \}}.
% }
% \explpkg{l3keys}{
% Higher-level implementation of key--value methods: intended to work
% as a \LaTeX3 version of \pkg{xkeyval}/\pkg{kvoptions}, although
% with input syntax more like that of \pkg{pgfkeys}.
% }
% \explpkg{l3msg}{
% Communicating with the user: includes low-level hooks to allow
% messages to be filtered (higher-level interface for filtering
% to be written!).
% }
% \explpkg{l3names}{ 
% This sets up the basic naming scheme and renames all
% 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. 
% }
% \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, e.g.~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.
% }
%\end{description}
%
%\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. 
% 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
%    is currently no native \LaTeX3 package loading module.
%  \item User level macros should be generated using the mechansim 
%    availble 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 `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
%        auxiliary functions.
%    \end{itemize}
%  \item Where possible, declare all variables and functions (using 
%    \cs{cs_new:Npn}, \cs{tl_new:N}, etc.) before use.
%  \item Prefer `higher-level' functions over `lower-level', where
%    possible. So for example use \cs{cs_if_exist:N(TF)} over 
%    \cs{if_cs_exist:N}.
%  \item Use space to make code readable. In general, we recommend
%    a layout such as:
%    \begin{verbatim}
%      \cs_new:Npn \foo_bar:Nn #1#2 {
%        \cs_if_exist:NTF #1 {
%          \foo_bar_aux_i:n {#2}
%        }{
%          \foo_bar_aux_ii:nn {#2} { literal }
%        }
%      }
%    \end{verbatim}
%    where spaces are used around |{| and |}| except for isolated
%    |#1|, |#2|, etc.
%  \item Put different code items on separate lines: readablity is
%    much more useful than compactness.
%  \item Use long, descriptive names for functions and variables, 
%    and for auxilliary 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} 
% 
% \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}
%    
% 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.
%    \begin{macrocode}
\RequirePackage{etex}
\reserveinserts{32}
%    \end{macrocode}
%    
%\begin{macro}{\@l@expl@check@declarations@bool}
%\begin{macro}{\@l@expl@log@functions@bool}
% A couple of package options to be provided.
% These have to be done by hand as there is no expl3 yet.
%    \begin{macrocode}
\newcommand*\@l@expl@check@declarations@bool{0}
\newcommand*\@l@expl@log@functions@bool{0}
\DeclareOption{check-declarations}{
  \def\@l@expl@check@declarations@bool{1}
}
\DeclareOption{log-functions}{
  \def\@l@expl@log@functions@bool{1}
}
\ProcessOptions\relax
%    \end{macrocode}
%\end{macro}
%\end{macro}    
%
% We already loaded \pkg{l3names} at the beginning of the \texttt{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,
  l3int,
  l3quark,
  l3seq,
  l3toks,
  l3prg,
  l3clist,
  l3token,
  l3prop,
  l3msg,
  l3io,
  l3skip
}
%    \end{macrocode}
% All the rest:
%    \begin{macrocode}
\RequirePackage{
  l3box,
  l3keyval,
  l3keys,
  l3precom,
%  l3calc,
  l3xref,
  l3file, 
  l3fp,
  l3luatex,
  l3font
}
\RequirePackage{calc}
%    \end{macrocode}
%    
%    \begin{macrocode}
\bool_if:nT { \@l@expl@check@declarations@bool } {
  \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: \\
      \c_space_tl \c_space_tl \tl_set:Nn #1 ~
        \iow_char:N \{ ~ ... ~ \iow_char:N \} \\
      without~first~having: \\
      \c_space_tl \c_space_tl \tl_new:N #1  \\ 
      \\ 
      LaTeX~will~create~the~variable~and~continue.
    }  
}
%    \end{macrocode}
%    
%</package>
%
% \end{implementation}
%
% \endinput