l3 (15jul17)

git-svn-id: svn://tug.org/texlive/trunk@44813 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 32 insertions, 24 deletions

diff --git a/Master/texmf-dist/source/latex/l3kernel/l3str.dtx b/Master/texmf-dist/source/latex/l3kernel/l3str.dtx
index 3739bc8a766..1642d85a1ee 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3str.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3str.dtx
@@ -41,7 +41,7 @@
 %    }^^A
 % }
 %
-% \date{Released 2017/05/29}
+% \date{Released 2017/07/15}
 %
 % \maketitle
 %
@@ -57,7 +57,7 @@
 % which have category code $12$ (\enquote{other}) with the exception of
 % space characters which have category code $10$ (\enquote{space}). Thus
 % at a technical level, a \TeX{} string is a token list with the appropriate
-% category codes. In this documentation, these will simply be referred to as
+% category codes. In this documentation, these are simply referred to as
 % strings.
 %
 % String variables are simply specialised token lists, but by convention
@@ -66,15 +66,22 @@
 % spaces, which have category code $10$ (blank space).  All the
 % functions in this module which accept a token list argument first
 % convert it to a string using \cs{tl_to_str:n} for internal processing,
-% and will not treat a token list or the corresponding string
+% and do not treat a token list or the corresponding string
 % representation differently.
 %
+% As a string is a subset of the more general token list, it is sometimes unclear
+% when one should be used over the other.
+% Use a string variable for data that isn’t primarily intended for typesetting
+% and for which a level of protection from unwanted expansion is suitable.
+% This data type simplifies comparison of variables since there are no concerns
+% about expansion of their contents.
+%
 % Note that as string variables are a special case of token list variables
 % the coverage of \cs[no-index]{str_\ldots{}:N} functions is somewhat smaller than
 % \cs[no-index]{tl_\ldots{}:N}.
 %
 % The functions \cs{cs_to_str:N}, \cs{tl_to_str:n}, \cs{tl_to_str:N} and
-% \cs{token_to_str:N} (and variants) will generate strings from the appropriate
+% \cs{token_to_str:N} (and variants) generate strings from the appropriate
 % input: these are documented in \pkg{l3basics}, \pkg{l3tl} and \pkg{l3token},
 % respectively.
 %
@@ -97,8 +104,8 @@
 %     \cs{str_new:N} \meta{str~var}
 %   \end{syntax}
 %   Creates a new \meta{str~var} or raises an error if the name is
-%   already taken.  The declaration is global.  The \meta{str~var} will
-%   initially be empty.
+%   already taken.  The declaration is global.  The \meta{str~var} is
+%   initially empty.
 % \end{function}
 %
 % \begin{function}[added = 2015-09-18]
@@ -107,7 +114,7 @@
 %     \cs{str_const:Nn} \meta{str~var} \Arg{token list}
 %   \end{syntax}
 %   Creates a new constant \meta{str~var} or raises an error if the name
-%   is already taken.  The value of the \meta{str~var} will be set
+%   is already taken.  The value of the \meta{str~var} is set
 %   globally to the \meta{token list}, converted to a string.
 % \end{function}
 %
@@ -200,7 +207,7 @@
 % \begin{function}[EXP,pTF, added = 2015-09-18]
 %   {\str_if_empty:N, \str_if_empty:c}
 %   \begin{syntax}
-%     \cs{sr_if_empty_p:N} \meta{str~var}
+%     \cs{str_if_empty_p:N} \meta{str~var}
 %     \cs{str_if_empty:NTF} \meta{str~var} \Arg{true code} \Arg{false code}
 %   \end{syntax}
 %   Tests if the \meta{string variable} is entirely empty
@@ -264,8 +271,8 @@
 %   \end{syntax}
 %   This function compares the \meta{test string} in turn with each
 %   of the \meta{string cases}. If the two are equal (as described for
-%   \cs{str_if_eq:nnTF} then the
-%   associated \meta{code} is left in the input stream. If any of the
+%   \cs{str_if_eq:nnTF} then the associated \meta{code} is left in the
+%   input stream and other cases are discarded. If any of the
 %   cases are matched, the \meta{true code} is also inserted into the
 %   input stream (after the code for the appropriate case), while if none
 %   match then the \meta{false code} is inserted. The function
@@ -288,7 +295,8 @@
 %   This function compares the full expansion of the \meta{test string}
 %   in turn with the full expansion of the \meta{string cases}. If the two
 %   full expansions are equal (as described for \cs{str_if_eq:nnTF} then the
-%   associated \meta{code} is left in the input stream.  If any of the
+%   associated \meta{code} is left in the input stream
+%   and other cases are discarded.  If any of the
 %   cases are matched, the \meta{true code} is also inserted into the
 %   input stream (after the code for the appropriate case), while if none
 %   match then the \meta{false code} is inserted. The function
@@ -306,7 +314,7 @@
 %     \cs{str_use:N} \meta{str~var}
 %   \end{syntax}
 %   Recovers the content of a \meta{str~var} and places it
-%   directly in the input stream. An error will be raised if the variable
+%   directly in the input stream. An error is raised if the variable
 %   does not exist or if it is invalid. Note that it is possible to use
 %   a \meta{str} directly without an accessor function.
 % \end{function}
@@ -361,7 +369,7 @@
 %   character, and leaves the remaining characters (if any) in the input
 %   stream, with category codes $12$ and $10$ (for spaces).  The
 %   functions differ in the case where the first character is a space:
-%   \cs{str_tail:N} and \cs{str_tail:n} will trim only that space, while
+%   \cs{str_tail:N} and \cs{str_tail:n} only trim that space, while
 %   \cs{str_tail_ignore_spaces:n} removes the first non-space character
 %   and any space before it.  If the \meta{token list} is empty (or
 %   blank in the case of the \texttt{_ignore_spaces} variant), then
@@ -405,7 +413,7 @@
 %     \iow_term:x { \str_range:nnn { abcdef } { -2 } { -1 } }
 %     \iow_term:x { \str_range:nnn { abcdef } { 0 } { -1 } }
 %   \end{verbatim}
-%   will print \texttt{bcde}, \texttt{cdef}, \texttt{ef}, and an empty
+%   prints \texttt{bcde}, \texttt{cdef}, \texttt{ef}, and an empty
 %   line to the terminal. The \meta{start index} must always be smaller than
 %   or equal to the \meta{end index}: if this is not the case then no output
 %   is generated. Thus
@@ -470,7 +478,7 @@
 %     As with all \pkg{expl3} functions, the input supported by
 %     \cs{str_fold_case:n} is \emph{engine-native} characters which are or
 %     interoperate with \textsc{utf-8}. As such, when used with \pdfTeX{}
-%     \emph{only} the Latin alphabet characters A--Z will be case-folded
+%     \emph{only} the Latin alphabet characters A--Z are case-folded
 %     (\emph{i.e.}~the \textsc{ascii} range which coincides with
 %     \textsc{utf-8}). Full \textsc{utf-8} support is available with both
 %     \XeTeX{} and \LuaTeX{}, subject only to the fact that \XeTeX{} in
@@ -514,7 +522,7 @@
 %     As with all \pkg{expl3} functions, the input supported by
 %     \cs{str_fold_case:n} is \emph{engine-native} characters which are or
 %     interoperate with \textsc{utf-8}. As such, when used with \pdfTeX{}
-%     \emph{only} the Latin alphabet characters A--Z will be case-folded
+%     \emph{only} the Latin alphabet characters A--Z are case-folded
 %     (\emph{i.e.}~the \textsc{ascii} range which coincides with
 %     \textsc{utf-8}). Full \textsc{utf-8} support is available with both
 %     \XeTeX{} and \LuaTeX{}, subject only to the fact that \XeTeX{} in
@@ -765,7 +773,7 @@
 %   spaces are not skipped for ease-of-input. The need to detokenize and force
 %   expansion of input arises from the case where a |#| token is used in the
 %   input, \emph{e.g.}~|\__str_if_eq_x:nn {#} { \tl_to_str:n {#} }|, which
-%   otherwise will fail as \cs{luatex_luaescapestring:D} does not double
+%   otherwise would fail as \cs{luatex_luaescapestring:D} does not double
 %   such tokens.
 %    \begin{macrocode}
 \cs_new:Npn \@@_if_eq_x:nn #1#2 { \pdftex_strcmp:D {#1} {#2} }
@@ -1203,7 +1211,7 @@
 %   trick again, so that the $8$ first arguments of
 %   \cs{@@_collect_end:nnnnnnnnw} are some \cs{or:}, followed by an
 %   \cs{fi:}, followed by |#1| characters from the input stream. Simply
-%   leaving this in the input stream will close the conditional properly
+%   leaving this in the input stream closes the conditional properly
 %   and the \cs{or:} disappear.
 %    \begin{macrocode}
 \cs_new:Npn \@@_collect_delimit_by_q_stop:w #1;
@@ -1613,7 +1621,7 @@
 % Set up to read each file. As they use C-style comments, there is a need to
 % deal with |#|. At the same time, spaces are important so they need to be
 % picked up as they are important. Beyond that, the current category code
-% scheme works fine. With no I/O loop available, hard-code one that will work
+% scheme works fine. With no I/O loop available, hard-code one that works
 % quickly.
 %    \begin{macrocode}
   \cs_set_protected:Npn \@@_map_inline:n #1
@@ -1664,8 +1672,8 @@
     }
 %    \end{macrocode}
 % Storing each exception is always done in the same way: create a constant
-% token list which expands to exactly the mapping. These will have the
-% category codes \enquote{now} (so should be letters) but will be detokenized
+% token list which expands to exactly the mapping. These have the
+% category codes \enquote{now} (so should be letters) but are later detokenized
 % for string use.
 %    \begin{macrocode}
   \cs_set_protected:Npn \@@_store:nnnnn #1#2#3#4#5
@@ -1680,7 +1688,7 @@
     }
 %    \end{macrocode}   
 % Parse the main Unicode data file for title case exceptions (the one-to-one
-% lower and upper case mappings it contains will all be covered by the \TeX{}
+% lower and upper case mappings it contains are all be covered by the \TeX{}
 % data).
 %    \begin{macrocode}
   \cs_set_protected:Npn \@@_parse_auxi:w
@@ -1694,7 +1702,7 @@
           \if_int_compare:w \__str_if_eq_x:nn { #5 ~ } {#7} = 0 \exp_stop_f:
           \else:
             \tl_const:cx
-              { c_@@_title_ \utex_char:D "#1 _tl }
+              { c_@@_mixed_ \utex_char:D "#1 _tl }
               { \utex_char:D "#7 }
           \fi:
         }
@@ -1734,7 +1742,7 @@
       \use:n { \@@_parse_auxii:w #1 ~ upper ~ #4 ~ } ~ \q_stop
       \if_int_compare:w \__str_if_eq_x:nn {#3} {#4} = 0 \exp_stop_f:
       \else:
-        \use:n { \@@_parse_auxii:w #1 ~ title ~ #3 ~ } ~ \q_stop
+        \use:n { \@@_parse_auxii:w #1 ~ mixed ~ #3 ~ } ~ \q_stop
       \fi:
     }
   \cs_set_protected:Npn \@@_parse_auxii:w #1 ~ #2 ~ #3 ~ #4 ~ #5 \q_stop