diff options
author | Karl Berry <karl@freefriends.org> | 2009-06-09 23:31:15 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2009-06-09 23:31:15 +0000 |
commit | 215b9a864d5829070bdc66ba736986eb72e5143e (patch) | |
tree | fe0882c81fc4ec945cee4b512f72eaa21ea5f791 /Master/texmf-dist/source/latex/expl3/source3.tex | |
parent | df90ec06321940c2f066b05e12f1b5ab099105da (diff) |
expl3 1407 (9jun09)
git-svn-id: svn://tug.org/texlive/trunk@13686 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/expl3/source3.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/expl3/source3.tex | 633 |
1 files changed, 316 insertions, 317 deletions
diff --git a/Master/texmf-dist/source/latex/expl3/source3.tex b/Master/texmf-dist/source/latex/expl3/source3.tex index 1199dbf3209..837260437b1 100644 --- a/Master/texmf-dist/source/latex/expl3/source3.tex +++ b/Master/texmf-dist/source/latex/expl3/source3.tex @@ -1,5 +1,5 @@ % \iffalse -%% File: source3.dtx Copyright (C) 1990-2006 LaTeX3 project +%% File: source3.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 @@ -17,7 +17,7 @@ %% %% The development version of the bundle can be found at %% -%% http://www.latex-project.org/cgi-bin/cvsweb.cgi/ +%% http://www.latex-project.org/svnroot/experimental/trunk/ %% %% for those people who are interested. %% @@ -35,184 +35,343 @@ % This document will typeset the LaTeX3 sources as a single document. % This will produce quite a large file (roughly ??? pages) and may -% take a long time. -% -% Some notes on processing this document are contained at the end -% of this document, after \end{document} -% -% DPC 1997/11/17 -% JLB 2005/03/09 copied from source2e.tex for l3in2e sources -% First a special index style for makeindex -% - -\begin{filecontents}{source3.ist} -actual '=' -quote '!' -level '>' -preamble -"\n \\begin{theindex} \n \\makeatletter\\scan@allowedfalse\n" -postamble -"\n\n \\end{theindex}\n" -item_x1 "\\efill \n \\subitem " -item_x2 "\\efill \n \\subsubitem " -delim_0 "\\pfill " -delim_1 "\\pfill " -delim_2 "\\pfill " -% The next lines will produce some warnings when -% running Makeindex as they try to cover two different -% versions of the program: -lethead_prefix "{\\bfseries\\hfil " -lethead_suffix "\\hfil}\\nopagebreak\n" -lethead_flag 1 -heading_prefix "{\\bfseries\\hfil " -heading_suffix "\\hfil}\\nopagebreak\n" -headings_flag 1 - -% and just for source3: -% Remove R so I is treated in sequence I J K not I II III -page_precedence "rnaA" -\end{filecontents} - -\begin{filecontents}{l3doc.cfg} - \DisableCrossrefs - \AtEndOfClass{\OnlyDescription} -\end{filecontents} - -\begin{filecontents}{l3full.cfg} - -% Set up the Index and Change History to use \part - \IndexPrologue{\part*{Index}% - \markboth{Index}{Index}% - \addcontentsline{toc}{part}{Index}% - The italic numbers denote the pages where the - corresponding entry is described, - numbers underlined point to the definition, - all others indicate the places where it is used.} - - \GlossaryPrologue{\part*{Change History}% -% Allow control names to be hyphenated here... - {\GlossaryParms\ttfamily\hyphenchar\font=`\-}% - \markboth{Change History}{Change History}% - \addcontentsline{toc}{part}{Change History}} - - \RecordChanges - \CodelineIndex - \EnableCrossrefs - \AlsoImplementation - \setcounter{IndexColumns}{2} -\end{filecontents} - +% take a long time on a slow machine. \documentclass{l3doc} - \listfiles -% Do not index some TeX primitives, and some common plain TeX commands. - -%% to be filled in later\DoNotIndex{...} -% The standard \changes command modified slightly to better cope with -% this multiple file document. -%\makeatletter -%\def\changes@#1#2#3{% -% \let\protect\@unexpandable@protect -% \edef\@tempa{\noexpand\glossary{#2\space\currentfile\space#1\levelchar -% \ifx\saved@macroname\@empty -% \space -% \actualchar -% \generalname -% \else -% \expandafter\@gobble -% \saved@macroname -% \actualchar -% \string\verb\quotechar*% -% \verbatimchar\saved@macroname -% \verbatimchar -% \fi -% :\levelchar #3}}% -% \@tempa\endgroup\@esphack} -%\makeatother - -% Needed for documentation in ltoutenc.dtx -\usepackage{textcomp} - \begin{document} - \title{The \LaTeX3 Sources} - \author{\Team} - - \pagenumbering{roman} - \maketitle - \renewcommand\maketitle{} - - \tableofcontents - - \clearpage - \pagenumbering{arabic} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -% Each of the following \DocInput lines includes a file with extension -% .dtx. Each of these files may be typeset separately. For instance -% latex l3boxes.dtx -% will typeset the source of the LaTeX3 box commands. -% -% If this file is processed, each of these separate dtx files will be -% contained as a part of a single document. Using ltxdoc.cfg you can -% then optionally produce a combined index and/or change history for -% the entire source of the format file. Note that such a document will -% be quite large (about ??? pages). -% +\title{The \LaTeX3 Sources} +\author{\Team} - \DocInput{l3names.dtx} % System dependant initialisation - \DocInput{l3basics.dtx} % +\pagenumbering{roman} +\maketitle - \DocInput{l3chk.dtx} % Checking assignments +\begin{abstract} - \DocInput{l3tlp.dtx} % +\parindent=0pt +\parskip=\baselineskip - \DocInput{l3expan.dtx} % +\noindent 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 +types of functions. - \DocInput{l3num.dtx} % +The \TeX\ and \eTeX\ primitives are all given a new name according to +these conventions. However, in the main direct use of the primitives is +not required or encouraged: the \pkg{expl3} modules define an +independent low-level \LaTeX3 programming language. - \DocInput{l3seq.dtx} % +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. - \DocInput{l3alloc.dtx} % +\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}. - \DocInput{l3io.dtx} % + New modules will be added to the distributed version of \pkg{expl3} as + they reach maturity. +\end{bfseries} - \DocInput{l3clist.dtx} % +\end{abstract} - \DocInput{l3prop.dtx} % - - \DocInput{l3int.dtx} % - - \DocInput{l3skip.dtx} % - - \DocInput{l3toks.dtx} % - - \DocInput{l3messages.dtx} % - - \DocInput{l3box.dtx} % - - \DocInput{l3precom.dtx} % - - \DocInput{l3quark.dtx} % +\clearpage - \DocInput{l3prg.dtx} % +{\def\\{:}% fix "newlines" in the ToC +\tableofcontents} - \DocInput{l3token.dtx} % +\clearpage +\pagenumbering{arabic} - \DocInput{l3xref.dtx} % +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - \DocInput{l3calc.dtx} % +% Each of the following \DocInput lines includes a file with extension +% .dtx. Each of these files may be typeset separately. For instance +% pdflatex l3box.dtx +% will typeset the source of the LaTeX3 box commands. If you use the +% Makefile, the index will be generated automatically; e.g., +% make doc F=l3box +% +% If this file is processed, each of these separate dtx files will be +% contained as a part of a single document. + +\makeatletter +\def\partname{Part} +\def\maketitle{\part{\@title}} +\let\thanks\@gobble +\let\DelayPrintIndex\PrintIndex +\let\PrintIndex\@empty +\makeatother + +\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 +programming language is found in \href{expl3.pdf}{expl3.pdf}. + +\section{Naming functions and variables} + +\LaTeX3 does not use \texttt{@} as a ``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} (``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. + +Each function name starts with the \emph{module} to which it belongs. +Thus apart from a small number of very basic functions, all \pkg{expl3} +function names contain at least one underscore to divide the module +name from the descriptive name of the function. For example, all +functions concerned with comma lists are in module \texttt{clist} and +begin \cs{clist_}. + +Every function must include an argument specifier. For functions which +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}. + 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 + 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, + all will be well. + \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 + get the content of a variable without needing to worry about the + 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 + 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 + 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 + 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 + 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 + 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 + by some arbitrary string). +\end{description} +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}. + +Variables are named in a similar manner to functions, but begin with +a single letter to define the type of variable: +\begin{description} + \item[\texttt{c}] Constant: global parameters whose value should not + be changed. + \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 +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 + \texttt{int} module contains some scratch variables called \cs{l_tmpa_int}, + \cs{l_tmpb_int}, and so on. In such a case adding the module name up front + to denote the module + and in the back to indicate the type, as in + \cs{l_int_tmpa_int} would be very unreadable.} name +and then a descriptive part. +Variables end with a short identifier to show the variable type: +\begin{description} + \item[\texttt{bool}] Either true or false. + \item[\texttt{box}] Box register. + \item[\texttt{clist}] Comma separated list. + \item[\texttt{dim}] `Rigid' lengths. + \item[\texttt{int}] Integer-valued count register. + \item[\texttt{num}] A `fake' integer type using only macros. Useful for + setting up allocation routines. + \item[\texttt{prop}] Property list. + \item[\texttt{skip}] `Rubber' lengths. + \item[\texttt{seq}] `Sequence': a data-type used to implement lists + (with access at both ends) and stacks. + \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. + \item[\texttt{toks}] Token register. +\end{description} + +\section{Documentation conventions} + +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. + +Each group of related functions is given in a box. For a function with +a ``user'' name, this might read: +\begin{function}{ + \ExplSyntaxOn | + \ExplSyntaxOff + } + \begin{syntax} + "\ExplSyntaxOn" + \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 + name of the function is simply reprinted. +\end{function} + +For programming functions, which use \texttt{_} and \texttt{:} in their +name there are a few additional conventions: If two related functions are given with identical names but +different argument specifiers, these are termed \emph{variants} of each +other, and the latter functions are printed in grey to show this more +clearly. They will carry out the same function but will take different +types of argument: +\begin{function}{ + \seq_new:N | + \seq_new:c + } + \begin{syntax} + "\seq_new:N" <sequence> + \end{syntax} + When a number of variants are described, the arguments are usually + illustrated only for the base function. Here, <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 + name rather than as a control sequence. Each argument given in the + illustration should be described in the following text. +\end{function} + +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 +a star: +\begin{function}{ + \cs_to_str:N / (EXP) + } + \begin{syntax} + "\cs_to_str:N" <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 <cs>, + shorthand for a <control sequence>. +\end{function} + +Conditional (\texttt{if}) functions are normally defined in three variants, with +\texttt{T}, \texttt{F} and \texttt{TF} argument specifiers. This allows +them to be used for different `true'/`false' branches, 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}{ + \xetex_if_engine: / (TF) (EXP) + } + \begin{syntax} + "\xetex_if_engine:TF" <true code> <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 + will use the \texttt{TF} variant, and so both <true code> + and <false code> will be shown. The two variant forms \texttt{T} and + \texttt{F} take only <true code> and <false code>, respectively. + Here, the star also shows that this function is expandable. + 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 + 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 `\textbf{\TeX{}hackers +note}' section: +\begin{function}{ + \token_to_str:N / (EXP) + } + \begin{syntax} + "\token_to_str:N" <token> + \end{syntax} + The normal description text. + \begin{texnote} + 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} +\end{function} + +\DisableImplementation + +\DocInput{l3names.dtx} + +\DocInput{l3basics.dtx} +\DocInput{l3expan.dtx} +\DocInput{l3prg.dtx} +\DocInput{l3quark.dtx} +\DocInput{l3token.dtx} + +\DocInput{l3int.dtx} +\DocInput{l3num.dtx} +\DocInput{l3intexpr.dtx} +\DocInput{l3skip.dtx} + +\DocInput{l3tl.dtx} +\DocInput{l3toks.dtx} +\DocInput{l3seq.dtx} +\DocInput{l3clist.dtx} +\DocInput{l3prop.dtx} + +\DocInput{l3io.dtx} +\DocInput{l3msg.dtx} +\DocInput{l3box.dtx} +\DocInput{l3xref.dtx} +\DocInput{l3keyval.dtx} +\DocInput{l3calc.dtx} +\DocInput{l3file.dtx} + +% \DocInput{l3precom.dtx} +% \DocInput{l3alloc.dtx} +% \DocInput{l3chk.dtx} + +\part{Implementation} +\def\maketitle{} +\EnableImplementation +\DisableDocumentation +\DocInputAgain %% \DocInput{l3vers.dtx} % Current version date - \includeltpatch % Corrections distributed after the full release - -% Stop here if ltxdoc.cfg says \AtEndOfClass{\OnlyDescription} -\StopEventually{\PrintIndex\end{document}} +\includeltpatch % Corrections distributed after the full release \clearpage \pagestyle{headings} @@ -222,178 +381,18 @@ page_precedence "rnaA" \newcount\hbadness \hfuzz=\maxdimen -\typeout{% - \string # Produce change log with^^J% - makeindex -s gglo.ist -o source3.gls source3.glo} - - \PrintChanges - \clearpage -% makeindex needs a symbol between the parts of composite page numbers -% but we dont want one, so: -\typeout{% - \string # Produce index with^^J% - makeindex -s source3.ist source3.idx} - \begingroup \def\endash{--} \catcode`\-\active \def-{\futurelet\temp\indexdash} \def\indexdash{\ifx\temp-\endash\fi} -\PrintIndex +\DelayPrintIndex \endgroup -% Make sure that the index is not printed twice -% (ltxdoc.cfg might have a second \PrintIndex command) -\let\PrintChanges\relax -\let\PrintIndex\relax - \end{document} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -To use this file to produce a fully indexed source code -you need to execute the following (or equivalent) commands: - - latex source3.tex - - makeindex -s source3.ist source3.idx - makeindex -s gglo.ist -o source3.gls source3.glo - - latex source3.tex - latex source3.tex - - -The makeindex style source3.ist is used in place of the usual -doc gind.ist to ensure that I is used in the sequence I J K -not I II II, which would be the default makeindex behaviour. - -The third run with latex is only required to get the table of -contents entries for the change log and index. You may speed things up -by using the \includeonly mechanism so as not to typeset the source -files on the second run. This involves changing the file -ltxdoc.cfg -between the latex runs. - -The following unix script automates this. - (It could easily be ported to scripts for DOS or VMS, - rm is ReMove a file, and echo "..." > file writes ... to "file".) - - -After this script (after the second ==============) is a similar script -that will produce the documentation for all the files in the base -distribution that are *not* included in source3.dvi. This second script -was requested, but before using it, beware it will take a long time! -It may however be modified as required, eg to not typeset the fdd files -or whatever... - -============== -#!/bin/sh - -rm -f source3.gls source3.ind source3.toc - -# First run: -# Create new standard ltxdoc.cfg file -# Pass the (possibly empty) list of arguments supplied on the -# command line to article class. -# -# If you use A4 paper, running this script with argument -# a4paper -# may save about 30 pages. -# -echo "\PassOptionsToClass{$*}{article}" > ltxdoc.cfg - - -# Now LaTeX the file with this cfg file. -# -latex source3.tex - - -# Make the Change log and Glossary. -# -makeindex -s source3.ist source3.idx -makeindex -s gglo.ist -o source3.gls source3.glo - - -# Second run: append \includeonly{} to ltxdoc.cfg to speed up things -# (this run needed only to get changes and index listed in .toc file) -# -# Note that the index will not be made incorrect by the insertion -# of the table of contents as the front matter uses a diferent page -# numbering scheme. -# -echo "\includeonly{}" >> ltxdoc.cfg - -latex source3.tex - - -# Third and final run, to put everything together. -# First restore the cfg file: -# -echo "\PassOptionsToClass{$*}{article}" > ltxdoc.cfg -latex source3.tex - - -============== -#!/bin/sh - -# Running this script will process all the dtx fdd and *guide.tex -# and ltnews*.tex files in the LaTeX distribution, except the dtx -# files included in source3.tex. -# (The shell first script in the comments of source3.tex will -# process those.) - -# Any command line arguments (eg a4paper) are taken as options to the -# article class. - -# This script is likely to take ages! - -echo "\PassOptionsToClass{$*}{article}" > ltxdoc.cfg -echo "\batchmode" >> ltxdoc.cfg - -# The next four lines produce full indexes and change logs -# you may not want those. -echo "\AtBeginDocument{\RecordChanges}" >> ltxdoc.cfg -echo "\AtEndDocument{\PrintChanges}" >> ltxdoc.cfg -echo "\AtBeginDocument{\CodelineIndex\EnableCrossrefs}" >> ltxdoc.cfg -echo "\AtEndDocument{\PrintIndex}" >> ltxdoc.cfg - -# If you do not want any code listings, just documentation, then instead -# of the above four lines, uncomment the following: -# echo "\AtBeginDocument{\OnlyDescription}" >> ltxdoc.cfg - -echo "\PassOptionsToClass{$*}{article}" > ltxguide.cfg -echo "\batchmode" >> ltxguide.cfg - -cp ltxguide.cfg ltnews.cfg - - -for i in *dtx *fdd *guide.tex ltnews*.tex -do -B=`basename $i .dtx` - -if (grep "Include{$B}" source3.tex >/dev/null ; ) -then -echo In source3: $i -else -echo latex $i - if (latex $i > /dev/null) - then - echo latex $i - latex $i > /dev/null - echo makeindex -s gind.ist $B.idx - makeindex -s gind.ist $B.idx > /dev/null 2> /dev/null - echo makeindex -s gglo.ist -o $B.gls $B.glo - makeindex -s gglo.ist -o $B.gls $B.glo > /dev/null 2> /dev/null - echo latex $i - latex $i > /dev/null - else - echo "!!! LaTeX ERROR: $i. (See $B.log.)" - fi -fi - -done |