[latex3-commits] [git/LaTeX3-latex3-latex3] gh1010-doc: Clarify documentation of \regex_const:Nn (fixes #997) (eb321a811)

[Bruno Le Floch]

Repository : https://github.com/latex3/latex3
On branch  : gh1010-doc
Link       : https://github.com/latex3/latex3/commit/eb321a8115001cccd8b69682557ffe1376c8be75

>---------------------------------------------------------------

commit eb321a8115001cccd8b69682557ffe1376c8be75
Author: Bruno Le Floch <blflatex at gmail.com>
Date:   Mon Nov 1 21:31:31 2021 +0100

    Clarify documentation of \regex_const:Nn (fixes #997)


>---------------------------------------------------------------

eb321a8115001cccd8b69682557ffe1376c8be75
 l3kernel/l3regex.dtx | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/l3kernel/l3regex.dtx b/l3kernel/l3regex.dtx
index 7ea7dab33..520127ae7 100644
--- a/l3kernel/l3regex.dtx
+++ b/l3kernel/l3regex.dtx
@@ -83,11 +83,12 @@
 %
 % If a regular expression is to be used several times,
 % it can be compiled once, and stored in a regex
-% variable using \cs{regex_const:Nn}. For example,
+% variable using \cs{regex_set:Nn}. For example,
 % \begin{verbatim}
-%   \regex_const:Nn \c_foo_regex { \c{begin} \cB. (\c[^BE].*) \cE. }
+%   \regex_new:N \l_foo_regex
+%   \regex_set:Nn \l_foo_regex { \c{begin} \cB. (\c[^BE].*) \cE. }
 % \end{verbatim}
-% stores in \cs[no-index]{c_foo_regex} a regular expression which matches the
+% stores in \cs[no-index]{l_foo_regex} a regular expression which matches the
 % starting marker for an environment: \cs[no-index]{begin}, followed by a
 % begin-group token (|\cB.|), then any number of tokens which are
 % neither begin-group nor end-group character tokens (|\c[^BE].*|),
@@ -531,21 +532,27 @@
 %   \meta{regex~var} is initially such that it never matches.
 % \end{function}
 %
-% \begin{function}[added = 2017-05-26]
-%   {\regex_set:Nn, \regex_gset:Nn, \regex_const:Nn}
+% \begin{function}[added = 2017-05-26]{\regex_set:Nn, \regex_gset:Nn}
 %   \begin{syntax}
 %     \cs{regex_set:Nn} \meta{regex~var} \Arg{regex}
 %   \end{syntax}
-%   Stores a compiled version of the \meta{regular expression}
-%   in the \meta{regex~var}. For instance, this function can be used
-%   as
+%   Stores a compiled version of the \meta{regular expression} in the
+%   \meta{regex~var}. The assignment is local for \cs{regex_set:Nn} and
+%   global for \cs{regex_gset:Nn}. For instance, this function can be
+%   used as
 %   \begin{verbatim}
 %     \regex_new:N \l_my_regex
 %     \regex_set:Nn \l_my_regex { my\ (simple\ )? reg(ex|ular\ expression) }
 %   \end{verbatim}
-%   The assignment is local for \cs{regex_set:Nn} and global for
-%   \cs{regex_gset:Nn}. Use \cs{regex_const:Nn} for compiled expressions
-%   which never change.
+% \end{function}
+%
+% \begin{function}[added = 2017-05-26]{\regex_const:Nn}
+%   \begin{syntax}
+%     \cs{regex_const:Nn} \meta{regex~var} \Arg{regex}
+%   \end{syntax}
+%   Creates a new constant \meta{regex~var} or raises an error if the name
+%   is already taken.  The value of the \meta{regex~var} is set
+%   globally to the compiled version of the \meta{regular expression}.
 % \end{function}
 %
 % \begin{function}[added = 2021-04-26, updated = 2021-04-29]