[latex3-commits] [l3svn] r7121 - Document escaped characters in l3regex replacement [ci skip]

[noreply at latex-project.org]

Author: bruno
Date: 2017-04-25 04:24:19 +0200 (Tue, 25 Apr 2017)
New Revision: 7121

Modified:
   trunk/l3experimental/l3str/l3regex.dtx
Log:
Document escaped characters in l3regex replacement [ci skip]


Modified: trunk/l3experimental/l3str/l3regex.dtx
===================================================================
--- trunk/l3experimental/l3str/l3regex.dtx	2017-04-22 19:51:54 UTC (rev 7120)
+++ trunk/l3experimental/l3str/l3regex.dtx	2017-04-25 02:24:19 UTC (rev 7121)
@@ -352,17 +352,32 @@
 % \subsection{Syntax of the replacement text}
 %
 % Most of the features described in regular expressions do not make
-% sense within the replacement text.  Escaped characters are supported
-% as inside regular expressions.  The whole match is accessed as~|\0|,
-% and the first~$9$ submatches are accessed as |\1|, \ldots{},~|\9|.
-% Further submatches are accessed through |\g{|\meta{number}|}| where
-% \meta{number} is any non-negative integer.  If there are fewer than
-% \meta{number} capturing groups, the submatch is empty.
+% sense within the replacement text.  Backslash introduces various
+% special constructions:
+% \begin{itemize}
+%   \item |\0| is the whole match;
+%   \item |\1|, |\2|, \ldots{}, |\9| or |\g{|\meta{number}|}| are the
+%     submatches (empty if there are fewer than \meta{number} capturing
+%     groups);
+%   \item \verb*|\ | inserts a space (spaces are ignored when not
+%     escaped);
+%   \item |\a|, |\e|, |\f|, |\n|, |\r|, |\t|, |\xhh|, |\x{hhh}|
+%     correspond to single characters as in regular expressions;
+%   \item |\c|\Arg{cs~name} inserts a control sequence;
+%   \item |\c|\meta{category}\meta{character} (see below);
+%   \item |\u|\Arg{tl~var~name} inserts the contents of the
+%     \meta{tl~var} (see below).
+% \end{itemize}
+% Characters other than backslash and space are simply inserted in the
+% result (but since the replacement text is first converted to a string,
+% one should also escape characters that are special for \TeX{}, for
+% instance use~|\#|).  Non-alphanumeric characters can always be safely
+% escaped with a backslash.
 %
 % For instance,
 % \begin{verbatim}
 %   \tl_set:Nn \l_my_tl { Hello,~world! }
-%   \regex_replace_all:nnN { ([er]?l|o) . } { \(\0\-\-\1\) } \l_my_tl
+%   \regex_replace_all:nnN { ([er]?l|o) . } { (\0--\1) } \l_my_tl
 % \end{verbatim}
 % results in \cs{l_my_tl} holding |H(ell--el)(o,--o) w(or--o)(ld--l)!|
 %
@@ -375,12 +390,11 @@
 % with arbitrary category codes, as well as control sequences.
 % \begin{l3regex-syntax}
 % \item[\\cXY] Produces the character~|Y| (which can be given as an
-%   escape sequence such as~|\t| for tab, or |\(| or~|\)| for a
-%   parenthesis) with category code~|X|, which must be one of
-%   |CBEMTPUDSLOA|.
+%   escape sequence such as~|\t| for tab) with category code~|X|, which
+%   must be one of |CBEMTPUDSLOA| as in regular expressions.
 % \item[\\c\Arg{text}] Produces the control sequence with csname
 %   \meta{text}.  The \meta{text} may contain references to the
-%   submatches |\0|, |\1|, \emph{etc.}
+%   submatches |\0|, |\1|, and so on, as in the example for |\u| below.
 % \end{l3regex-syntax}
 %
 % The escape sequence |\u|\Arg{tl~var~name} allows to insert the