diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/expl3.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/expl3/expl3.dtx | 1013 |
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 |