From b1ce47fe4d0e1f06d1b019c3c6eb5f1b0ecd5e14 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Sat, 15 Jul 2017 21:27:01 +0000
Subject: l3 (15jul17)

git-svn-id: svn://tug.org/texlive/trunk@44813 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/source/latex/l3kernel/l3keys.dtx | 111 +++++++++++----------
 1 file changed, 57 insertions(+), 54 deletions(-)

(limited to 'Master/texmf-dist/source/latex/l3kernel/l3keys.dtx')

diff --git a/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx b/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
index 2b1deb80434..6f4847fd0d2 100644
--- a/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
+++ b/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
@@ -41,7 +41,7 @@
 %    }^^A
 % }
 %
-% \date{Released 2017/05/29}
+% \date{Released 2017/07/15}
 %
 % \maketitle
 %
@@ -86,7 +86,7 @@
 %     }
 % \end{verbatim}
 %
-% At a document level, \cs{keys_set:nn} will be used within a
+% At a document level, \cs{keys_set:nn} is used within a
 % document function, for example
 % \begin{verbatim}
 %   \DeclareDocumentCommand \MyModuleSetup { m }
@@ -102,7 +102,7 @@
 %
 % Key names may contain any tokens, as they are handled internally
 % using \cs{tl_to_str:n}; spaces are \emph{ignored} in key names.
-% As will be discussed in
+% As discussed in
 % section~\ref{sec:l3keys:subdivision}, it is suggested that the character
 % |/| is reserved for sub-division of keys into logical
 % groups. Functions and variables are \emph{not} expanded when creating
@@ -114,7 +114,7 @@
 %       \l_mymodule_tmp_tl .code:n = code
 %     }
 % \end{verbatim}
-% will create a key called |\l_mymodule_tmp_tl|, and not one called
+% creates a key called |\l_mymodule_tmp_tl|, and not one called
 % \texttt{key}.
 %
 % \section{Creating keys}
@@ -154,9 +154,9 @@
 %
 % Key properties are applied in the reading order and so the ordering
 % is significant. Key properties which define \enquote{actions}, such
-% as |.code:n|, |.tl_set:N|, \emph{etc.}, will override one another.
+% as |.code:n|, |.tl_set:N|, \emph{etc.}, override one another.
 % Some other properties are mutually exclusive, notably |.value_required:n|
-% and |.value_forbidden:n|, and so will replace one another. However,
+% and |.value_forbidden:n|, and so they replace one another. However,
 % properties covering non-exclusive behaviours may be given in any order. Thus
 % for example the following definitions are equivalent.
 % \begin{verbatim}
@@ -172,7 +172,7 @@
 %     }
 % \end{verbatim}
 % Note that with the exception of the special |.undefine:| property, all
-% key properties will define the key within the current \TeX{} scope.
+% key properties define the key within the current \TeX{} scope.
 %
 % \begin{function}[updated = 2013-07-08]
 %   {.bool_set:N, .bool_set:c, .bool_gset:N, .bool_gset:c}
@@ -230,7 +230,7 @@
 %   Defines \meta{key} to set \meta{comma list variable} to \meta{value}.
 %   Spaces around commas and empty items will be stripped.
 %   If the variable does not exist, it
-%   will be created globally at the point that the key is set up.
+%   is created globally at the point that the key is set up.
 % \end{function}
 %
 % \begin{function}[updated = 2013-07-10]{.code:n}
@@ -240,7 +240,7 @@
 %   Stores the \meta{code} for execution when \meta{key} is used.
 %   The \meta{code} can include one parameter (|#1|), which will be the
 %   \meta{value} given for the \meta{key}. The \texttt{x}-type variant
-%   will expand \meta{code} at the point  where the \meta{key} is
+%   expands \meta{code} at the point  where the \meta{key} is
 %   created.
 % \end{function}
 %
@@ -268,7 +268,7 @@
 %   The default does not affect keys where values are required or
 %   forbidden. Thus a required value cannot be supplied by a default
 %   value, and giving a default value for a key which cannot take a value
-%   will not trigger an error.
+%   does not trigger an error.
 % \end{function}
 %
 % \begin{function}{.dim_set:N, .dim_set:c, .dim_gset:N, .dim_gset:c}
@@ -277,7 +277,7 @@
 %   \end{syntax}
 %   Defines \meta{key} to set \meta{dimension} to \meta{value} (which
 %   must a dimension expression).  If the variable does not exist, it
-%   will be created globally at the point that the key is set up.
+%   is created globally at the point that the key is set up.
 % \end{function}
 %
 % \begin{function}{.fp_set:N, .fp_set:c, .fp_gset:N, .fp_gset:c}
@@ -286,7 +286,7 @@
 %   \end{syntax}
 %   Defines \meta{key} to set \meta{floating point} to \meta{value}
 %   (which must a floating point expression).  If the variable does not exist,
-%   it will be created globally at the point that the key is set up.
+%   it is created globally at the point that the key is set up.
 % \end{function}
 %
 % \begin{function}[added = 2013-07-14]
@@ -304,7 +304,7 @@
 %     \meta{key} .inherit:n = \Arg{parents}
 %   \end{syntax}
 %   Specifies that the \meta{key} path should inherit the keys listed
-%   as \meta{parents}. For example, with setting
+%   as \meta{parents}. For example, after setting
 %   \begin{verbatim}
 %     \keys_define:n { foo } { test .code:n = \tl_show:n {#1} }
 %     \keys_define:n { } { bar .inherit:n = foo }
@@ -336,7 +336,7 @@
 %   \end{syntax}
 %   Defines \meta{key} to set \meta{integer} to \meta{value} (which
 %   must be an integer expression).  If the variable does not exist, it
-%   will be created globally at the point that the key is set up.
+%   is created globally at the point that the key is set up.
 % \end{function}
 %
 % \begin{function}[updated = 2013-07-10]{.meta:n}
@@ -389,7 +389,7 @@
 %   \end{syntax}
 %   Defines \meta{key} to set \meta{skip} to \meta{value} (which
 %   must be a skip expression). If the variable does not exist, it
-%   will be created globally at the point that the key is set up.
+%   is created globally at the point that the key is set up.
 % \end{function}
 %
 % \begin{function}{.tl_set:N, .tl_set:c, .tl_gset:N, .tl_gset:c}
@@ -397,7 +397,7 @@
 %     \meta{key} .tl_set:N = \meta{token list variable}
 %   \end{syntax}
 %   Defines \meta{key} to set \meta{token list variable} to \meta{value}.
-%   If the variable does not exist, it will be created globally
+%   If the variable does not exist, it is created globally
 %   at the point that the key is set up.
 % \end{function}
 %
@@ -408,7 +408,7 @@
 %   Defines \meta{key} to set \meta{token list variable} to \meta{value},
 %   which will be subjected to an \texttt{x}-type expansion
 %   (\emph{i.e.}~using \cs{tl_set:Nx}). If the variable does not exist,
-%   it will be created globally at the point that the key is set up.
+%   it is created globally at the point that the key is set up.
 % \end{function}
 %
 % \begin{function}[added = 2015-07-14]{.undefine:}
@@ -424,7 +424,7 @@
 %   \end{syntax}
 %   Specifies that \meta{key} cannot receive a \meta{value} when used.
 %   If a \meta{value} is given then an error will be issued. Setting
-%   the property \texttt{false} will cancel the restriction.
+%   the property \texttt{false} cancels the restriction.
 % \end{function}
 %
 % \begin{function}[added = 2015-07-14]{.value_required:n}
@@ -433,7 +433,7 @@
 %   \end{syntax}
 %   Specifies that \meta{key} must receive a \meta{value} when used.
 %   If a \meta{value} is not given then an error will be issued. Setting
-%   the property \texttt{false} will cancel the restriction.
+%   the property \texttt{false} cancels the restriction.
 % \end{function}
 %
 % \section{Sub-dividing keys}
@@ -456,7 +456,7 @@
 % used to represent keys internally. Both of the above code fragments
 % set the same key, which has full name \texttt{module/subgroup/key}.
 %
-% As will be illustrated in the next section, this subdivision is
+% As illustrated in the next section, this subdivision is
 % particularly relevant to making multiple choices.
 %
 % \section{Choice and multiple choice keys}
@@ -606,7 +606,7 @@
 %   \end{syntax}
 %   Parses the \meta{keyval list}, and sets those keys which are defined
 %   for \meta{module}. The behaviour on finding an unknown key can be set
-%   by defining a special \texttt{unknown} key: this will be illustrated
+%   by defining a special \texttt{unknown} key: this is illustrated
 %   later.
 % \end{function}
 %
@@ -634,18 +634,18 @@
 %   has path \texttt{mymodule/subset/key-a}. This information is stored in
 %   \cs{l_keys_path_tl}, and will have been processed by \cs{tl_to_str:n}.
 %
-%    The \emph{name} of the key is the part of the path after the last
-%    \texttt{/}, and thus is not unique. In the preceding examples, both keys
-%    have name \texttt{key-a} despite having different paths.  This information
-%    is stored in \cs{l_keys_key_tl}, and will have been processed by
-%    \cs{tl_to_str:n}.
+%   The \emph{name} of the key is the part of the path after the last
+%   \texttt{/}, and thus is not unique. In the preceding examples, both keys
+%   have name \texttt{key-a} despite having different paths.  This information
+%   is stored in \cs{l_keys_key_tl}, and will have been processed by
+%   \cs{tl_to_str:n}.
 % \end{variable}
 %
 % \section{Handling of unknown keys}
 % \label{sec:l3keys:unknown}
 %
-% If a key has not previously been defined (is unknown), \cs{keys_set:nn} will
-% look for a special \texttt{unknown} key for the same module, and if this is
+% If a key has not previously been defined (is unknown), \cs{keys_set:nn}
+% looks for a special \texttt{unknown} key for the same module, and if this is
 % not defined raises an error indicating that the key name was unknown. This
 % mechanism can be used for example to issue custom error texts.
 % \begin{verbatim}
@@ -671,7 +671,7 @@
 %   \cs{keys_set_known:nnN} function parses the \meta{keyval list}, and sets
 %   those keys which are defined for \meta{module}. Any keys which are unknown
 %   are not processed further by the parser.
-%   The key--value pairs for each \emph{unknown} key name will be
+%   The key--value pairs for each \emph{unknown} key name are
 %   stored in the \meta{tl} in a comma-separated form (\emph{i.e.}~an edited
 %   version of the \meta{keyval list}). The \cs{keys_set_known:nn} version
 %   skips this stage.
@@ -695,7 +695,7 @@
 %       key-four  .fp_set:N = \l_my_a_fp          ,
 %     }
 % \end{verbatim}
-% the use of \cs{keys_set:nn} will attempt to set all four keys. However, in
+% the use of \cs{keys_set:nn} attempts to set all four keys. However, in
 % some contexts it may only be sensible to set some keys, or to control the
 % order of setting. To do this, keys may be assigned to \emph{groups}:
 % arbitrary sets which are independent of the key tree. Thus modifying the
@@ -712,7 +712,7 @@
 %       key-four  .fp_set:N = \l_my_a_fp          ,
 %     }
 % \end{verbatim}
-% will assign \texttt{key-one} and \texttt{key-two} to group \texttt{first},
+% assigns \texttt{key-one} and \texttt{key-two} to group \texttt{first},
 % \texttt{key-three} to group \texttt{second}, while \texttt{key-four} is
 % not assigned to a group.
 %
@@ -730,11 +730,11 @@
 %   \begin{syntax}
 %     \cs{keys_set_filter:nnnN} \Arg{module} \Arg{groups} \Arg{keyval list} \meta{tl}
 %   \end{syntax}
-%   Actives key filtering in an \enquote{opt-out} sense: keys assigned to any
-%   of the \meta{groups} specified will be ignored. The \meta{groups} are
+%   Activates key filtering in an \enquote{opt-out} sense: keys assigned to any
+%   of the \meta{groups} specified are ignored. The \meta{groups} are
 %   given as a comma-separated list. Unknown keys are not assigned to any
-%   group and will thus always be set. The key--value pairs for each
-%   key which is filtered out will be stored in the \meta{tl} in a
+%   group and are thus always set. The key--value pairs for each
+%   key which is filtered out are stored in the \meta{tl} in a
 %   comma-separated form (\emph{i.e.}~an edited version of the \meta{keyval
 %   list}). The \cs{keys_set_filter:nnn} version skips this stage.
 %
@@ -750,10 +750,10 @@
 %   \begin{syntax}
 %     \cs{keys_set_groups:nnn} \Arg{module} \Arg{groups} \Arg{keyval list}
 %   \end{syntax}
-%   Actives key filtering in an \enquote{opt-in} sense: only keys assigned to
-%   one or more of the \meta{groups} specified will be set. The \meta{groups} are
+%   Activates key filtering in an \enquote{opt-in} sense: only keys assigned to
+%   one or more of the \meta{groups} specified are set. The \meta{groups} are
 %   given as a comma-separated list. Unknown keys are not assigned to any
-%   group and will thus never be set.
+%   group and are thus never set.
 % \end{function}
 %
 % \section{Utility functions for keys}
@@ -829,7 +829,7 @@
 % to category \enquote{other} (12) so that the parser does not \enquote{miss}
 % any due to category code changes. Spaces are removed from the ends
 % of the keys and values. Keys and values which are given in braces
-% will have exactly one set removed (after space trimming), thus
+% have exactly one set removed (after space trimming), thus
 % \begin{verbatim}
 %    key = {value here},
 % \end{verbatim}
@@ -848,15 +848,15 @@
 %   given).  \meta{function_1} should take one argument, while
 %   \meta{function_2} should absorb two arguments. After
 %   \cs{keyval_parse:NNn} has parsed the \meta{key--value list},
-%   \meta{function_1} will be used to process keys given with no value
-%   and \meta{function_2} will be used to process keys given with a
+%   \meta{function_1} is used to process keys given with no value
+%   and \meta{function_2} is used to process keys given with a
 %   value. The order of the \meta{keys} in the \meta{key--value list}
-%   will be preserved. Thus
+%   is preserved. Thus
 %   \begin{verbatim}
 %     \keyval_parse:NNn \function:n \function:nn
 %       { key1 = value1 , key2 = value2, key3 = , key4 }
 %   \end{verbatim}
-%   will be converted into an input stream
+%   is converted into an input stream
 %   \begin{verbatim}
 %     \function:nn { key1 } { value1 }
 %     \function:nn { key2 } { value2 }
@@ -1363,7 +1363,7 @@
 %   the function. If not, then a check to make sure there is no need for
 %   a value with the property. If there should be one then complain,
 %   otherwise execute it. There is no need to check for a |:| as if it
-%   is missing the earlier tests will have failed.
+%   was missing the earlier tests would have failed.
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_define_code:n #1
   {
@@ -1511,15 +1511,17 @@
 %
 % \begin{macro}[int]
 %   {\@@_cmd_set:nn, \@@_cmd_set:nx, \@@_cmd_set:Vn, \@@_cmd_set:Vo}
-%   Setting the code for a key first checks that the basic data structures
-%   exist, then saves the code.
+%   Setting the code for a key first logs if appropriate that we are
+%   defining a new key, then saves the code.
 %    \begin{macrocode}
-\cs_new_protected:Npn \@@_cmd_set:nn #1#2
+\__debug_patch:nnNw
   {
     \cs_if_exist:cF { \c_@@_code_root_tl #1 }
-      { \__chk_log:x { Defining~key~#1~\msg_line_context: } }
-    \cs_set_protected:cpn { \c_@@_code_root_tl #1 } ##1 {#2}
+      { \__debug_log:x { Defining~key~#1~\msg_line_context: } }
   }
+  { }
+\cs_new_protected:Npn \@@_cmd_set:nn #1#2
+  { \cs_set_protected:cpn { \c_@@_code_root_tl #1 } ##1 {#2} }
 \cs_generate_variant:Nn \@@_cmd_set:nn { nx , Vn , Vo }
 %    \end{macrocode}
 % \end{macro}
@@ -1549,7 +1551,8 @@
 %   Assigning a key to one or more groups uses comma lists. As the list of
 %   groups only exists if there is anything to do, the setting is done using
 %   a scratch list. For the usual grouping reasons we use the low-level
-%   approach to undefining a list.
+%   approach to undefining a list.  We also use the low-level approach for
+%   the other case to avoid tripping up the |check-declarations| code.
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_groups_set:n #1
   {
@@ -1560,7 +1563,7 @@
           \tex_undefined:D
       }
       {
-        \clist_set_eq:cN { \c_@@_groups_root_tl \l_keys_path_tl }
+        \cs_set_eq:cN { \c_@@_groups_root_tl \l_keys_path_tl }
           \l_@@_groups_clist
       }
   }
@@ -1757,7 +1760,7 @@
 % \begin{macro}
 %   {.choices:nn, .choices:Vn, .choices:on, .choices:xn}
 %   For auto-generation of a series of mutually-exclusive choices.
-%   Here, |#1| will consist of two separate
+%   Here, |#1| consists of two separate
 %   arguments, hence the slightly odd-looking implementation.
 %    \begin{macrocode}
 \cs_new_protected:cpn { \c_@@_props_root_tl .choices:nn } #1
@@ -2368,7 +2371,7 @@
 % \begin{macro}[int, EXP]{\@@_choice_find:n}
 % \begin{macro}[int, EXP]{\@@_multichoice_find:n}
 %   Executing a choice has two parts. First, try the choice given, then
-%   if that fails call the unknown key. That will exist, as it is created
+%   if that fails call the unknown key. That always exists, as it is created
 %   when a choice is first made. So there is no need for any escape code.
 %   For multiple choices, the same code ends up used in a mapping.
 %    \begin{macrocode}
@@ -2456,7 +2459,7 @@
 %   (same message, but with a |t| or |f| argument, then build the
 %   control sequences which contain the code and other information
 %   about the key, call an intermediate auxiliary which constructs the
-%   code that will be displayed to the terminal, and finally conclude
+%   code to be displayed to the terminal, and finally conclude
 %   with \cs{__msg_show_wrap:n}.
 %    \begin{macrocode}
 \cs_new_protected:Npn \keys_show:nn #1#2
-- 
cgit v1.2.3

