summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/expl3/expl3.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/expl3.dtx')
-rw-r--r--Master/texmf-dist/source/latex/expl3/expl3.dtx1013
1 files changed, 0 insertions, 1013 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/expl3.dtx b/Master/texmf-dist/source/latex/expl3/expl3.dtx
deleted file mode 100644
index 0ff399f6404..00000000000
--- a/Master/texmf-dist/source/latex/expl3/expl3.dtx
+++ /dev/null
@@ -1,1013 +0,0 @@
-% \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 2222 2011-04-09 12:47:12Z 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}
-%
-% Separate functions are provided to assign data to local and global
-% variables; for example, "\tl_set:Nn" and "\tl_gset:Nn" respectively
-% set the value of a local or global `token list' variable.
-% Note that it is a poor \TeX\ practise to intermix local and global
-% assignments to a variable; otherwise you risk exhausting the save stack.
-% \unskip\footnote{See the \TeX book, p.\,301, for further information.}
-%
-% 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}
-%
-%\begin{macro}{\_tl_check_exists:N}
-% When used as a package, there is an option to be picky and to
-% check definitions exist.
-% These redefinitions are delayed until here so that all the necessary
-% definitions are in place.
-% \begin{macrocode}
-\tex_ifodd:D \@l@expl@check@declarations@bool \scan_stop:
- \cs_set_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
- {
- \_tl_check_exists:N #1
- \cs_set_nopar:Npx #1 { \exp_not:n {#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
- {
- \_tl_check_exists:N #1
- \cs_gset_nopar:Npx #1 { \exp_not:n {#2} }
- }
- \cs_set_protected:Npn \tl_gset:Nx #1#2
- {
- \_tl_check_exists:N #1
- \cs_gset_nopar:Npx #1 {#2}
- }
- \cs_set_protected:Npn \tl_set_eq:NN #1#2
- {
- \_tl_check_exists:N #1
- \_tl_check_exists:N #2
- \cs_set_eq:NN #1 #2
- }
- \cs_set_protected:Npn \tl_gset_eq:NN #1#2
- {
- \_tl_check_exists:N #1
- \_tl_check_exists:N #2
- \cs_gset_eq:NN #1 #2
- }
-\tex_fi:D
-%</package>
-% \end{macrocode}
-%\end{macro}
-%
-% \end{implementation}
-%
-% \endinput