summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-07-15 21:27:01 +0000
committerKarl Berry <karl@freefriends.org>2017-07-15 21:27:01 +0000
commitb1ce47fe4d0e1f06d1b019c3c6eb5f1b0ecd5e14 (patch)
tree58362abe4b603bb5f6db898b9b835bc8af730b3e /Master/texmf-dist/source/latex/l3kernel/l3keys.dtx
parent03b8dcfa3435f0265dfad4fd09aaab8f4ff9c617 (diff)
l3 (15jul17)
git-svn-id: svn://tug.org/texlive/trunk@44813 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3kernel/l3keys.dtx')
-rw-r--r--Master/texmf-dist/source/latex/l3kernel/l3keys.dtx111
1 files changed, 57 insertions, 54 deletions
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