[latex3-commits] [git/LaTeX3-latex3-latex3] main: Clarify doc of prop_put, prop_set_from_keyval etc (see discussion at #924) (531f38b0a)

[Bruno Le Floch]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/531f38b0a1556e0f105546d85171cbbce499c943

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

commit 531f38b0a1556e0f105546d85171cbbce499c943
Author: Bruno Le Floch <blflatex at gmail.com>
Date:   Sun May 16 23:03:56 2021 +0200

    Clarify doc of prop_put, prop_set_from_keyval etc (see discussion at #924)


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

531f38b0a1556e0f105546d85171cbbce499c943
 l3kernel/l3prop.dtx | 45 +++++++++++++++++++++++++--------------------
 1 file changed, 25 insertions(+), 20 deletions(-)

diff --git a/l3kernel/l3prop.dtx b/l3kernel/l3prop.dtx
index 5bf3e271d..e57d9ee23 100644
--- a/l3kernel/l3prop.dtx
+++ b/l3kernel/l3prop.dtx
@@ -51,10 +51,11 @@
 %
 % \LaTeX3 implements a \enquote{property list} data type, which contain
 % an unordered list of entries each of which consists of a \meta{key} and
-% an associated \meta{value}. The \meta{key} and \meta{value} may both be
-% any \meta{balanced text}. It is possible to map functions to property lists
-% such that the function is applied to every key--value pair within
-% the list.
+% an associated \meta{value}. The \meta{key} and \meta{value} may both
+% be any \meta{balanced text}, but the \meta{key} is processed using
+% \cs{tl_to_str:n}, meaning that category codes are ignored. It is
+% possible to map functions to property lists such that the function is
+% applied to every key--value pair within the list.
 %
 % Each entry in a property list must have a unique \meta{key}: if an entry is
 % added to a property list which already contains the \meta{key} then the new
@@ -63,7 +64,7 @@
 %
 % Property lists are intended for storing key-based information for use within
 % code.  This is in contrast to key--value lists, which are a form of
-% \emph{input} parsed by the \pkg{keys} module.
+% \emph{input} parsed by the \pkg{l3keys} module.
 %
 % \section{Creating and initialising property lists}
 %
@@ -124,6 +125,12 @@
 %   \end{syntax}
 %   Sets \meta{prop~var} to contain key--value pairs given in the second
 %   argument.  If duplicate keys appear only one of the values is kept.
+%
+%   Spaces are trimmed around every \meta{key} and every \meta{value},
+%   and if the result of trimming spaces consists of a single brace
+%   group then a set of outer braces is removed.  This enables both the
+%   \meta{key} and the \meta{value} to contain spaces, commas or equal
+%   signs.  The \meta{key} is then processed by \cs{tl_to_str:n}.
 % \end{function}
 %
 % \begin{function}[added = 2017-11-28, updated = 2019-08-25]
@@ -137,11 +144,12 @@
 %   \end{syntax}
 %   Creates a new constant \meta{prop~var} or raises an error if the
 %   name is already taken. The \meta{prop~var} is set globally to
-%   contain key--value pairs given in the second argument.
-%   If duplicate keys appear only one of the values is kept.
+%   contain key--value pairs given in the second argument, processed in
+%   the way described for \cs{prop_set_from_keyval:Nn}.  If duplicate
+%   keys appear only one of the values is kept.
 % \end{function}
 %
-% \section{Adding entries to property lists}
+% \section{Adding and updating property list entries}
 %
 % \begin{function}[updated = 2012-07-09]
 %   {
@@ -162,12 +170,12 @@
 %     \cs{prop_put:Nnn} \meta{property list} \Arg{key} \Arg{value}
 %   \end{syntax}
 %   Adds an entry to the \meta{property list} which may be accessed
-%   using the \meta{key} and which has \meta{value}. Both the \meta{key}
-%   and \meta{value} may contain any \meta{balanced text}. The \meta{key}
-%   is stored after processing with \cs{tl_to_str:n}, meaning that
-%   category codes are ignored. If the \meta{key} is already present
-%   in the \meta{property list}, the existing entry is overwritten
-%   by the new \meta{value}.
+%   using the \meta{key} and which has \meta{value}. If the \meta{key}
+%   is already present in the \meta{property list}, the existing entry
+%   is overwritten by the new \meta{value}. Both the \meta{key} and
+%   \meta{value} may contain any \meta{balanced text}. The \meta{key} is
+%   stored after processing with \cs{tl_to_str:n}, meaning that category
+%   codes are ignored.
 % \end{function}
 %
 % \begin{function}
@@ -178,12 +186,9 @@
 %   \begin{syntax}
 %     \cs{prop_put_if_new:Nnn} \meta{property list} \Arg{key} \Arg{value}
 %   \end{syntax}
-%   If the \meta{key} is present in the \meta{property list} then
-%   no action is taken. If the \meta{key} is not present in the
-%   \meta{property list} then a new entry is added. Both the \meta{key}
-%   and \meta{value} may contain any \meta{balanced text}. The \meta{key}
-%   is stored after processing with \cs{tl_to_str:n}, meaning that
-%   category codes are ignored.
+%   If the \meta{key} is present in the \meta{property list} then no
+%   action is taken. Otherwise, a new entry is added as described for
+%   \cs{prop_put:Nnn}.
 % \end{function}
 %
 % \section{Recovering values from property lists}