From b1ce47fe4d0e1f06d1b019c3c6eb5f1b0ecd5e14 Mon Sep 17 00:00:00 2001 From: Karl Berry 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