summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/l3kernel/source3body.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-09-16 22:35:41 +0000
committerKarl Berry <karl@freefriends.org>2011-09-16 22:35:41 +0000
commit6d95b4a2c1bbdaea1a3802c822808f476ac5703b (patch)
tree1abf9117bf53f2de53fbcc62c352acc92780365b /Master/texmf-dist/doc/latex/l3kernel/source3body.tex
parentb7f762397f5df2d732326713423e31e1bf91b903 (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.tex127
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}