[latex3-commits] [l3svn] branch master updated: Document formal definition of <space token> [ci skip]

[noreply at latex-project.org]

This is an automated email from the git hooks/post-receive script.

joseph pushed a commit to branch master
in repository l3svn.

The following commit(s) were added to refs/heads/master by this push:
       new  2b627e1   Document formal definition of <space token> [ci skip]
2b627e1 is described below

commit 2b627e1d0acb1a708308e52b02414e07ff64f528
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Tue Sep 26 18:58:10 2017 +0100

    Document formal definition of <space token> [ci skip]
    
    Hopefully this is accurate without repetition: a <space token> is defined and
    used where this is appropriate.
---
 l3kernel/l3tl.dtx |   68 +++++++++++++++++++++++++++++++----------------------
 1 file changed, 40 insertions(+), 28 deletions(-)

diff --git a/l3kernel/l3tl.dtx b/l3kernel/l3tl.dtx
index eb411a3..7656be8 100644
--- a/l3kernel/l3tl.dtx
+++ b/l3kernel/l3tl.dtx
@@ -84,6 +84,27 @@
 % Functions which act on items are often faster than their analogue acting
 % directly on tokens.
 %
+% \section{Space tokens}
+%
+% During tokenization, \TeX{} normalises the representation of spaces.
+% Any character with category code $10$ will be normalised to \verb*| |
+% (character code $32$) as part of tokenization: the result is a
+% \meta{space token}. In the following descriptions, \meta{space token}
+% \emph{always} refers to such normalised values.
+%
+% Explicit \meta{space tokens} are ignored in a number of contexts: at the start
+% of input lines, after function and variable names, when absorbing undelimited
+% arguments, and in mappings and functions which use mappings, such as
+% \cs{tl_count:n}. Note this does not apply to implicit \meta{space tokens}
+% (\cs{c_space_token} or equivalent).
+%
+% \begin{texnote}
+%   In \pkg{expl3} there is no interface for generating \enquote{funny spaces},
+%   that is category code $10$ tokens but with character code not equal to $32$.
+%   Where such tokens are generated by other code, they will not be treated as
+%   \meta{space tokens} as used in the following definitions.
+%  \end{texnote}
+%
 % \section{Creating and initialising token list variables}
 %
 % \begin{function}{\tl_new:N, \tl_new:c}
@@ -358,10 +379,9 @@
 %     \cs{tl_if_blank_p:n} \Arg{token list}
 %     \cs{tl_if_blank:nTF} \Arg{token list} \Arg{true code} \Arg{false code}
 %   \end{syntax}
-%   Tests if the \meta{token list} consists only of blank spaces
+%   Tests if the \meta{token list} consists only of explicit \meta{space tokens}
 %   (\emph{i.e.}~contains no item). The test is \texttt{true} if
-%   \meta{token list} is zero or more space characters
-%   (explicit character tokens with category code~$10$),
+%   \meta{token list} is zero or more explicit \meta{space tokens},
 %   and is \texttt{false} otherwise.
 % \end{function}
 %
@@ -440,10 +460,10 @@
 %     \cs{tl_if_single:NTF} \meta{tl~var} \Arg{true code} \Arg{false code}
 %   \end{syntax}
 %   Tests if the content of the \meta{tl~var} consists of a single item,
-%   \emph{i.e.}~is a single normal token (neither an explicit space
-%   character nor a begin-group character) or a single brace group,
-%   surrounded by optional spaces on both sides. In other words, such a
-%   token list has token count $1$ according to \cs{tl_count:N}.
+%   \emph{i.e.}~is a single normal token (neither an explicit \meta{space
+%   token} nor a begin-group character) or a single brace group,
+%   surrounded by optional \meta{space tokens} on both sides. In other words,
+%   such a token list has token count $1$ according to \cs{tl_count:N}.
 % \end{function}
 %
 % \begin{function}[updated = 2011-08-13, EXP,pTF]{\tl_if_single:n}
@@ -452,10 +472,10 @@
 %     \cs{tl_if_single:nTF} \Arg{token list} \Arg{true code} \Arg{false code}
 %   \end{syntax}
 %   Tests if the \meta{token list} has exactly one item, \emph{i.e.}~is
-%   a single normal token (neither an explicit space character nor a
+%   a single normal token (neither an explicit \meta{space token} nor a
 %   begin-group character) or a single brace group, surrounded by
-%   optional spaces on both sides. In other words, such a token list has
-%   token count $1$ according to \cs{tl_count:n}.
+%   optional \meta{space tokens} on both sides. In other words, such a token
+%   list has token count $1$ according to \cs{tl_count:n}.
 % \end{function}
 %
 % \begin{function}[added = 2013-07-24, EXP, noTF]{\tl_case:Nn, \tl_case:cn}
@@ -751,8 +771,7 @@
 %   \begin{syntax}
 %     \cs{tl_trim_spaces:n} \Arg{token list}
 %   \end{syntax}
-%   Removes any leading and trailing  space characters
-%   (explicit character tokens with category code~$10$)
+%   Removes any leading and trailing explicit \meta{space tokens}
 %   from the \meta{token list} and leaves the result in the input
 %   stream.
 %   \begin{texnote}
@@ -770,8 +789,7 @@
 %   \begin{syntax}
 %     \cs{tl_trim_spaces:N} \meta{tl~var}
 %   \end{syntax}
-%   Removes any leading and trailing space characters
-%   (explicit character tokens with category code~$10$)
+%   Removes any leading and trailing explicit \meta{space tokens}
 %   from the content of the \meta{tl~var}. Note that this therefore
 %   \emph{resets} the content of the variable.
 % \end{function}
@@ -817,9 +835,7 @@
 %   \end{syntax}
 %   Leaves in the input stream the first \meta{item} in the
 %   \meta{token list}, discarding the rest of the \meta{token list}.
-%   All leading space characters (explicit character tokens with
-%   category code~$10$)
-%   are discarded; for example
+%   All leading explicit \meta{space tokens} are discarded; for example
 %   \begin{verbatim}
 %     \tl_head:n { abc }
 %   \end{verbatim}
@@ -849,10 +865,9 @@
 %   \end{syntax}
 %   Leaves in the input stream the first \meta{item} in the
 %   \meta{token list}, discarding the rest of the \meta{token list}.
-%   All leading space characters
-%   (explicit character tokens with category code~$10$)
-%   are discarded.
-%   A blank \meta{token list} (which consists only of space characters)
+%   All leading explicit \meta{space tokens} are discarded.
+%   A blank \meta{token list} (which consists only of explicit
+%   \meta{space tokens})
 %   results in a low-level \TeX{} error, which may be avoided by the
 %   inclusion of an empty group in the input (as shown), without the need
 %   for an explicit test. Alternatively, \cs{tl_if_blank:nF} may be used to
@@ -867,8 +882,7 @@
 %   \begin{syntax}
 %     \cs{tl_tail:n} \Arg{token list}
 %   \end{syntax}
-%   Discards all leading space characters
-%   (explicit character tokens with category code~$10$)
+%   Discards all leading explicit \meta{space tokens}
 %   and the first \meta{item} in the \meta{token list}, and leaves the
 %   remaining tokens in the input stream.  Thus for example
 %   \begin{verbatim}
@@ -944,8 +958,7 @@
 %   \end{syntax}
 %   Tests if the first \meta{token} in the \meta{token list}
 %   is a normal \texttt{N}-type argument. In other words,
-%   it is neither an explicit space character
-%   (token with category code~$10$)
+%   it is neither an explicit \meta{space token}
 %   nor an explicit begin-group character
 %   (with category code~1 and any character code). An empty
 %   argument yields \texttt{false}, as it does not have a \enquote{normal}
@@ -960,8 +973,7 @@
 %     \cs{tl_if_head_is_space:nTF} \Arg{token list} \Arg{true code} \Arg{false code}
 %   \end{syntax}
 %   Tests if the first \meta{token} in the \meta{token list}
-%   is an explicit space character
-%   (token with category code~$10$).
+%   is an explicit \meta{space token}.
 %   In particular, the test is \texttt{false} if the \meta{token list}
 %   starts with an implicit token such as \cs{c_space_token}, or if it
 %   is empty.
@@ -1037,7 +1049,7 @@
 % \end{variable}
 %
 % \begin{variable}{\c_space_tl}
-%   An explicit space character contained in a token list (compare this with
+%   An explicit \meta{space token} contained in a token list (compare this with
 %   \cs{c_space_token}). For use where an explicit space is required.
 % \end{variable}
 %

-- 
To stop receiving notification emails like this one, please contact
the administrator of this repository.