[latex3-commits] [git/LaTeX3-latex3-latex3] main: Document that clists/quarks are particular token lists (fixes #791) (2c57a3080)

[Bruno Le Floch]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/2c57a3080a0a41561af180be910f1f132a37e832

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

commit 2c57a3080a0a41561af180be910f1f132a37e832
Author: Bruno Le Floch <blflatex at gmail.com>
Date:   Sat May 15 16:45:04 2021 +0200

    Document that clists/quarks are particular token lists (fixes #791)
    
    This means that \tl_set_eq:NN can be used to set a token list equal
    to a comma list.  Strings also are token lists, but this was already
    documented.


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

2c57a3080a0a41561af180be910f1f132a37e832
 l3kernel/l3clist.dtx | 27 +++++++++++++++++++++------
 l3kernel/l3quark.dtx |  5 ++---
 2 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/l3kernel/l3clist.dtx b/l3kernel/l3clist.dtx
index 4b3684308..970aed1c7 100644
--- a/l3kernel/l3clist.dtx
+++ b/l3kernel/l3clist.dtx
@@ -50,15 +50,16 @@
 %
 % \begin{documentation}
 %
-% Comma lists contain ordered data where items can be added to the left
-% or right end of the list.  This data type allows basic list
+% Comma lists (in short, |clist|) contain ordered data where items can
+% be added to the left or right end of the list.  This data type allows
+% basic list
 % manipulations such as adding/removing items, applying a function to
 % every item, removing duplicate items, extracting a given item, using
 % the comma list with specified separators, and so on.  Sequences
 % (defined in \pkg{l3seq}) are safer, faster, and provide more features,
 % so they should often be preferred to comma lists.  Comma lists are
 % mostly useful when interfacing with \LaTeXe{} or other code that
-% expects or provides comma list data.
+% expects or provides items separated by commas.
 %
 % Several items can be added at once.  To ease input of comma lists from
 % data provided by a user outside an \cs{ExplSyntaxOn} \ldots{}
@@ -75,10 +76,10 @@
 % \end{verbatim}
 % results in |\l_my_clist| containing |a,b,c~\d,{e~},{{f}}| namely the
 % five items |a|, |b|, |c~\d|, |e~| and~|{f}|.  Comma lists normally do
-% not contain empty items so the following gives an empty comma list:
+% not contain empty or blank items so the following gives an empty comma list:
 % \begin{verbatim}
 %   \clist_clear_new:N \l_my_clist
-%   \clist_put_right:Nn \l_my_clist { , ~ , , }
+%   \clist_set:Nn \l_my_clist { , ~ , , }
 %   \clist_if_empty:NTF \l_my_clist { true } { false }
 % \end{verbatim}
 % and it leaves \texttt{true} in the input stream.  To include an
@@ -86,6 +87,17 @@
 % or ends with a space, or is a single brace group), surround it with
 % braces.
 %
+% Any |n|-type token list is a valid comma list input for \pkg{l3clist}
+% functions, which will split the token list at every comma and process
+% the items as described above.  On the other hand, |N|-type functions
+% expect comma list variables, which are particular token list variables
+% in which this processing of items (and removal of blank items) has
+% already occurred.  Because comma list variables are token list
+% variables, expanding them once yields their items separated by commas,
+% and \pkg{l3tl} functions such as \cs{tl_show:N} can be applied to
+% them.  (These functions often have \pkg{l3clist} analogues, which
+% should be preferred.)
+%
 % Almost all operations on comma lists are
 % noticeably slower than those on sequences so converting the data to
 % sequences using \cs{seq_set_from_clist:Nn} (see \pkg{l3seq}) may be
@@ -156,7 +168,10 @@
 %     \cs{clist_set_eq:NN} \meta{comma list_1} \meta{comma list_2}
 %   \end{syntax}
 %   Sets the content of \meta{comma list_1} equal to that of
-%   \meta{comma list_2}.
+%   \meta{comma list_2}.  To set a token list variable equal to a comma
+%   list variable, use \cs{tl_set_eq:NN}.  Conversely, setting a comma
+%   list variable to a token list is unadvisable unless one checks
+%   space-trimming and related issues.
 % \end{function}
 %
 % \begin{function}[added = 2014-07-17]
diff --git a/l3kernel/l3quark.dtx b/l3kernel/l3quark.dtx
index 10ccfa748..23710cbe5 100644
--- a/l3kernel/l3quark.dtx
+++ b/l3kernel/l3quark.dtx
@@ -55,7 +55,8 @@
 %
 % \section{Quarks}
 %
-% Quarks are control sequences that expand to themselves and should
+% Quarks are control sequences (and in fact, token lists) that expand
+% to themselves and should
 % therefore \emph{never} be executed directly in the code.
 % This would result in an endless loop!
 %
@@ -90,8 +91,6 @@
 % \cs{tl_if_eq:NNTF}. A set of special quark testing functions is set up
 % below. All the quark testing functions are expandable although the
 % ones testing only single tokens are much faster.
-% An example of the quark testing functions and their use in recursion
-% can be seen in the implementation of \cs{clist_map_function:NN}.
 %
 % \section{Defining quarks}
 %