diff options
author | Karl Berry <karl@freefriends.org> | 2011-09-16 22:35:41 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2011-09-16 22:35:41 +0000 |
commit | 6d95b4a2c1bbdaea1a3802c822808f476ac5703b (patch) | |
tree | 1abf9117bf53f2de53fbcc62c352acc92780365b /Master/texmf-dist/doc/latex/l3kernel/source3body.tex | |
parent | b7f762397f5df2d732326713423e31e1bf91b903 (diff) |
l3kernel 2828 (15sep11)
git-svn-id: svn://tug.org/texlive/trunk@23983 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/l3kernel/source3body.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/l3kernel/source3body.tex | 127 |
1 files changed, 64 insertions, 63 deletions
diff --git a/Master/texmf-dist/doc/latex/l3kernel/source3body.tex b/Master/texmf-dist/doc/latex/l3kernel/source3body.tex index d68e88af3d3..1c4a797023b 100644 --- a/Master/texmf-dist/doc/latex/l3kernel/source3body.tex +++ b/Master/texmf-dist/doc/latex/l3kernel/source3body.tex @@ -9,7 +9,7 @@ %% %% http://www.latex-project.org/lppl.txt %% -%% This file is part of the "expl3 bundle" (The Work in LPPL) +%% This file is part of the "l3kernel bundle" (The Work in LPPL) %% and all files in that bundle must be distributed together. %% %% The released version of this bundle is available from CTAN. @@ -53,7 +53,7 @@ \setlength\parskip{\baselineskip} \noindent -This is the reference documentation for the \pkg{expl3} +This is the reference documentation for the \pkg{expl3} programming environment. The \pkg{expl3} modules set up an experimental naming scheme for \LaTeX{} commands, which allow the \LaTeX{} programmer to systematically name functions and variables, and specify the argument @@ -107,7 +107,7 @@ stand-alone \LaTeX3 is developed. \makeatletter \def\partname{Part} -\def\maketitle{\part{\@title}} +\def\maketitle{\clearpage\part{\@title}} \let\thanks\@gobble \let\DelayPrintIndex\PrintIndex \let\PrintIndex\@empty @@ -115,19 +115,19 @@ stand-alone \LaTeX3 is developed. \part{Introduction to \pkg{expl3} and this document} -This document is intended to act as a comprehensive reference manual -for the \pkg{expl3} language. A general guide to the \LaTeX3 +This document is intended to act as a comprehensive reference manual +for the \pkg{expl3} language. A general guide to the \LaTeX3 programming language is found in \href{expl3.pdf}{expl3.pdf}. -\section{Naming functions and variables} +\section{Naming functions and variables} \LaTeX3 does not use \texttt{@} as a \enquote{letter} for defining internal macros. Instead, the symbols |_| and \texttt{:} are used in internal macro names to provide structure. The name of -each \emph{function} is divided into logical units using \texttt{_}, -while \texttt{:} separates the \emph{name} of the function from the -\emph{argument specifier} (\enquote{arg-spec}). This describes the arguments -expected by the function. In most cases, each argument is represented +each \emph{function} is divided into logical units using \texttt{_}, +while \texttt{:} separates the \emph{name} of the function from the +\emph{argument specifier} (\enquote{arg-spec}). This describes the arguments +expected by the function. In most cases, each argument is represented by a single letter. The complete list of arg-spec letters for a function is referred to as the \emph{signature} of the function. @@ -143,50 +143,50 @@ take no arguments, this will be blank and the function name will end \texttt{:}. Most functions take one or more arguments, and use the following argument specifiers: \begin{description} - \item[\texttt{D}] The \texttt{D} specifier means \emph{do not use}. + \item[\texttt{D}] The \texttt{D} specifier means \emph{do not use}. All of the \TeX{} primitives are initially \cs{let} to a \texttt{D} - name, and some are then given a second name. Only the kernel + name, and some are then given a second name. Only the kernel team should use anything with a \texttt{D} specifier! \item[\texttt{N} and \texttt{n}] These mean \emph{no manipulation}, - of a single token for \texttt{N} and of a set of tokens given in - braces for \texttt{n}. Both pass the argument though exactly as - given. Usually, if you use a single token for an \texttt{n} argument, + of a single token for \texttt{N} and of a set of tokens given in + braces for \texttt{n}. Both pass the argument though exactly as + given. Usually, if you use a single token for an \texttt{n} argument, all will be well. - \item[\texttt{c}] This means \emph{csname}, and indicates that the + \item[\texttt{c}] This means \emph{csname}, and indicates that the argument will be turned into a csname before being used. So So \cs{foo:c} |{ArgumentOne}| will act in the same way as \cs{foo:N} \cs{ArgumentOne}. - \item[\texttt{V} and \texttt{v}] These mean \emph{value - of variable}. The \texttt{V} and \texttt{v} specifiers are used to + \item[\texttt{V} and \texttt{v}] These mean \emph{value + of variable}. The \texttt{V} and \texttt{v} specifiers are used to get the content of a variable without needing to worry about the - underlying \TeX{} structure containing the data. A \texttt{V} + underlying \TeX{} structure containing the data. A \texttt{V} argument will be a single token (similar to \texttt{N}), for example - \cs{foo:V} \cs{MyVariable}; on the other hand, using \texttt{v} a - csname is constructed first, and then the value is recovered, for + \cs{foo:V} \cs{MyVariable}; on the other hand, using \texttt{v} a + csname is constructed first, and then the value is recovered, for example \cs{foo:v} |{MyVariable}|. \item[\texttt{o}] This means \emph{expansion once}. In general, the \texttt{V} and \texttt{v} specifiers are favoured over \texttt{o} for recovering stored information. However, \texttt{o} is useful for correctly processing information with delimited arguments. - \item[\texttt{x}] The \texttt{x} specifier stands for \emph{exhaustive + \item[\texttt{x}] The \texttt{x} specifier stands for \emph{exhaustive expansion}: the plain \TeX{} \cs{edef}. - \item[\texttt{f}] The \texttt{f} specifier stands for \emph{full - expansion}, and in contrast to \emph{x} stops at the first + \item[\texttt{f}] The \texttt{f} specifier stands for \emph{full + expansion}, and in contrast to \emph{x} stops at the first non-expandable item without trying to execute it. \item[\texttt{T} and \texttt{F}] For logic tests, there are the branch - specifiers \texttt{T} (\emph{true}) and \texttt{F} (\emph{false}). - Both specifiers treat the input in the same way as \texttt{n} (no + specifiers \texttt{T} (\emph{true}) and \texttt{F} (\emph{false}). + Both specifiers treat the input in the same way as \texttt{n} (no change), but make the logic much easier to see. - \item[\texttt{p}] The letter \texttt{p} indicates \TeX{} - \emph{parameters}. Normally this will be used for delimited + \item[\texttt{p}] The letter \texttt{p} indicates \TeX{} + \emph{parameters}. Normally this will be used for delimited functions as \pkg{expl3} provides better methods for creating simple - sequential arguments. - \item[\texttt{w}] Finally, there is the \texttt{w} specifier for - \emph{weird} arguments. This covers everything else, but mainly - applies to delimited values (where the argument must be terminated + sequential arguments. + \item[\texttt{w}] Finally, there is the \texttt{w} specifier for + \emph{weird} arguments. This covers everything else, but mainly + applies to delimited values (where the argument must be terminated by some arbitrary string). \end{description} -Notice that the argument specifier describes how the argument is +Notice that the argument specifier describes how the argument is processed prior to being passed to the underlying function. For example, \cs{foo:c} will take its argument, convert it to a control sequence and pass it to \cs{foo:N}. @@ -199,7 +199,7 @@ a single letter to define the type of variable: \item[\texttt{g}] Parameters whose value should only be set globally. \item[\texttt{l}] Parameters whose value should only be set locally. \end{description} -Each variable name is then build up in a similar way to that of a +Each variable name is then build up in a similar way to that of a function, typically starting with the module\footnote{The module names are not used in case of generic scratch registers defined in the data type modules, e.g., the @@ -220,10 +220,10 @@ Variables end with a short identifier to show the variable type: \item[\texttt{fp}] floating-point values; \item[\texttt{int}] Integer-valued count register. \item[\texttt{prop}] Property list. - \item[\texttt{seq}] \enquote{Sequence}: a data-type used to implement lists + \item[\texttt{seq}] \enquote{Sequence}: a data-type used to implement lists (with access at both ends) and stacks. \item[\texttt{skip}] \enquote{Rubber} lengths. - \item[\texttt{stream}] An input or output stream (for reading from or + \item[\texttt{stream}] An input or output stream (for reading from or writing to, respectively). \item[\texttt{tl}] Token list variables: placeholder for a token list. \end{description} @@ -231,25 +231,25 @@ Variables end with a short identifier to show the variable type: \subsection{Terminological inexactitude} A word of warning. In this document, and others referring to the \pkg{expl3} -programming modules, we often refer to \enquote{variables} and +programming modules, we often refer to \enquote{variables} and \enquote{functions} as if they were actual constructs from a real programming language. In truth, \TeX{} is a macro processor, and functions are simply macros that may or may not take arguments and expand to their replacement text. Many of the common variables are \emph{also} macros, and if placed into the input stream will simply expand -to their definition as well~--- a \enquote{function} with no arguments and a +to their definition as well~--- a \enquote{function} with no arguments and a \enquote{token list variable} are in truth one and the same. On the other hand, some \enquote{variables} are actually registers that must be initialised and their values set and retrieved with specific functions. The conventions of the \pkg{expl3} code are designed to clearly separate the -ideas of \enquote{macros that contain data} and +ideas of \enquote{macros that contain data} and \enquote{macros that contain code}, and a consistent wrapper is applied to all forms of \enquote{data} whether they be macros or -actually registers. This means that sometimes we will use phrases like -\enquote{the function returns a value}, when actually we just mean -\enquote{the macro expands to something}. Similarly, the term +actually registers. This means that sometimes we will use phrases like +\enquote{the function returns a value}, when actually we just mean +\enquote{the macro expands to something}. Similarly, the term \enquote{execute} might be used in place of \enquote{expand} or it might refer to the more specific case of \enquote{processing in \TeX's stomach} @@ -260,7 +260,7 @@ definitions and need to be told to tighten up our terminology. \section{Documentation conventions} -This document is typeset with the experimental \pkg{l3doc} class; +This document is typeset with the experimental \pkg{l3doc} class; several conventions are used to help describe the features of the code. A number of conventions are used here to make the documentation clearer. @@ -270,9 +270,9 @@ a \enquote{user} name, this might read: \begin{syntax} \cs{ExplSyntaxOn} \dots{} \cs{ExplSyntaxOff} \end{syntax} - The textual description of how the function works would appear here. The - syntax of the function is shown in mono-spaced text to the right of - the box. In this example, the function takes no arguments and so the + The textual description of how the function works would appear here. The + syntax of the function is shown in mono-spaced text to the right of + the box. In this example, the function takes no arguments and so the name of the function is simply reprinted. \end{function} @@ -287,26 +287,27 @@ different types of argument: \cs{seq_new:N} \meta{sequence} \end{syntax} When a number of variants are described, the arguments are usually - illustrated only for the base function. Here, \meta{sequence} indicates + illustrated only for the base function. Here, \meta{sequence} indicates that \cs{seq_new:N} expects the name of a sequence. From the argument - specifier, \cs{seq_new:c} also expects a sequence name, but as a + specifier, \cs{seq_new:c} also expects a sequence name, but as a name rather than as a control sequence. Each argument given in the illustration should be described in the following text. \end{function} \paragraph{Fully expandable functions} \hypertarget{expstar}{Some functions are fully expandable}, -which allows it to be used within -an \texttt{x}-type argument (in plain \TeX{} terms, inside an \cs{edef}). -These fully expandable functions are indicated in the documentation by +which allows it to be used within +an \texttt{x}-type argument (in plain \TeX{} terms, inside an \cs{edef}), +as well as within an \texttt{f}-type argument. +These fully expandable functions are indicated in the documentation by a star: \begin{function}[EXP]{\cs_to_str:N} \begin{syntax} \cs{cs_to_str:N} \meta{cs} \end{syntax} As with other functions, some text should follow which explains how - the function works. Usually, only the star will indicate that the - function is expandable. In this case, the function expects a \meta{cs}, + the function works. Usually, only the star will indicate that the + function is expandable. In this case, the function expects a \meta{cs}, shorthand for a \meta{control sequence}. \end{function} @@ -316,7 +317,7 @@ an \texttt{f}-type argument. In this case a hollow star is used to indicate this: \begin{function}[rEXP]{\seq_map_function:NN} \begin{syntax} - \cs{tl_trim_spaces:n} \meta{seq} \meta{function} + \cs{seq_map_function:NN} \meta{seq} \meta{function} \end{syntax} \end{function} @@ -325,32 +326,32 @@ this: are normally defined in three variants, with \texttt{T}, \texttt{F} and \texttt{TF} argument specifiers. This allows them to be used for different \enquote{true}/\enquote{false} branches, -depending on -which outcome the conditional is being used to test. To indicate this +depending on +which outcome the conditional is being used to test. To indicate this without repetition, this information is given in a shortened form: \begin{function}[EXP,TF]{\xetex_if_engine:} \begin{syntax} \cs{xetex_if_engine:TF} \Arg{true code} \Arg{false code} \end{syntax} - The underlining and italic of \texttt{TF} indicates that - \cs{xetex_if_engine:T}, \cs{xetex_if_engine:F} and - \cs{xetex_if_engine:TF} are all available. Usually, the illustration + The underlining and italic of \texttt{TF} indicates that + \cs{xetex_if_engine:T}, \cs{xetex_if_engine:F} and + \cs{xetex_if_engine:TF} are all available. Usually, the illustration will use the \texttt{TF} variant, and so both \meta{true code} and \meta{false code} will be shown. The two variant forms \texttt{T} and \texttt{F} take only \meta{true code} and \meta{false code}, respectively. Here, the star also shows that this function is expandable. - With some minor exceptions, \emph{all} conditional functions in the + With some minor exceptions, \emph{all} conditional functions in the \pkg{expl3} modules should be defined in this way. \end{function} Variables, constants and so on are described in a similar manner: \begin{variable}{\l_tmpa_tl} - A short piece of text will describe the variable: there is no + A short piece of text will describe the variable: there is no syntax illustration in this case. \end{variable} In some cases, the function is similar to one in \LaTeXe{} or plain \TeX{}. -In these cases, the text will include an extra \enquote{\textbf{\TeX{}hackers +In these cases, the text will include an extra \enquote{\textbf{\TeX{}hackers note}} section: \begin{function}[EXP]{\token_to_str:N} \begin{syntax} @@ -358,7 +359,7 @@ note}} section: \end{syntax} The normal description text. \begin{texnote} - Detail for the experienced \TeX{} or \LaTeXe\ programmer. In this + Detail for the experienced \TeX{} or \LaTeXe\ programmer. In this case, it would point out that this function is the \TeX{} primitive \cs{string}. \end{texnote} |