summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/l3kernel
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/l3kernel')
-rw-r--r--Master/texmf-dist/doc/latex/l3kernel/expl3.pdfbin674529 -> 674812 bytes
-rw-r--r--Master/texmf-dist/doc/latex/l3kernel/interface3.pdfbin1261021 -> 1269105 bytes
-rw-r--r--Master/texmf-dist/doc/latex/l3kernel/interface3.tex89
-rw-r--r--Master/texmf-dist/doc/latex/l3kernel/l3docstrip.pdfbin449457 -> 393836 bytes
-rw-r--r--Master/texmf-dist/doc/latex/l3kernel/l3styleguide.pdfbin273207 -> 273213 bytes
-rw-r--r--Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex242
-rw-r--r--Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.pdfbin220205 -> 220212 bytes
-rw-r--r--Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.tex110
-rw-r--r--Master/texmf-dist/doc/latex/l3kernel/source3.pdfbin3875910 -> 3871245 bytes
-rw-r--r--Master/texmf-dist/doc/latex/l3kernel/source3.tex106
-rw-r--r--Master/texmf-dist/doc/latex/l3kernel/source3body.tex448
11 files changed, 0 insertions, 995 deletions
diff --git a/Master/texmf-dist/doc/latex/l3kernel/expl3.pdf b/Master/texmf-dist/doc/latex/l3kernel/expl3.pdf
index 820c38f6400..77eb63f6116 100644
--- a/Master/texmf-dist/doc/latex/l3kernel/expl3.pdf
+++ b/Master/texmf-dist/doc/latex/l3kernel/expl3.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/l3kernel/interface3.pdf b/Master/texmf-dist/doc/latex/l3kernel/interface3.pdf
index 0de151d8703..cec74ab1a1c 100644
--- a/Master/texmf-dist/doc/latex/l3kernel/interface3.pdf
+++ b/Master/texmf-dist/doc/latex/l3kernel/interface3.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/l3kernel/interface3.tex b/Master/texmf-dist/doc/latex/l3kernel/interface3.tex
deleted file mode 100644
index 4c0a2761e92..00000000000
--- a/Master/texmf-dist/doc/latex/l3kernel/interface3.tex
+++ /dev/null
@@ -1,89 +0,0 @@
-% \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 "l3kernel bundle" (The Work in LPPL)
-%% and all files in that bundle must be distributed together.
-%%
-%% The released version of this bundle is available from CTAN.
-%%
-%% -----------------------------------------------------------------------
-%%
-%% 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/l3docstrip.pdf b/Master/texmf-dist/doc/latex/l3kernel/l3docstrip.pdf
index 0bd4285bf37..37e876db28b 100644
--- a/Master/texmf-dist/doc/latex/l3kernel/l3docstrip.pdf
+++ b/Master/texmf-dist/doc/latex/l3kernel/l3docstrip.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.pdf b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.pdf
index ec18c58a785..82960bc1a10 100644
--- a/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.pdf
+++ b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex b/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex
deleted file mode 100644
index 6a3a9d122e6..00000000000
--- a/Master/texmf-dist/doc/latex/l3kernel/l3styleguide.tex
+++ /dev/null
@@ -1,242 +0,0 @@
-\iffalse meta-comment
-
-File l3styleguide.tex Copyright (C) 2011,2012 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 "l3kernel bundle" (The Work in LPPL)
-and all files in that bundle must be distributed together.
-
-The released version of this bundle is available from CTAN.
-
-\fi
-
-\documentclass{l3doc}
-\usepackage{svn-multi}
-
-\svnid{$Id: l3styleguide.tex 2772 2011-09-07 15:07:41Z 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: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}
-
-All code-level functions should be \enquote{long} if they accept any
-arguments, even if it seems \enquote{very unlikely} that a \cs{par} token
-will be passed. Thus \cs{cs_new_nopar:Npn} and so forth should only be used
-to create functions which accept no arguments at all.
-
-The expandability of each function should be well-defined. Functions which
-cannot be fully expanded must be \texttt{protected}. This means that expandable
-functions must themselves only contain expandable material. Functions which
-use any non-expandable material must be defined using \cs{cs_new_protected:Npn}
-or similar.
-
-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.
-
-\section{Private and internal functions}
-
-Private functions (those starting \cs{__}) should not be used between modules.
-The only exception is where a \enquote{family} of modules share some
-\enquote{internal} methods: this happens most obviously in the kernel itself.
-Any internal functions or variables \emph{must} be documented in the same way
-as public ones.
-
-The \pkg{l3docstrip} method should be used for internal functions in a module.
-This requires a line
-\begin{quote}
- \ttfamily
- \%<@@=\meta{module}>
-\end{quote}
-at the start of the source (\texttt{.dtx}) file, with internal functions
-then written in the form
-\begin{verbatim}
- \cs_new_protected:Npn \@@_function:nn #1#2
- ...
-\end{verbatim}
-
-\section{Auxiliary functions}
-
-In general, the team encourage the use of descriptive names in \LaTeX3 code.
-Thus many helper functions will have names which describe briefly what they do,
-rather than simply indicating that they are auxiliary to some higher-level
-function. However, there are places where one or more \texttt{aux} functions
-are required. Where possible, these should be differentiated by signature
-\begin{verbatim}
- \cs_new_protected:Npn \@@_function:nn #1#2
- {
- ...
- }
- \cs_new_protected:Npn \@@_function_aux:nn #1#2
- {
- ...
- }
- \cs_new_protected:Npn \@@_function_aux:w #1#2 \q_stop
- {
- ...
- }
-\end{verbatim}
-Where more than one auxiliary shares the same signature, the recommended naming
-scheme is \texttt{auxi}, \texttt{auxii} and so on.
-\begin{verbatim}
- \cs_new_protected:Npn \@@_function_auxi:nn #1#2
- {
- ...
- }
- \cs_new_protected:Npn \@@_function_auxii:nn #1#2
- {
- ...
- }
-\end{verbatim}
-The use of \texttt{aux_i}, \texttt{aux_ii}, \emph{etc.}\ is discouraged as this
-conflicts with the convention used by \cs{use_i:nn} and related functions.
-
-\end{document}
diff --git a/Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.pdf b/Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.pdf
index 8e6903f95a5..2b7d6cc8b35 100644
--- a/Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.pdf
+++ b/Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.tex b/Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.tex
deleted file mode 100644
index 4dfc70e0e97..00000000000
--- a/Master/texmf-dist/doc/latex/l3kernel/l3syntax-changes.tex
+++ /dev/null
@@ -1,110 +0,0 @@
-\iffalse meta-comment
-
-File l3syntax-changes.tex Copyright (C) 2011-2012 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 "l3kernel bundle" (The Work in LPPL)
-and all files in that bundle must be distributed together.
-
-The released version of this bundle is available from CTAN.
-
-\fi
-
-\documentclass{l3doc}
-
-\usepackage{svn-multi}
-
-\svnid{$Id: l3syntax-changes.tex 4048 2012-08-02 09:49:10Z 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}
-
-\section{September 2011}
-
-\begin{itemize}
-\item clist functions which receive an \texttt{n}-type comma list argument
- now trim spaces from each item in the argument.
-\end{itemize}
-
-\section{June 2012}
-
-\begin{itemize}
- \item Access to list functions now indexes from~$1$, not from~$0$.
- This applies to multiple choices in the \pkg{l3keys} module and
- the \cs{clist_item:Nn}, \cs{seq_item:Nn} and \cs{tl_item:Nn}
- functions.
- \item \cs{tl_trim_spaces:n} now requires a variable number of
- expansions to fully expand, rather than exactly two. Of course,
- \texttt{x}-type expansion still correctly evaluates this function.
-\end{itemize}
-
-\section{July 2012}
-
-\begin{itemize}
- \item The \cs{tl_if_head_eq_meaning:nN}, \cs{tl_if_head_eq_catcode:nN}
- and \cs{tl_if_head_eq_charcode:nN} conditionals now never match when
- their first argument is empty.
-\end{itemize}
-
-\section{August 2012}
-
-\begin{itemize}
- \item \cs{lua_now:x} is now a standard \texttt{x}-type expansion of
- \cs{lua_now:n}, which does no expansion. Engine-level expansion is moved
- to \cs{lua_now_x:n}, reflecting the fact that this is non-standard in the
- same way as for example \cs{str_if_eq_x:nn(TF)}.
-\end{itemize}
-
-
-\end{document}
diff --git a/Master/texmf-dist/doc/latex/l3kernel/source3.pdf b/Master/texmf-dist/doc/latex/l3kernel/source3.pdf
index 3821467a59e..b46ea2254f9 100644
--- a/Master/texmf-dist/doc/latex/l3kernel/source3.pdf
+++ b/Master/texmf-dist/doc/latex/l3kernel/source3.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/l3kernel/source3.tex b/Master/texmf-dist/doc/latex/l3kernel/source3.tex
deleted file mode 100644
index 22c3c44048d..00000000000
--- a/Master/texmf-dist/doc/latex/l3kernel/source3.tex
+++ /dev/null
@@ -1,106 +0,0 @@
-% \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 "l3kernel bundle" (The Work in LPPL)
-%% and all files in that bundle must be distributed together.
-%%
-%% The released version of this bundle is available from CTAN.
-%%
-%% -----------------------------------------------------------------------
-%%
-%% 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 780 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}
diff --git a/Master/texmf-dist/doc/latex/l3kernel/source3body.tex b/Master/texmf-dist/doc/latex/l3kernel/source3body.tex
deleted file mode 100644
index c5dbc33a7b3..00000000000
--- a/Master/texmf-dist/doc/latex/l3kernel/source3body.tex
+++ /dev/null
@@ -1,448 +0,0 @@
-% \iffalse meta-comment
-%
-%% File: source3body.tex Copyright (C) 1990-2012 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 "l3kernel bundle" (The Work in LPPL)
-%% and all files in that bundle must be distributed together.
-%%
-%% The released version of this bundle is available from CTAN.
-%%
-%% -----------------------------------------------------------------------
-%%
-%% 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{\clearpage\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 through 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}: every token in the argument is fully expanded until only
- unexpandable ones remain. The \TeX{} \tn{edef} primitive carries out
- this type of expansion. Functions which feature an \texttt{x}-type
- argument are in general \emph{not} expandable, unless specifically
- noted.
- \item[\texttt{f}] The \texttt{f} specifier stands for \emph{full
- expansion}, and in contrast to \texttt{x} stops at the first
- non-expandable item (reading the argument from left to right) without
- trying to expand it. For example, when setting a token list
- variable (a macro used for storage), the sequence
- \begin{verbatim}
- \tl_set:Nn \l_mya_tl { A }
- \tl_set:Nn \l_myb_tl { B }
- \tl_set:Nf \l_mya_tl { \l_mya_tl \l_myb_tl }
- \end{verbatim}
- will leave |\l_mya_tl| with the content |A\l_myb_tl|, as |A| cannot
- be expanded and so terminates expansion before |\l_myb_tl| is considered.
- \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}
-
-\paragraph{Fully expandable functions}
-\hypertarget{expstar}{Some functions are fully expandable},
-which allows it to be used within
-an \texttt{x}-type argument (in plain \TeX{} terms, inside an \cs{edef}),
-as well as within an \texttt{f}-type argument.
-These fully expandable functions are indicated in the documentation by
-a star:
-\begin{function}[EXP]{\cs_to_str:N}
- \begin{syntax}
- \cs{cs_to_str:N} \meta{cs}
- \end{syntax}
- As with other functions, some text should follow which explains how
- the function works. Usually, only the star will indicate that the
- function is expandable. In this case, the function expects a \meta{cs},
- shorthand for a \meta{control sequence}.
-\end{function}
-
-\paragraph{Restricted expandable functions}
-\hypertarget{rexpstar}{A few functions are fully expandable} but cannot be fully expanded within
-an \texttt{f}-type argument. In this case a hollow star is used to indicate
-this:
-\begin{function}[rEXP]{\seq_map_function:NN}
- \begin{syntax}
- \cs{seq_map_function:NN} \meta{seq} \meta{function}
- \end{syntax}
-\end{function}
-
-\paragraph{Conditional functions}
-\hypertarget{explTF}{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,TF]{\xetex_if_engine:}
- \begin{syntax}
- \cs{xetex_if_engine:TF} \Arg{true code} \Arg{false code}
- \end{syntax}
- The underlining and italic of \texttt{TF} indicates that
- \cs{xetex_if_engine:T}, \cs{xetex_if_engine:F} and
- \cs{xetex_if_engine:TF} are all available. Usually, the illustration
- 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.
-
-\section{\TeX{} concepts not supported by \LaTeX3{}}
-
-The \TeX{} concept of an \enquote{\cs{outer}} macro is \emph{not supported}
-at all by \LaTeX3{}. As such, the functions provided here may break when
-used on top of \LaTeXe{} if \cs{outer} tokens are used in the arguments.
-
-\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{l3coffins.dtx}
-\DocInput{l3color.dtx}
-\DocInput{l3msg.dtx}
-\DocInput{l3keys.dtx}
-\DocInput{l3file.dtx}
-\DocInput{l3fp.dtx}
-% To get the various submodules of l3fp to appear in the implementation
-% part only, they have to be added to the documentation list after typesetting
-% the 'user' part just for the main module.
-\ExplSyntaxOn
-\clist_gput_right:Nn \g_docinput_clist
- {
- l3fp-aux.dtx ,
- l3fp-traps.dtx ,
- l3fp-round.dtx ,
- l3fp-parse.dtx ,
- l3fp-logic.dtx ,
- l3fp-basics.dtx ,
- l3fp-extended.dtx ,
- l3fp-expo.dtx ,
- l3fp-trig.dtx ,
- l3fp-convert.dtx ,
- l3fp-assign.dtx ,
- l3fp-old.dtx ,
- }
-\ExplSyntaxOff
-\DocInput{l3luatex.dtx}
-
-\DocInput{l3candidates.dtx}
-
-\endinput