[latex3-commits] [git/LaTeX3-latex3-latex3] cctab: Document some places where cctabs can be used (de3aea50d)

[Bruno Le Floch]

Repository : https://github.com/latex3/latex3
On branch  : cctab
Link       : https://github.com/latex3/latex3/commit/de3aea50d0e4a53f53b661f53d6964cfb49efa8e

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

commit de3aea50d0e4a53f53b661f53d6964cfb49efa8e
Author: Bruno Le Floch <bruno at le-floch.fr>
Date:   Mon Jun 29 06:50:25 2020 +0200

    Document some places where cctabs can be used


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

de3aea50d0e4a53f53b661f53d6964cfb49efa8e
 l3kernel/l3cctab.dtx | 26 +++++++++++++++-----------
 l3kernel/l3tl.dtx    |  6 ++++--
 2 files changed, 19 insertions(+), 13 deletions(-)

diff --git a/l3kernel/l3cctab.dtx b/l3kernel/l3cctab.dtx
index 66141d311..7ebf75035 100644
--- a/l3kernel/l3cctab.dtx
+++ b/l3kernel/l3cctab.dtx
@@ -70,10 +70,11 @@
 %   \begin{syntax}
 %     \cs{cctab_const:Nn} \meta{category code table} \Arg{category code set up}
 %   \end{syntax}
-%   Creates a new \meta{category code table} with the category code settings in
-%   force at the time the function is called, and applies (in a group) the
-%   \meta{category code set up} on top of prevailing settings, then saves them
-%   globally as a constant table.
+%   Creates a new \meta{category code table}, applies (in a group) the
+%   \meta{category code set up} on top of prevailing settings at the
+%   time the function is called, then saves them globally as a constant
+%   table.  The \meta{category code set up} can include a call to
+%   \cs{cctab_select:N}.
 % \end{function}
 %
 % \begin{function}{\cctab_gset:Nn,\cctab_gset:cn}
@@ -82,10 +83,11 @@
 %   \end{syntax}
 %   Applies (in a group) the \meta{category code set up} on top of
 %   prevailing category code settings, then saves them globally in the
-%   \meta{category code table}. Thus within a standard code block
-%   the starting point will be the code applied by \cs{c_code_cctab}.
-%   The assignment of the table is global: the underlying primitive does
-%   not respect grouping.
+%   \meta{category code table}.  The \meta{category code set up} can
+%   include a call to \cs{cctab_select:N}.  Within a standard code block
+%   for instance, the starting point will be the code applied by
+%   \cs{c_code_cctab}.  The assignment of the table is global: the
+%   underlying primitive does not respect grouping.
 % \end{function}
 %
 % \section{Using category code tables}
@@ -116,7 +118,9 @@
 %     \cs{cctab_select:N} \meta{category code table}
 %   \end{syntax}
 %   Selects the \meta{category code table} for the scope of the current
-%   group.
+%   group.  This is in particular useful in the \meta{setup} arguments
+%   of \cs{tl_set_rescan:Nnn}, \cs{tl_rescan:nn}, \cs{cctab_const:Nn},
+%   and \cs{cctab_gset:Nn}.
 % \end{function}
 %
 % \section{Category code table conditionals}
@@ -364,7 +368,7 @@
 % \begin{macro}{\cctab_begin:N, \cctab_begin:c}
 % \begin{macro}{\cctab_end:}
 %   These functions perform a few sanity checks before calling internal
-%   functions defined below, which do the engine-dependent
+%   functions defined above, which do the engine-dependent
 %   heavy-lifting.  The first two functions check if a \meta{cctab~var}
 %   exists before trying to use it while \cs{cctab_end:} checks if a
 %   \cs{cctab_begin:N} was used some time earlier.  Skipping these
@@ -391,7 +395,7 @@
 %   Category code tables are always global, so only one version of
 %   assignments is needed.  Simply run the setup in a group and save the
 %   result in a category code table~|#1|, provided it is valid.  The
-%   internal function is defined below depending on the engine.
+%   internal function is defined above depending on the engine.
 %    \begin{macrocode}
 \cs_new_protected:Npn \cctab_gset:Nn #1#2
   {
diff --git a/l3kernel/l3tl.dtx b/l3kernel/l3tl.dtx
index b10167ca2..b7f4d873e 100644
--- a/l3kernel/l3tl.dtx
+++ b/l3kernel/l3tl.dtx
@@ -305,7 +305,8 @@
 %   This allows the \meta{tl~var} to contain material
 %   with category codes other than those that apply when \meta{tokens}
 %   are absorbed.  The \meta{setup} is run within a group and may
-%   contain any valid input, although only changes in category codes
+%   contain any valid input, although only changes in category codes,
+%   such as uses of \cs{cctab_select:N},
 %   are relevant. See also \cs{tl_rescan:nn}.
 %   \begin{texnote}
 %     The \meta{tokens} are first turned into a string (using
@@ -332,7 +333,8 @@
 %   by the \meta{setup} are those in force at the point of use of
 %   \cs{tl_rescan:nn}.)
 %   The \meta{setup} is run within a group and may
-%   contain any valid input, although only changes in category codes
+%   contain any valid input, although only changes in category codes,
+%   such as uses of \cs{cctab_select:N},
 %   are relevant.  See also \cs{tl_set_rescan:Nnn}, which is more
 %   robust than using \cs{tl_set:Nn} in the \meta{tokens} argument of
 %   \cs{tl_rescan:nn}.