From 62ea3c38421c330e364e1b53c366715efe3c7554 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Mon, 29 Aug 2011 00:08:58 +0000
Subject: l3kernel 2678 (28aug11)

git-svn-id: svn://tug.org/texlive/trunk@23738 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/doc/latex/l3kernel/README        |   9 +-
 Master/texmf-dist/doc/latex/l3kernel/expl3.pdf     | Bin 615923 -> 615780 bytes
 .../texmf-dist/doc/latex/l3kernel/interface3.pdf   | Bin 0 -> 1108029 bytes
 .../texmf-dist/doc/latex/l3kernel/interface3.tex   |  89 +++++
 .../texmf-dist/doc/latex/l3kernel/l3styleguide.pdf | Bin 0 -> 266158 bytes
 .../texmf-dist/doc/latex/l3kernel/l3styleguide.tex | 174 +++++++++
 .../doc/latex/l3kernel/l3syntax-changes.pdf        | Bin 0 -> 185448 bytes
 .../doc/latex/l3kernel/l3syntax-changes.tex        |  73 ++++
 Master/texmf-dist/doc/latex/l3kernel/source3.pdf   | Bin 2632214 -> 2632286 bytes
 Master/texmf-dist/doc/latex/l3kernel/source3.tex   | 106 ++++++
 .../texmf-dist/doc/latex/l3kernel/source3body.tex  | 392 +++++++++++++++++++++
 11 files changed, 838 insertions(+), 5 deletions(-)
 create mode 100644 Master/texmf-dist/doc/latex/l3kernel/interface3.pdf
 create mode 100644 Master/texmf-dist/doc/latex/l3kernel/interface3.tex
 create mode 100644 Master/texmf-dist/doc/latex/l3kernel/l3styleguide.pdf
 create mode 100644 Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex
 create mode 100644 Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.pdf
 create mode 100644 Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.tex
 create mode 100644 Master/texmf-dist/doc/latex/l3kernel/source3.tex
 create mode 100644 Master/texmf-dist/doc/latex/l3kernel/source3body.tex

(limited to 'Master/texmf-dist/doc/latex')

diff --git a/Master/texmf-dist/doc/latex/l3kernel/README b/Master/texmf-dist/doc/latex/l3kernel/README
index 9281d08f4c1..86bd894c7bc 100644
--- a/Master/texmf-dist/doc/latex/l3kernel/README
+++ b/Master/texmf-dist/doc/latex/l3kernel/README
@@ -1,8 +1,7 @@
+An Experimental LaTeX3 Programming Convention
+=============================================
 
-   An Experimental LaTeX3 Programming Convention
-   =============================================
-
-   2011/05/10
+   2011/08/22
 
 
 WHERE TO GET IT
@@ -85,5 +84,5 @@ discussion should be directed to the LaTeX-L lists.
 
 =====================================================================
 
---- Copyright 1998-2011 The LaTeX3 Project. All rights reserved ---
+Copyright 1998-2011 The LaTeX3 Project. All rights reserved
 
diff --git a/Master/texmf-dist/doc/latex/l3kernel/expl3.pdf b/Master/texmf-dist/doc/latex/l3kernel/expl3.pdf
index 33e0e3d0264..c069babd84f 100644
Binary files a/Master/texmf-dist/doc/latex/l3kernel/expl3.pdf and b/Master/texmf-dist/doc/latex/l3kernel/expl3.pdf differ
diff --git a/Master/texmf-dist/doc/latex/l3kernel/interface3.pdf b/Master/texmf-dist/doc/latex/l3kernel/interface3.pdf
new file mode 100644
index 00000000000..0ef0de9cdc6
Binary files /dev/null and b/Master/texmf-dist/doc/latex/l3kernel/interface3.pdf differ
diff --git a/Master/texmf-dist/doc/latex/l3kernel/interface3.tex b/Master/texmf-dist/doc/latex/l3kernel/interface3.tex
new file mode 100644
index 00000000000..f4c4fa4e2bf
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/l3kernel/interface3.tex
@@ -0,0 +1,89 @@
+% \iffalse meta-comment
+%
+%% File: interfaces3.tex Copyright (C) 1990-2011 The 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 LaTeX3 Project.
+%%
+%% -----------------------------------------------------------------------
+%
+% \fi
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% This document will typeset the LaTeX3 interface descriptions a single
+% document. This will produce quite a large file (more than 170 pages
+% currently).
+%
+% 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}
+
+\title{The \LaTeX3 Interfaces}
+\author{%
+ The \LaTeX3 Project\thanks
+   {%
+     E-mail:
+       \href{mailto:latex-team@latex-project.org}
+         {latex-team@latex-project.org}%
+   }%
+}
+
+\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/l3kernel/l3styleguide.pdf b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.pdf
new file mode 100644
index 00000000000..13d7af542b8
Binary files /dev/null and b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.pdf differ
diff --git a/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex
new file mode 100644
index 00000000000..b93ebe3fe79
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex
@@ -0,0 +1,174 @@
+\iffalse meta-comment
+
+File l3styleguide.tex Copyright (C) 2011 The 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.
+
+\fi
+
+\documentclass{l3doc}
+\usepackage{svn-multi}
+
+\svnid{$Id: l3styleguide.tex 2328 2011-05-08 07:01:23Z joseph $}
+\def\filedate{\svnfileyear/\svnfilemonth/\svnfileday}
+
+\title{%
+  The \LaTeX3 kernel: style guide for code authors%
+    \thanks
+      {%
+        This file describes v\svnfilerev,
+        last revised \filedate.
+      }%
+}
+\author{%
+  The \LaTeX3 Project\thanks
+    {%
+      E-mail:
+      \href{mailto:latex-team@latex-project.org}%
+        {latex-team@latex-project.org}%
+    }%
+}
+\date{Released \filedate}
+
+\begin{document}
+
+\maketitle
+
+\tableofcontents
+
+\section{Introduction}
+
+This document is intended as a style guide for authors of code and
+documentation for the \LaTeX3 kernel. It covers both aspects of coding
+style and the formatting of the sources. The aim of providing these
+guidelines is help ensure consistency of the code and sources from
+different authors. Experience suggests that in the long-term this helps
+with maintenance. There will of course be places where there are
+exceptions to these guidelines: common sense should always be
+applied!
+
+\section{Documentation style}
+
+\LaTeX3 source and documentation should be written using the document
+class \cls{l3doc} in \file{dtx} format. This class provides a number
+of logical mark up elements, which should be used where possible.
+In the main, this is standard \LaTeX{} practice, but there are a
+few points to highlight:
+\begin{itemize}
+  \item
+    Where possible, use \cs{cs} to mark up control sequences
+    rather than using a verbatim environment.
+  \item
+    Arguments which are given in braces should be marked using
+    \cs{Arg} when code-level functions are discussed, but using
+    \cs{marg} for document functions.
+  \item
+    The names \TeX{}, \LaTeX{}, \emph{etc}.\ use the normal logical mark
+    up followed by an empty group (|{}|), with the exception of |\LaTeX3|,
+    where the number should follow directly.
+  \item
+    Where in line verbatim text is used, it should be marked up
+    using the \verb=|...|= construct (\emph{i.e.}~vertical bars delimit
+    the verbatim text).
+  \item In line quotes should be marked up using the \cs{enquote}
+    function.
+  \item
+    Where numbers in the source have a mathematical meaning,
+    they should be included in math mode. Such in-line math mode
+    material should be marked up using |$...$| and  \emph{not}
+    |\(...\)|.
+\end{itemize}
+
+Line length in the source files should to be under $80$
+characters where possible, as this helps keep everything on the screen
+when editing files. In the \file{dtx} format, documentation lines start
+with a \texttt{\%}, which is usually followed by a space to leave a
+\enquote{comment margin} at the start of each line.
+
+As with code indenting (see later), nested environments and arguments
+should be indented by (at least) two spaces to make the nature of the nesting
+clear. Thus for example a typical arrangement for the \env{function}
+environment might be
+\begin{verbatim*}
+\begin{function}{\seq_gclear:N, \seq_gclear:c}
+  \begin{syntax}
+    \cs{seq_gclear:N} \meta{sequence}
+  \end{syntax}
+  Clears all entries from the \meta{sequence} globally.
+\end{function}
+\end{verbatim*}
+The \enquote{outer} \verb*|% \begin{function}| should have the customary
+space after the |%| character at the start of the line.
+
+In general, a single \env{function}  or \env{macro} environment should be
+used for a group of closely-related functions, for example argument
+specification variants. In such cases, a comma-separated list should be
+used, as shown in the preceding example.
+
+\section{Format of the code itself}
+
+The requirement for less than $80$ characters per line applies to the code
+itself as well as the surrounding documentation. A number of the general
+style principals for \LaTeX3 code apply: these are described in the following
+paragraph and an example is then given.
+
+With the exception of simple runs of parameter (|{#1}|, |#1#2|,
+\emph{etc.}), everything should divided up using spaces to make the code
+more readable. In general, these will be single spaces, but in some
+places it makes more sense to align parts of the code to emphasise
+similarity. (Tabs should not be used for introducing white space.)
+
+Each conceptually-separate step in a function should be on a separate
+line, to make the meaning clearer. Hence the \texttt{false} branch
+in the example uses two lines for the two auxiliary function uses.
+
+Within the definition, a two-space indent should be used to show each
+\enquote{level} of code. Thus in the example \cs{tl_if_empty:nTF} is
+indented by two spaces, but the two branches are indented by four
+spaces. Within the \texttt{false} branch, the need for multiple lines
+means that an additional two-space indent should be used to show that
+these lines are all part of the brace group.
+
+The result of these lay-out conventions is code which will in general
+look like the example:
+\begin{verbatim*}
+\cs_new_nopar:Npn \module_foo:nn #1#2
+  {
+    \tl_if_empty:nTF {#1}
+      { \module_foo_aux:n { X #2 } }
+      {
+        \module_foo_aux:nn {#1} {#2}
+        \module_foo_aux:n {#1#2}
+      }
+  }
+\end{verbatim*}
+
+\section{Code conventions}
+
+When using \cs{cs_generate_variant:Nn}, group related variants together
+to make the pattern clearer. A common example is variants of a function
+which has an \texttt{N}-type first argument:
+\begin{verbatim*}
+\cs_generate_variant:Nn \foo:Nn {     NV , No }
+\cs_generate_variant:Nn \foo:Nn { c , cV , co }
+\end{verbatim*}
+
+There are cases where omitting braces from \texttt{o}-type arguments
+is desirable for performance reasons. This should only be done if the
+argument is a single token, thus for example
+\begin{verbatim}
+\tl_set:No \l_some_tl \l_some_other_tl
+\end{verbatim}
+remains clear and can be used where appropriate.
+
+\end{document}
diff --git a/Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.pdf b/Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.pdf
new file mode 100644
index 00000000000..48e130d080b
Binary files /dev/null and b/Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.pdf differ
diff --git a/Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.tex b/Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.tex
new file mode 100644
index 00000000000..8be4aa773d1
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.tex
@@ -0,0 +1,73 @@
+\iffalse meta-comment
+
+File l3syntax-changes.tex Copyright (C) 2011 The 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.
+
+\fi
+
+\documentclass{l3doc}
+
+\usepackage{svn-multi}
+
+\svnid{$Id: l3syntax-changes.tex 2626 2011-08-18 19:22:19Z joseph $}
+\def\filedate{\svnfileyear/\svnfilemonth/\svnfileday}
+
+\title{%
+  Syntax changes in \LaTeX3 functions
+    \thanks
+      {%
+        This file describes v\svnfilerev,
+        last revised \filedate.
+      }%
+}
+\author{%
+  The \LaTeX3 Project\thanks
+    {%
+      E-mail:
+      \href{mailto:latex-team@latex-project.org}%
+        {latex-team@latex-project.org}%
+    }%
+}
+\date{Released \filedate}
+
+\newcommand{\TF}{\textit{(TF)}}
+
+\begin{document}
+
+\maketitle
+
+This file lists functions whose syntax has changed after August 2011,
+with an approximate date.
+
+\section{August 2011}
+
+\begin{itemize}
+  \item \cs{tl_if_single:n\TF} recognized any non-zero number of
+    explicit spaces as \meta{true}, and did not ignore trailing spaces.
+    Now it is \meta{true} for
+    \[
+      \meta{optional spaces}
+      \meta{normal token or brace group}
+      \meta{optional spaces}.
+    \]
+  \item \cs{tl_reverse:n} stripped outer braces and lost unprotected spaces.
+    Now it keeps spaces, leaves unbraced single tokens unbraced, and
+    braced groups braced.
+  \item \cs{tl_trim_spaces:n} only removed one leading and trailing space.
+    Now removes recursively. Also, on the left it used to strip implicit
+    and explicit spaces with any character code. Now it strips only explicit
+    space characters $(32,10)$.
+  \end{itemize}
+
+\end{document}
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/l3kernel/source3.pdf b/Master/texmf-dist/doc/latex/l3kernel/source3.pdf
index cf5bd891a30..1a2a6307e59 100644
Binary files a/Master/texmf-dist/doc/latex/l3kernel/source3.pdf and b/Master/texmf-dist/doc/latex/l3kernel/source3.pdf differ
diff --git a/Master/texmf-dist/doc/latex/l3kernel/source3.tex b/Master/texmf-dist/doc/latex/l3kernel/source3.tex
new file mode 100644
index 00000000000..927e483cce9
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/l3kernel/source3.tex
@@ -0,0 +1,106 @@
+% \iffalse meta-comment
+%
+%% File: source3.tex Copyright (C) 1990-2011 The 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 LaTeX3 Project.
+%%
+%% -----------------------------------------------------------------------
+%
+% \fi
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% This document will typeset the LaTeX3 sources as a single document.
+% This will produce quite a large file (more than 400 pages).
+%
+% 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{%
+ The \LaTeX3 Project\thanks
+   {%
+     E-mail:
+       \href{mailto:latex-team@latex-project.org}
+         {latex-team@latex-project.org}%
+   }%
+}
+
+\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
+
+\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}
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/l3kernel/source3body.tex b/Master/texmf-dist/doc/latex/l3kernel/source3body.tex
new file mode 100644
index 00000000000..1caee5bd0e2
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/l3kernel/source3body.tex
@@ -0,0 +1,392 @@
+% \iffalse meta-comment
+%
+%% File: source3body.tex Copyright (C) 1990-2011 The 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 LaTeX3 Project.
+%%
+%% -----------------------------------------------------------------------
+%
+% \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 \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 
+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{coffin}] a \enquote{box with handles} --- a higher-level data
+     type for carrying out |box| alignment operations.
+  \item[\texttt{dim}] \enquote{Rigid} lengths.
+  \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 
+    (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 
+    writing to, respectively).
+  \item[\texttt{tl}] Token list variables: placeholder for a token list.
+\end{description}
+
+\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 
+\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 
+\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 
+\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 
+\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}
+(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 \enquote{user} name, this might read:
+\begin{function}{\ExplSyntaxOn, \ExplSyntaxOff}
+  \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 
+  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}
+    \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 
+  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}[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}, 
+  shorthand for a \meta{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 \enquote{true}/\enquote{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}[EXP,pTF]{\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 
+  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 
+  \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 \enquote{\textbf{\TeX{}hackers 
+note}} section:
+\begin{function}[EXP]{\token_to_str:N}
+  \begin{syntax}
+    \cs{token_to_str:N} \meta{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}
+
+\section{Formal language conventions which apply generally}
+
+As this is a formal reference guide for \LaTeX3 programming, the descriptions
+of functions are intended to be reasonably \enquote{complete}. However, there
+is also a need to avoid repetition. Formal ideas which apply to general
+classes of function are therefore summarised here.
+
+For tests which have a \texttt{TF} argument specification, the test if
+evaluated to give a logically \texttt{TRUE} or \texttt{FALSE} result.
+Depending on this result, either the \meta{true code} or the \meta{false code}
+will be left in the input stream. In the case where the test is expandable,
+and a predicate (|_p|) variant is available, the logical value determined by
+the test is left in the input stream: this will typically be part of a larger
+logical construct.
+
+\DisableImplementation
+
+\DocInput{l3bootstrap.dtx}
+\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{l3seq.dtx}
+\DocInput{l3clist.dtx}
+\DocInput{l3prop.dtx}
+\DocInput{l3box.dtx}
+\DocInput{l3io.dtx}
+\DocInput{l3msg.dtx}
+\DocInput{l3keys.dtx}
+\DocInput{l3file.dtx}
+\DocInput{l3fp.dtx}
+\DocInput{l3luatex.dtx}
+
+\endinput
-- 
cgit v1.2.3