summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3str.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3str.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3str.dtx56
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