From 60e55e3300d53b2692b076e1eed63de0d390f50d Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Wed, 26 Jan 2011 23:21:07 +0000 Subject: expl3 2138 (26jan11) git-svn-id: svn://tug.org/texlive/trunk@21185 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/expl3/expl3.pdf | Bin 512728 -> 512725 bytes Master/texmf-dist/doc/latex/expl3/interface3.tex | 83 ----- Master/texmf-dist/doc/latex/expl3/l3calc.pdf | Bin 377232 -> 461759 bytes Master/texmf-dist/doc/latex/expl3/source3.pdf | Bin 1568303 -> 2213356 bytes Master/texmf-dist/doc/latex/expl3/source3.tex | 102 ------ Master/texmf-dist/doc/latex/expl3/source3body.tex | 391 --------------------- .../texmf-dist/source/latex/expl3/interface3.tex | 83 +++++ Master/texmf-dist/source/latex/expl3/l3.ins | 120 +++++++ .../texmf-dist/source/latex/expl3/l3candidates.dtx | 156 ++++---- Master/texmf-dist/source/latex/expl3/l3format.ins | 83 +++++ Master/texmf-dist/source/latex/expl3/l3fp.dtx | 2 +- Master/texmf-dist/source/latex/expl3/l3tl.dtx | 12 +- Master/texmf-dist/source/latex/expl3/source3.tex | 102 ++++++ .../texmf-dist/source/latex/expl3/source3body.tex | 391 +++++++++++++++++++++ Master/texmf-dist/tex/latex/expl3/l3fp.sty | 2 +- Master/texmf-dist/tex/latex/expl3/l3tl.sty | 12 +- 16 files changed, 875 insertions(+), 664 deletions(-) delete mode 100644 Master/texmf-dist/doc/latex/expl3/interface3.tex delete mode 100644 Master/texmf-dist/doc/latex/expl3/source3.tex delete mode 100644 Master/texmf-dist/doc/latex/expl3/source3body.tex create mode 100644 Master/texmf-dist/source/latex/expl3/interface3.tex create mode 100644 Master/texmf-dist/source/latex/expl3/l3.ins create mode 100644 Master/texmf-dist/source/latex/expl3/l3format.ins create mode 100644 Master/texmf-dist/source/latex/expl3/source3.tex create mode 100644 Master/texmf-dist/source/latex/expl3/source3body.tex diff --git a/Master/texmf-dist/doc/latex/expl3/expl3.pdf b/Master/texmf-dist/doc/latex/expl3/expl3.pdf index 6fb8cadd754..1c079761cf7 100644 Binary files a/Master/texmf-dist/doc/latex/expl3/expl3.pdf and b/Master/texmf-dist/doc/latex/expl3/expl3.pdf differ diff --git a/Master/texmf-dist/doc/latex/expl3/interface3.tex b/Master/texmf-dist/doc/latex/expl3/interface3.tex deleted file mode 100644 index cb2d3d88335..00000000000 --- a/Master/texmf-dist/doc/latex/expl3/interface3.tex +++ /dev/null @@ -1,83 +0,0 @@ -% \iffalse -%% File: interface3.tex Copyright (C) 1990-2010 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. -%% -%% ----------------------------------------------------------------------- -%% \fi - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% -% This document will typeset the LaTeX3 interface descriptions a single -% document. This will produce quite a large file (more than 170 pages -% currently) and may take a long time on a slow machine. -% -% There is also a full version of the sources (source3.tex) which additionally -% also typesets the command implementations. -% -% Do not forget to generate the index (as explained on the terminal output -% near the end of the run)! -% -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\documentclass{l3doc} \listfiles - -\begin{document} -%\catcode\string`\_\string=\active - -\title{The \LaTeX3 Interfaces} -\author{\Team} - -\pagenumbering{roman} -\maketitle - -% -% First load all modules and typeset the documentation parts -% - -\input{source3body} % all the individual modules - - - -\clearpage - -\begingroup -\def\endash{--} -\catcode`\-\active -\def-{\futurelet\temp\indexdash} -\def\indexdash{\ifx\temp-\endash\fi} - -\DelayPrintIndex -\endgroup - -\end{document} - - diff --git a/Master/texmf-dist/doc/latex/expl3/l3calc.pdf b/Master/texmf-dist/doc/latex/expl3/l3calc.pdf index 477a2f0412f..49e994124a6 100644 Binary files a/Master/texmf-dist/doc/latex/expl3/l3calc.pdf and b/Master/texmf-dist/doc/latex/expl3/l3calc.pdf differ diff --git a/Master/texmf-dist/doc/latex/expl3/source3.pdf b/Master/texmf-dist/doc/latex/expl3/source3.pdf index f644a02e66e..5f95838412d 100644 Binary files a/Master/texmf-dist/doc/latex/expl3/source3.pdf and b/Master/texmf-dist/doc/latex/expl3/source3.pdf differ diff --git a/Master/texmf-dist/doc/latex/expl3/source3.tex b/Master/texmf-dist/doc/latex/expl3/source3.tex deleted file mode 100644 index 74199936ca1..00000000000 --- a/Master/texmf-dist/doc/latex/expl3/source3.tex +++ /dev/null @@ -1,102 +0,0 @@ -% \iffalse -%% File: source3.dtx Copyright (C) 1990-2010 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. -%% -%% ----------------------------------------------------------------------- -%% \fi - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% -% This document will typeset the LaTeX3 sources as a single document. -% This will produce quite a large file (more than 400 pages) and may -% take a long time on a slow machine. -% -% There is also a shorter version (interface3.tex) that only typesets the -% command % interface descriptions. -% -% Do not forget to generate the index (as explained on the terminal output -% near the end of the run)! -% -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\documentclass{l3doc} -\listfiles - -\begin{document} - - -\title{The \LaTeX3 Sources} -\author{\Team} - -\pagenumbering{roman} -\maketitle - -% -% First load all modules and typeset the documentation parts -% - -\input{source3body} % all the individual modules - -% -% Now reload all modules and typeset the implementation parts -% - -\part{Implementation} -\def\maketitle{} -\EnableImplementation -\DisableDocumentation -\DocInputAgain - -%% \DocInput{l3vers.dtx} % Current version date - -\clearpage -\pagestyle{headings} - -% Make TeX shut up. -\hbadness=10000 -\newcount\hbadness -\hfuzz=\maxdimen - -\PrintChanges -\clearpage - -\begingroup -\def\endash{--} -\catcode`\-\active -\def-{\futurelet\temp\indexdash} -\def\indexdash{\ifx\temp-\endash\fi} - -\DelayPrintIndex -\endgroup - -\end{document} - - diff --git a/Master/texmf-dist/doc/latex/expl3/source3body.tex b/Master/texmf-dist/doc/latex/expl3/source3body.tex deleted file mode 100644 index 017efe6530c..00000000000 --- a/Master/texmf-dist/doc/latex/expl3/source3body.tex +++ /dev/null @@ -1,391 +0,0 @@ -% \iffalse -%% File: source3body.tex Copyright (C) 1990-2010 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. -%% -%% ----------------------------------------------------------------------- -%% \fi - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% -% This file is used by -% -% source3.tex % documentation including implementation -% -% interface3.tex % only interface documentation -% -% -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\begin{abstract} - -\setlength\parindent{0pt} -\setlength\parskip{\baselineskip} - -\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. - -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. - -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}. - - New modules will be added to the distributed version of \pkg{expl3} as - they reach maturity. -\end{bfseries} - -\end{abstract} - -\clearpage - -{\def\\{:}% fix "newlines" in the ToC -\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 -% 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} - -\subsubsection{Terminological inexactitude} - -A word of warning. In this document, and others referring to the \pkg{expl3} -programming modules, we often refer to `variables' and `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 mayn't 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 `function' with no arguments and a `token -list variable' are in truth one and the same. On the other hand, some -`variables' are actually registers that must be initialised and their values -set and retreived with specific functions. - -The conventions of the \pkg{expl3} code are designed to clearly separate the -ideas of `macros that contain data' and `macros that contain code', and a -consistent wrapper is applied to all forms of `data' whether they be macros or -actually registers. This means that sometimes we will use phrases like `the -function returns a value', when actually we just mean `the macro expands to -something'. Similarly, the term `execute' might be used in place of `expand' -or it might refer to the more specific case of `processing in \TeX's stomach' -(if you are familiar with the \TeX{}book parlance). - -If in doubt, please ask; chances are we've been hasty in writing certain -definitions and need to be told to tighten up our terminology. - -\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" \dots\ "\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 - 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" - \end{syntax} - When a number of variants are described, the arguments are usually - illustrated only for the base function. Here, 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" - \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 , - shorthand for a . -\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" - \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 - and will be shown. The two variant forms \texttt{T} and - \texttt{F} take only and , 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" - \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{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{l3keys.dtx} -%\DocInput{l3calc.dtx} -\DocInput{l3file.dtx} - -% \DocInput{l3precom.dtx} -% \DocInput{l3alloc.dtx} -% \DocInput{l3chk.dtx} - -\DocInput{l3fp.dtx} -\DocInput{l3luatex.dtx} - -\endinput diff --git a/Master/texmf-dist/source/latex/expl3/interface3.tex b/Master/texmf-dist/source/latex/expl3/interface3.tex new file mode 100644 index 00000000000..cb2d3d88335 --- /dev/null +++ b/Master/texmf-dist/source/latex/expl3/interface3.tex @@ -0,0 +1,83 @@ +% \iffalse +%% File: interface3.tex Copyright (C) 1990-2010 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. +%% +%% ----------------------------------------------------------------------- +%% \fi + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% This document will typeset the LaTeX3 interface descriptions a single +% document. This will produce quite a large file (more than 170 pages +% currently) and may take a long time on a slow machine. +% +% There is also a full version of the sources (source3.tex) which additionally +% also typesets the command implementations. +% +% Do not forget to generate the index (as explained on the terminal output +% near the end of the run)! +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +\documentclass{l3doc} \listfiles + +\begin{document} +%\catcode\string`\_\string=\active + +\title{The \LaTeX3 Interfaces} +\author{\Team} + +\pagenumbering{roman} +\maketitle + +% +% First load all modules and typeset the documentation parts +% + +\input{source3body} % all the individual modules + + + +\clearpage + +\begingroup +\def\endash{--} +\catcode`\-\active +\def-{\futurelet\temp\indexdash} +\def\indexdash{\ifx\temp-\endash\fi} + +\DelayPrintIndex +\endgroup + +\end{document} + + diff --git a/Master/texmf-dist/source/latex/expl3/l3.ins b/Master/texmf-dist/source/latex/expl3/l3.ins new file mode 100644 index 00000000000..91288ab8004 --- /dev/null +++ b/Master/texmf-dist/source/latex/expl3/l3.ins @@ -0,0 +1,120 @@ + +\input docstrip.tex +\askforoverwritefalse + +\preamble + + +EXPERIMENTAL CODE + +Do not distribute this file without also distributing the +source files specified above. + +Do not distribute a modified version of this file. + + +\endpreamble +% stop docstrip adding \endinput +\postamble +\endpostamble + +\keepsilent + +% wrapper package for the expl3 bundle +\generate{\file{expl3.sty}{\from{expl3.dtx}{package}}} + + +% l3names.sty sets up the naming scheme for TeX primitives. +\generate{\file{l3names.sty}{\from{l3names.dtx}{package}}} + + + +% Define some basic commands to get us started with the new +% programming style. +\generate{\file{l3basics.sty}{\from{l3basics.dtx}{package,trace}}} + + +% Define some basic commands that check various conditions +% related to defining commands eg defined/undefined global/local +% Not sure how much of this really makes sense as a package, but... +\generate{\file{l3chk.sty}{\from{l3chk.dtx}{package,trace}}} + + +%% toks register handling (can be compiled with check module) +\generate{\file{l3toks.sty}{\from{l3toks.dtx}{package,trace}}} + + +%% token lists +\generate{\file{l3tl.sty}{\from{l3tl.dtx}{package,trace}}} + + +%% LaTeX3 expansion module +\generate{\file{l3expan.sty}{\from{l3expan.dtx}{package,trace}}} + + +%% LaTeX3 quarks. +\generate{\file{l3quark.sty}{\from{l3quark.dtx}{package,trace}}} + + +%% LaTeX3 sequences. +\generate{\file{l3seq.sty}{\from{l3seq.dtx}{package,trace}}} + + +%% LaTeX3 clists. +\generate{\file{l3clist.sty}{\from{l3clist.dtx}{package,trace}}} + + +%% LaTeX3 property lists. +\generate{\file{l3prop.sty}{\from{l3prop.dtx}{package,trace}}} + + +%% LaTeX3 fake integer macros. --- this is still needed in places such as xor !!! +\generate{\file{l3num.sty}{\from{l3num.dtx}{package,trace}}} + +%% LaTeX3 integer registers. (can be compiled with check module) +\generate{\file{l3int.sty}{\from{l3int.dtx}{package,trace}}} + +%% LaTeX3 skip registers. +\generate{\file{l3skip.sty}{\from{l3skip.dtx}{package,trace}}} + + +%% LaTeX3 precompilation +\generate{\file{l3precom.sty}{\from{l3precom.dtx}{package,precompile,trace}}} + +%% LaTeX3 I/O module. +\generate{\file{l3io.sty}{\from{l3io.dtx}{package,trace}}} + +%% LaTeX3 program control structures (loops, booleans, ...) +\generate{\file{l3prg.sty}{\from{l3prg.dtx}{package}}} + +%% LaTeX3 box module +\generate{\file{l3box.sty}{\from{l3box.dtx}{package}}} + +%% LaTeX3 messages +\generate{\file{l3msg.sty}{\from{l3msg.dtx}{package}}} + +%% LaTeX3 tokens +\generate{\file{l3token.sty}{\from{l3token.dtx}{package}}} + +%% LaTeX3 cross references +\generate{\file{l3xref.sty}{\from{l3xref.dtx}{package}}} +%%\generate{\file{l3xref-test.tex}{\from{l3xref.dtx}{testfile}}} + +%% LaTeX3 calc module +\generate{\file{l3calc.sty}{\from{l3calc.dtx}{package}}} + +%% LaTeX3 keyval modules +\generate{\file{l3keyval.sty}{\from{l3keyval.dtx}{package}}} +\generate{\file{l3keys.sty}{\from{l3keys.dtx}{package}}} + +%% LaTeX3 file loading +\generate{\file{l3file.sty}{\from{l3file.dtx}{package}}} + +%% LaTeX3 floating point unit +\generate{\file{l3fp.sty}{\from{l3fp.dtx}{package}}} + +%% LaTeX3 LuaTeX support +\generate{\file{l3luatex.sty}{\from{l3luatex.dtx}{package}}} + + +\endbatchfile diff --git a/Master/texmf-dist/source/latex/expl3/l3candidates.dtx b/Master/texmf-dist/source/latex/expl3/l3candidates.dtx index 98b6fdd6aff..4062f8828c6 100644 --- a/Master/texmf-dist/source/latex/expl3/l3candidates.dtx +++ b/Master/texmf-dist/source/latex/expl3/l3candidates.dtx @@ -37,7 +37,7 @@ % %\fi \errorcontextlines=999 -\GetIdInfo$Id: l3candidates.dtx 2063 2010-10-03 08:26:49Z mittelba $ +\GetIdInfo$Id: l3candidates.dtx 2137 2011-01-23 23:13:58Z will $ {L3 Experimental 'extras' module} %\iffalse %<*driver> @@ -116,35 +116,6 @@ % \end{function} % % -% \begin{function}{\tl_transform:nn|\char_transform:NN} -% \begin{syntax} -% |\tl_transform:nn| \Arg{tranformation rules} \Arg{token list} -% "\char_transform:NN" -% \end{syntax} -% Tokenises and evaluates according to the transformation rules -% given in the first argument. -% These transformation rules may be function/variable -% redefinitions, catcode changes (see "\char_make_other:N" and so on), or -% token transformations given by "\char_transform:NN". -% -% "\char_transform:NN" declares that within the argument, -% any occurences of are interpreted as if they were albeit -% with the same catcode as . -% -% Note 1: Everything evaluated by this function occurs within a group; -% global definitions will be necessary to make changes outside of it. -% -% Note 2: Because this function must be invoked before its arguments are -% tokenised, it cannot be evaluated within another macro (unless clever use -% of "\tl_rescan:nn" is employed). -% \begin{texnote} -% This is a wrapper around \TeX's "\lowercase" primitive and only the ASCII -% uppercase letters are protected from being transformed themselves. -% If you are using Xe\TeX\ or Lua\TeX, be careful of unicode letters that will -% be affected by this process. -% \end{texnote} -% \end{function} -% % \section{Functions for sequences} % % @@ -221,6 +192,27 @@ % % % +% \begin{function}{\clist_length:N / (EXP)|\clist_length:n / (EXP)} +% \begin{syntax} +% "\clist_length:N" +% \end{syntax} +% Expands to the number of elements in the . +% \end{function} +% +% \begin{function}{\clist_element:Nn / (EXP)|\clist_element:nn / (EXP)} +% \begin{syntax} +% "\clist_element:Nn" \Arg{i} +% "\clist_element:nn" |{| |,| |,|\dots|,| |,| |}| \Arg{i} +% "\clist_element:nn" |{| |,| |,|\dots|,| |,| |}| \Arg{i} +% \end{syntax} +% Expands to , the -th element of the . +% The indexing counts from zero, and negative indices count from the end. +% (Negative indexing is slightly less efficent since the length of the list +% must first be calculated.) +% \end{function} +% +% +% % \end{documentation} % % \begin{implementation} @@ -288,48 +280,6 @@ % % % -% \begin{macro}{\tl_transform:nn,\char_transform:NN} -% \begin{macrocode} -\cs_new:Npn \tl_transform:nn #1 - { - \group_begin: - \tl_map_function:nN - { \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z } - \char_protect_uppercase:N - \cs_set_eq:NN \char_transform:NN \char_transform_hidden:NN - #1 - \tl_transform_aux:n - } -% \end{macrocode} -% Allow for catcode changes: -% \begin{macrocode} -\cs_new:Npn \tl_transform_aux:n #1 - { - \tl_to_lowercase:n { \group_end: #1 } - } -\cs_set:Npn \char_protect_uppercase:N #1 - { - \char_set_lccode:nn {`#1} {`#1} - } -% \end{macrocode} -% -% \begin{macrocode} -\cs_new:Npn \char_transform_hidden:NN #1#2 - { - \char_set_lccode:nn {`#1} {`#2} - } -\cs_new:Npn \char_transform:NN - { - \msg_error:nn {l3prg} {naked-char-transform} - } -\msg_new:nnn {l3prg} {naked-char-transform} - { - This command can only appear within the first\\ - argument of \string\tl_transform:nn. - } -% \end{macrocode} -% \end{macro} -% % % \begin{macro}{\seq_mapthread_function:NNN} % \begin{macrocode} @@ -444,6 +394,68 @@ % \end{macro} % % +% +% \begin{macro}{\clist_length:N,\clist_length:n} +% \begin{macrocode} +\cs_new:Npn \clist_length:N { + \exp_args:No \clist_length:n +} +\cs_new:Npn \clist_length:n #1 { + \int_eval:n { + 0 \clist_map_function:nN {#1} \tl_elt_count_aux:n + } +} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\clist_element:Nn,\clist_element:nn} +% \begin{macrocode} +\cs_new:Npn \clist_element:Nn #1 { + \exp_args:No \clist_element:nn #1 +} +\cs_new:Npn \clist_element:nn #1#2 { +% \end{macrocode} +% When negative indexing is used, calculate the length and subtract. +% This incurs a minor performance penalty, of course, but it's nothing to +% worry about. +% \begin{macrocode} + \int_compare:nNnTF {#2} < {0} + { + \exp_args:Nf \clist_element_aux:nw + {\clist_length:n {#1}+#2} #1 , \q_recursion_tail , \q_recursion_stop + } + { + \clist_element_aux:nw {#2} #1 , \q_recursion_tail , \q_recursion_stop + } +% \end{macrocode} +% Shorter but less readable version of the code block above: +% \begin{verbatim} +% \exp_args:Nf \clist_element_aux:nnw +% { #2 \int_compare:nNnT {#2} < {0} { +\clist_length:n {#1} } } +% #1 , \q_recursion_tail , \q_recursion_stop +% \end{verbatim} +% Note in both cases I've used |\exp_args:Nf| directly, since I'm starting +% to think that adding too many control sequences is bad for \TeX's +% performance. +% \begin{macrocode} +} +\cs_new:Npn \clist_element_aux:nw #1#2, { + \quark_if_recursion_tail_stop:n {#2} + \int_compare:nNnTF {#1} = {0} + { + \use_i_delimit_by_q_recursion_stop:nw {#2} + } + { + \clist_element_aux:nw {#1-1} + } +} +% \end{macrocode} +% \end{macro} +% +% +% +% % \begin{macrocode} % % \end{macrocode} diff --git a/Master/texmf-dist/source/latex/expl3/l3format.ins b/Master/texmf-dist/source/latex/expl3/l3format.ins new file mode 100644 index 00000000000..5fb4d549050 --- /dev/null +++ b/Master/texmf-dist/source/latex/expl3/l3format.ins @@ -0,0 +1,83 @@ + +\input docstrip.tex +\askforoverwritefalse + +\preamble + + +EXPERIMENTAL CODE + +Do not distribute this file without also distributing the +source files specified above. + +Do not distribute a modified version of this file. + + +\endpreamble +% stop docstrip adding \endinput +\postamble +\endpostamble + +\keepsilent + +% generate the format file +\generate{% + \file{latex3.ltx}{% + \from{l3names.dtx}{initex} % The naming conventions + \from{l3basics.dtx}{initex} % Initialisations + \from{l3expan.dtx}{initex} % Controlling expansion of arguments + \from{l3tl.dtx}{initex} % token list variables + \from{l3intexpr.dtx}{initex} % + \from{l3quark.dtx}{initex} % quarks + \from{l3seq.dtx}{initex} % Sequences and stacks +% + \from{l3alloc.dtx}{initex} % Register allocations +% + \from{l3toks.dtx}{initex} % dealing with token registers + \from{l3int.dtx}{initex} % dealing with integer registers + \from{l3prg.dtx}{initex} % Program control structures + \from{l3clist.dtx}{initex} % Comma separated lists + \from{l3token.dtx}{initex} % token investigation + \from{l3prop.dtx}{initex} % property lists + \from{l3msg.dtx}{initex} % setting up for user communication + \from{l3io.dtx}{initex} % dealing with I/O + \from{l3skip.dtx}{initex} % dealing with skip registers + \from{l3box.dtx}{initex} % dealing with box registers + \from{l3keyval.dtx}{initex} % + \from{l3keys.dtx}{initex} % + \from{l3fp.dtx}{initex} % + \from{l3luatex.dtx}{initex} % +% +% \from{l3precom.dtx}{initex,precompile} % +% + \from{l3calc.dtx}{initex} % + \from{l3xref.dtx}{initex} % Cross references + \from{l3file.dtx}{initex} % file loading +% + \from{l3vers.dtx}{initex} % Version information +% +% +% \from{l3chk.dtx}{initex} % Checking functions +% + \from{l3final.dtx}{initex} % Final wrap-up + } +} + +% generate higher-level material +\generate{% + \file{xparse.ltx}{\from{xparse.dtx}{initex}} + \file{xtemplate.ltx}{\from{xtemplate.dtx}{initex}} +} + +\Msg{} +\Msg{*************************************} +\Msg{*} +\Msg{* Now run (PDF)INITEX on lbase.ltx} +\Msg{*} +\Msg{* On an up to date system, run } +\Msg{* pdftex -ini -etex *latex3.ltx } +\Msg{*} +\Msg{*************************************} +\Msg{} + +\endbatchfile diff --git a/Master/texmf-dist/source/latex/expl3/l3fp.dtx b/Master/texmf-dist/source/latex/expl3/l3fp.dtx index 7251d1af935..a6fb183db8c 100644 --- a/Master/texmf-dist/source/latex/expl3/l3fp.dtx +++ b/Master/texmf-dist/source/latex/expl3/l3fp.dtx @@ -35,7 +35,7 @@ \RequirePackage{l3names} % %\fi -\GetIdInfo$Id: l3fp.dtx 2128 2011-01-10 22:44:33Z joseph $ +\GetIdInfo$Id: l3fp.dtx 2129 2011-01-10 22:58:48Z joseph $ {L3 Experimental floating-point operations} %\iffalse %<*driver> diff --git a/Master/texmf-dist/source/latex/expl3/l3tl.dtx b/Master/texmf-dist/source/latex/expl3/l3tl.dtx index b436be36ab5..00ab46f152d 100644 --- a/Master/texmf-dist/source/latex/expl3/l3tl.dtx +++ b/Master/texmf-dist/source/latex/expl3/l3tl.dtx @@ -36,7 +36,7 @@ \RequirePackage{l3names} % %\fi -\GetIdInfo$Id: l3tl.dtx 2103 2010-12-18 07:40:03Z joseph $ +\GetIdInfo$Id: l3tl.dtx 2138 2011-01-26 08:15:27Z joseph $ {L3 Experimental Token Lists} %\iffalse %<*driver> @@ -1475,13 +1475,11 @@ % \begin{macrocode} \prg_new_conditional:Nnn \tl_if_single:N {p,TF,T,F} { \tl_if_empty:NTF #1 - {\prg_return_false:} + { \prg_return_false: } { - \exp_after:wN \tl_if_blank:nTF #1 - {\prg_return_true:} - { - \exp_after:wN \_tl_if_single_aux:w #1 \q_stop - } + \tl_if_blank:oTF {#1} + { \prg_return_true: } + { \exp_after:wN \_tl_if_single_aux:w #1 \q_stop } } } % \end{macrocode} diff --git a/Master/texmf-dist/source/latex/expl3/source3.tex b/Master/texmf-dist/source/latex/expl3/source3.tex new file mode 100644 index 00000000000..74199936ca1 --- /dev/null +++ b/Master/texmf-dist/source/latex/expl3/source3.tex @@ -0,0 +1,102 @@ +% \iffalse +%% File: source3.dtx Copyright (C) 1990-2010 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. +%% +%% ----------------------------------------------------------------------- +%% \fi + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% This document will typeset the LaTeX3 sources as a single document. +% This will produce quite a large file (more than 400 pages) and may +% take a long time on a slow machine. +% +% There is also a shorter version (interface3.tex) that only typesets the +% command % interface descriptions. +% +% Do not forget to generate the index (as explained on the terminal output +% near the end of the run)! +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\documentclass{l3doc} +\listfiles + +\begin{document} + + +\title{The \LaTeX3 Sources} +\author{\Team} + +\pagenumbering{roman} +\maketitle + +% +% First load all modules and typeset the documentation parts +% + +\input{source3body} % all the individual modules + +% +% Now reload all modules and typeset the implementation parts +% + +\part{Implementation} +\def\maketitle{} +\EnableImplementation +\DisableDocumentation +\DocInputAgain + +%% \DocInput{l3vers.dtx} % Current version date + +\clearpage +\pagestyle{headings} + +% Make TeX shut up. +\hbadness=10000 +\newcount\hbadness +\hfuzz=\maxdimen + +\PrintChanges +\clearpage + +\begingroup +\def\endash{--} +\catcode`\-\active +\def-{\futurelet\temp\indexdash} +\def\indexdash{\ifx\temp-\endash\fi} + +\DelayPrintIndex +\endgroup + +\end{document} + + diff --git a/Master/texmf-dist/source/latex/expl3/source3body.tex b/Master/texmf-dist/source/latex/expl3/source3body.tex new file mode 100644 index 00000000000..017efe6530c --- /dev/null +++ b/Master/texmf-dist/source/latex/expl3/source3body.tex @@ -0,0 +1,391 @@ +% \iffalse +%% File: source3body.tex Copyright (C) 1990-2010 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. +%% +%% ----------------------------------------------------------------------- +%% \fi + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% This file is used by +% +% source3.tex % documentation including implementation +% +% interface3.tex % only interface documentation +% +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +\begin{abstract} + +\setlength\parindent{0pt} +\setlength\parskip{\baselineskip} + +\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. + +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. + +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}. + + New modules will be added to the distributed version of \pkg{expl3} as + they reach maturity. +\end{bfseries} + +\end{abstract} + +\clearpage + +{\def\\{:}% fix "newlines" in the ToC +\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 +% 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} + +\subsubsection{Terminological inexactitude} + +A word of warning. In this document, and others referring to the \pkg{expl3} +programming modules, we often refer to `variables' and `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 mayn't 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 `function' with no arguments and a `token +list variable' are in truth one and the same. On the other hand, some +`variables' are actually registers that must be initialised and their values +set and retreived with specific functions. + +The conventions of the \pkg{expl3} code are designed to clearly separate the +ideas of `macros that contain data' and `macros that contain code', and a +consistent wrapper is applied to all forms of `data' whether they be macros or +actually registers. This means that sometimes we will use phrases like `the +function returns a value', when actually we just mean `the macro expands to +something'. Similarly, the term `execute' might be used in place of `expand' +or it might refer to the more specific case of `processing in \TeX's stomach' +(if you are familiar with the \TeX{}book parlance). + +If in doubt, please ask; chances are we've been hasty in writing certain +definitions and need to be told to tighten up our terminology. + +\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" \dots\ "\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 + 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" + \end{syntax} + When a number of variants are described, the arguments are usually + illustrated only for the base function. Here, 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" + \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 , + shorthand for a . +\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" + \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 + and will be shown. The two variant forms \texttt{T} and + \texttt{F} take only and , 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" + \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{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{l3keys.dtx} +%\DocInput{l3calc.dtx} +\DocInput{l3file.dtx} + +% \DocInput{l3precom.dtx} +% \DocInput{l3alloc.dtx} +% \DocInput{l3chk.dtx} + +\DocInput{l3fp.dtx} +\DocInput{l3luatex.dtx} + +\endinput diff --git a/Master/texmf-dist/tex/latex/expl3/l3fp.sty b/Master/texmf-dist/tex/latex/expl3/l3fp.sty index 73dac125835..6ac5741afb0 100644 --- a/Master/texmf-dist/tex/latex/expl3/l3fp.sty +++ b/Master/texmf-dist/tex/latex/expl3/l3fp.sty @@ -48,7 +48,7 @@ %% %% ----------------------------------------------------------------------- \RequirePackage{l3names} -\GetIdInfo$Id: l3fp.dtx 2128 2011-01-10 22:44:33Z joseph $ +\GetIdInfo$Id: l3fp.dtx 2129 2011-01-10 22:58:48Z joseph $ {L3 Experimental floating-point operations} \ProvidesExplPackage {\filename}{\filedate}{\fileversion}{\filedescription} diff --git a/Master/texmf-dist/tex/latex/expl3/l3tl.sty b/Master/texmf-dist/tex/latex/expl3/l3tl.sty index cd8125b8d1b..e334d246130 100644 --- a/Master/texmf-dist/tex/latex/expl3/l3tl.sty +++ b/Master/texmf-dist/tex/latex/expl3/l3tl.sty @@ -48,7 +48,7 @@ %% %% ----------------------------------------------------------------------- \RequirePackage{l3names} -\GetIdInfo$Id: l3tl.dtx 2103 2010-12-18 07:40:03Z joseph $ +\GetIdInfo$Id: l3tl.dtx 2138 2011-01-26 08:15:27Z joseph $ {L3 Experimental Token Lists} \ProvidesExplPackage {\filename}{\filedate}{\fileversion}{\filedescription} @@ -282,13 +282,11 @@ } \prg_new_conditional:Nnn \tl_if_single:N {p,TF,T,F} { \tl_if_empty:NTF #1 - {\prg_return_false:} + { \prg_return_false: } { - \exp_after:wN \tl_if_blank:nTF #1 - {\prg_return_true:} - { - \exp_after:wN \_tl_if_single_aux:w #1 \q_stop - } + \tl_if_blank:oTF {#1} + { \prg_return_true: } + { \exp_after:wN \_tl_if_single_aux:w #1 \q_stop } } } \cs_new:Npn \_tl_if_single_aux:w #1#2 \q_stop { -- cgit v1.2.3