summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/ltxkeys/ltxkeys-guide.tex
blob: 739845562d350ef4132fd262e34f9000a07d3586 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
\documentclass[
  use-a4-paper,
  use-10pt-font,
  final-version,
  use-UK-English,
  fancy-section-headings,
  frame-section-numbers,
  para-abstract-style,
  input-config-file,
  no-hyperref-messages
]{amltxdoc}

\hfuzz1pt
\makeatletter
\WrapQuotes
\def\xdecs{\fx{\XDeclareOption}\RedStar\sspace}
\makeindex

% Move to config file:
\def\keydotchoice#1#2{\fx{#1}\unskip\makered{.}\unskip\fx{{#2}}}
\def\preffamkey{\fnl{{pref}{fam}{key}}\sspace}
\def\mpkey{\fnl{{mp}{key}}\sspace}
\def\ifmpkey{\fnl{{if}{mp}{key}}\sspace}
\def\ipreffamkey#1{\fnl{{#1}{pref}{fam}{key}}}
\def\ipreffam#1{\fnl{{pref}{fam}}\unskip\tcl{cmdcolor}{\texttt{@#1}}}

\begin{document}

\begin{frontmatter}
\title{The \texttt{\color{blue}ltxkeys} Package\titleref{t1}}
\titlenote[t1]{%
  The package is available at \iftogTF{pdf}{\url{\@titleurl}}
  {\url{\@shorttitleurl}}.
}
\version{0.0.1}
\titleurl{http://www.ctan.org/tex-archive/macros/latex/contrib/ltxkeys/}
\shorttitleurl{http://www.ctan.org/}
\author{Ahmed Musa \Email{amusa22@gmail.com}\\Preston, Lancashire, UK}

\def\abstractname{\textsc{Summary}}
\begin{abstract}
The \pkg'{ltxkeys} provides facilities for creating and managing keys in the sense of the \pkg'{keyval, xkeyval}, but it is intended to be more robust and faster than these earlier packages. Its robustness emanates from, inter alia, its ability to preserve braces in key values throughout parsing. The need to preserve braces in key values emerges often in parsing keys. This is the case in, eg, the \pkg'{xwatermark}. The package is faster than the \pkg'{xkeyval} mainly because it avoids character-wise parsing of key values (which is called \quoted{selective sanitization} by the \pkg'{xkeyval}). Moreover, it is faster to normalize a comma-separated or key-value list than trim leading and trailing spaces of each element of the list (the \pkg'{xkeyval} as does), since not all the elements of the list will normally have leading and trailing spaces. In fact, the chances are that only a few elements of the list will have such spaces. As another example of optimization, anyone familiar with the implementation of the \pkg'{xkeyval} would have noticed that the macro \hx{\XKV@srstate}, which (in order to allow \hx{\setkeys} to be re-entrant) pushes and pops the states of some important functions in the package, loops over all the functions both when pushing and popping. In the \pkg'{ltxkeys}, pushing and popping functions together involve only one loop. And, unlike in the \pkg'{xkeyval}, higher order functions are undefined as soon as they are no longer needed, to avoid clogging up the stack. In setting keys, the \pkg'{ltxkeys} loops over not only families, as in the \pkg'{xkeyval}, but also over key prefixes. The same strategy applies when the \pkg'{ltxkeys} tries to establish if a key is defined or not. While many aspects of the \pkg'{ltxkeys} are similar to those of the \pkg'{xkeyval}, there are important differences in several areas of syntax, semantics, and internal implementation. The \pkg'{ltxkeys} also provides additional facilities (beyond the \pkg'{xkeyval}) for defining and managing keys. Several types of keys (including ordinary keys, command keys, style keys, choice keys, boolean and biboolean keys) can be efficiently created and managed. In the \pkg'{ltxkeys}, the notions of \quoted{pre-setting} and \quoted{post-setting} keys are similar to those of the \pkg'{xkeyval}. But the \pkg'{ltxkeys} introduces additional concepts in this respect: \quoted{initialized} and \quoted{launched} keys. The latter are special preset keys.
\end{abstract}

\let\licensename\relax
\begin{license}
  \small
\xwmcolorbox[textalign=justified, outerframecolor=blue, innerframecolor=orange,
  width=.985\hsize]{%
  This work (\ie, all the files in the \pkg'{ltxkeys} bundle) may be distributed and/or modified under the conditions of the \lppl, either version~1.3 of this license or any later version.
  The \lppl maintenance status of this software is \quoted{author-maintained}. This software is provided \quoted{as it is}, without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose.
  \endgraf
  \centerline{\makered{\CopyrightYear}}\vspace{-.8\baselineskip}\relax
}
\end{license}
\end{frontmatter}

\begin{xwmshade}[fillcolor=white,framecolor=orange,framerule=1pt,framesep=2pt,
  width=1.0\hsize]\tableofcontents
\end{xwmshade}


\docsection{Motivation}

What are the \emph{raison d'etre} and origins of the \pkg'{ltxkeys}? Well, I decided to write this package as I grabbled with some practical problems of key parsing while developing version~1.5.0 of the \pkg'{xwatermark}. The tasks proved more challenging than I had predicted and, despite its commendable and widely deployed facilities, I found the \pkg'{xkeyval} inadequate in some respects. As mentioned earlier, the several functionalities of the \pkg'{ltxkeys} can be employed for general key management in \latex beyond the \pkg'{xwatermark}. Indeed the \pkg'{ltxkeys} can be used as a more robust replacement for the \pkg'{xkeyval}, of course with some adaptation.


\docsection{Package options}

Wherever the semicolon \quoted{;} is indicated as a list parser in this guide, it can be replaced by any user-specified one character parser via the package option \fx{keyparser}. To avoid confusing the user-supplied parser with internal parsers, it is advisable to enclose the chosen character in curly braces, \eg, as in the following example. The braces will be stripped off internally.

\start{example}[keyparser]
\documentclass[verbose,keyparser={|}]{article}
|orr
\usepackage[keyparser={|}]{ltxkeys}
\finish{example}

The other package options are listed in \amref{tab:pkgoptions}.

\extrarowheight=2pt
\arrayrulecolor{yellow}
\begin{tabularx}{\linewidth}{|m{3cm}|m{2.5cm}|X|}
\caption{Package options\xwmlabel{tab:pkgoptions}}\\\hline
\rowcolor{pink}
\bfseries Option&\bfseries Default&\bfseries Meaning\\\hline
\endfirsthead
\hline
\multicolumn{3}{|l|}{\emph{Continued from last page}}\\\hline
\bfseries Option&\bfseries Default&\bfseries Meaning\\\hline
\endhead
\multicolumn{3}{|r|}{\emph{Continued on next page}}\\\hline
\endfoot
\hline
\endlastfoot
\fx{verbose} & \hx{false} & The global boolean switch that determines if information should be logged for some tasks in the package. The speed of compilation is affected by this option.\\\hline
\fx{keyparser} & \texttt{;} & The list parser used for some loops in defining keys. See note above.\\\hline
\fx{keystacklimit} & \hx{4} & This is used to guard against erroneous infinite re-entrance of \fx{\ltxkeys@setkeys}. The default value of~4 means that \fx{\ltxkeys@setkeys} can't ordinarily be nested beyond level~4. If you must nest \fx{\ltxkeys@setkeys} beyond this level, you have to raise the \fx{keystacklimit} as a package option.\\\hline
\end{tabularx}

\end{document}


\docsection{Defining keys}

In the following, quantities in square brackets---\eg, [yyy]---and those in parenthesis---\eg, (yyy)---are optional.


\docsubsection{Ordinary keys}

  \ltxkeys@ordkey[<pref>]{<fam>}{<key>}[<default>]{<callback>}

This defines a macro of the form \preffamkey of one argument that holds the key function <callback>. The default value for <pref> is always \fx{KV}, as in the \pkg'{xkeyval}. When \ang{key} is used in a \fx{\ltxkeys@setkeys} command (see \amref{sec:}) containing key=value, the macro \preffamkey takes the value as its argument and is then executed. The given argument or key value can be accessed in <callback> by using \fx{#1} inside the function. The optional <default>, if available, will be used by \preffamkey when the user hasn't provided a value for the key at \fx{\ltxkeys@setkeys}. If <default> was absent at key definition and the key user hasn't provided a value for the key, an error message will be flagged.


\docsubsection{Command keys}

  \ltxkeys@cmdkey[<pref>]{<fam>}[<mp>]{<key>}[<default>]{<callback>}

The optional <mp> is called the \quoted{macro prefix} (in the parlance of the \pkg'{xkeyval}). If <mp> is given, the command \mpkey will hold the current user input; otherwise (if <mp> is absent) the user input will be available in \ipreffamkey{cmd}. The command \preffamkey, called the \quoted{key macro} by the \pkg'{xkeyval}, will hold the <callback>.


\docsubsection{Style keys---keys with dependants}

Style keys have the following syntaxes:

  \ltxkeys@stylekey[<pref>]{<fam>}[<mp>]{<key>}[<default>](<dependants>){<callback>}

  \ltxkeys@stylekey*[<pref>]{<fam>}[<mp>]{<key>}[<default>](<dependants>){<callback>}

The <dependants> have the syntax:

    {<keytype>/<keyname>/<default>/<callback>; another set of dependant; etc}

  <default> and <callback> can be absent. <keytype> can be \quoted{ord} (ordinary key), \quoted{cmd} (command key), \quoted{bool} (boolean key), or \quoted{choice} (choice key).

Dependants keys always share the same key prefix <pref>, family <fam>, and macro prefix <mp> with the parent key.

If <mp> is given, the command \mpkey will hold the current user input for the parent key; otherwise the user input will be available in \ipreffamkey{style}. The command \preffamkey will always hold the <callback>.

If the \stform is used, all undefined dependants will be defined and set on the fly as the parent is being set. If the \stform isn't used and undefined dependants occur, then an error message will be flagged at the time the parent is being set.

At most times it is possible to access the parent key's current value with \parentval. Within <default> and <callback> of <dependants>, it is possible to refer to the parent key's callback with its full macro name (\ie, \preffamkey). \parentval is always available for use as the default value of dependant keys, but it may be lost in the callbacks of dependant keys, because a dependant key, once defined, may be set independent of, and long after, the parent key has been executed. It is therefore more reliable to refer to the macro \fnl{{pref}{fam}{key}{value}}, which is recorded for only the parent key of style keys and which holds the current user input for the parent key. The macro \fnl{{pref}{fam}{key}{value}} is recorded only if it appears at least once in the attributes of dependant keys. The macro \fnl{{pref}{fam}{key}{value}} has a more unique name than \mpkey but they always contain the same value of a style key. As mentioned above, if <mp> is not given, the user input for a style key will be available in the macro \ipreffamkey{style}, instead of \mpkey.

Note: \fx{#1} in the callback of parent key refers to the current value of the parent key, while \fx{#1} in the callback of any dependant key refers to the current value of that dependant key.

Example (define and set all undefined dependants on the fly):

  \ltxkeys@stylekey*[KV]{fam}[mp@]{keya}[{left}](%
    % `#1' here refers to the value of the DEPENDANT key
    % at the time it is being set. Use \parentkey and \parentval
    % here to access the parent key name and its current value:
    ord/keyb/{right}/\def\y##1{#1##1};
    % The default of keyc is the current value of parent (keya):
    cmd/keyc/\parentval;
    % Because \KV@fam@keya@value appears below, it will be saved
    % when the parent key (keya) is being set, otherwise it would be
    % unavailable:
    bool/keyd/true/\ifmp@keyd\edef\x##1{##1\KV@fam@keya@value}\fi
  ){
    % `#1' here refers to the value of the PARENT key
    % at the time it is being set:
    \def\x##1{##1xx#1xx}%
    % Check the value of parent key:
    \ltxkeys@checkchoice[\userinput\nr]{#1}{left,right,center}%
  }

In this example, \fx{\userinput} corresponds to \fx{#1}, and \fx{\nr} is the numerical order of the user input in the nominations \fnz{{left}{right}{center}}. See more about the commands \ffx'{\ltxkeys@checkchoice, \CheckInput} in \amref{sec:}.

You can try setting \fx{keya} as follows to see what happens to keys \ffx'{keyb,keyc,keyd}:

  \ltxkeys@setkeys[KV]{fam}{keya={right}}

The braces in the key values above are just to exemplify the fact that braces in key values are preserved throughout key parsing. This is essential in, for example, the \pkg'{xwatermark}.


\docsubsection{Boolean keys}

  \ltxkeys@boolkey[<pref>]{<fam>}[<mp>]{<key>}[<default>]{<callback>}

  \ltxkeys@boolkey+[<pref>]{<fam>}[<mp>]{<key>}[<default>]{<callback>}{<fn>}

If <mp> is given, the command \mpkey will hold the current user input for the key at key setting time; otherwise the user input will be available in \ipreffamkey{bool}\footnote{This differs from the system in the \pkg'{xkeyval}.}. If <mp> is specified, a boolean of the form \ifmpkey will be created at key definition, which will be set by \fx{\ltxkeys@setkeys} according to the user input. If <mp> is not specified, a boolean of the form \ipreffamkey{ifbool} will instead be created.

The user input for boolean keys must be in the set {true | false}. The command \preffamkey will always hold the <callback>, which will be executed if the user input is valid.

The \plform of \fx{\ltxkeys@boolkey} will execute <fn> in place of <callback> if the user input isn't in {true | false}; the plain form will issue an error in this case.


\docsubsubsection{Biboolean keys}

  \ltxkeys@biboolkeys[<pref>]{<fam>}[<mp>]{<bool1>,<bool2>}
    [<default>]{<callback1>}{<callback2>}

  \ltxkeys@biboolkeys+[<pref>]{<fam>}[<mp>]{<bool1>,<bool2>}
    [<default>]{<callback1>}{<callback2>}{<fn>}

Biboolean keys always assume opposite states: when one is true, the other is automatically toggled to false; and vice versa. Think of the options \hx{draft} and \hx{final} in a document class, but note that traditional document classes don't currently use biboolean keys.

  <callback1> belongs to the boolean key <bool1>, while <callback2> belongs to <bool2>.

The \plform of \ltxkeys@biboolkeys will execute <fn> in place of <callback1> or <callback2> if the input is not in {true | false}; the plain form will issue an error in this case.

Biboolean keys have equal symmetry (\ie, they can call each other with equal propensity) and they won't bomb out in an infinite reentrance. They normally would know if they're calling each other.

  Example:

  \ltxkeys@biboolkeys+[KV]{fam}[mp@]{keya,keyb}[true]{%
    \ifmp@keya\def\x##1{##1x#1x##1}\fi
  }{%
    \ifmp@keyb\def\y##1{##1y#1y##1}\fi
  }{%
    \@latex@error{Invalid value '\string#1' for keya or keyb}\@ehc
  }


\docsubsection{Choice keys}

The choice keys of the \pkg'{ltxkeys} differ from those of the \pkg'{xkeyval} in at least one respects, namely, the presence of the macro prefix for choice keys in the \pkg'{ltxkeys}.

  \ltxkeys@choicekey[<pref]{<fam>}[<mp>]{<key>}[<bin>]{<alt>}[<default>]{<callback>}

  \ltxkeys@choicekey*[<pref]{<fam>}[<mp>]{<key>}[<bin>]{<alt>}[<default>]{<callback>}

  \ltxkeys@choicekey*+[<pref]{<fam>}[<mp>]{<key>}[<bin>]{<alt>}[<default>]{<callback>}{<fn>}

  \ltxkeys@choicekey*+![<pref]{<fam>}[<mp>]{<key>}[<bin>]{<alt>}[<default>]{<callback>}{<fn>}

Choice keys check the user input against the nominations suggested by the author of the key. The \stform will convert user input to lowercase before checking it against the list of nominations in \ang{alt}. In all the above variants, if the input is valid, then \ang{callback} will be executed. If the user input isn't valid, the \nonplform+ will flag an error, while the \plform will execute \ang{fn}. The \clform will fully expand the user input before checking it against the nominations in \ang{alt}. The \clform arises from the fact that sometimes macros are passed as the values of choice keys.

If <mp> is absent, then \fx{\ltxkeys@choicekey} uses \ipreffamkey{chc} to hold the user input.

<alt> is the list of nominations for the key value, \ie, admissible values of the key. When <alt> has no \fx{/.code} or forward slash \fx{/} in it, then it is expected to be of the familiar \pkg'{xkeyval} syntax:

    {choice1, choice2, etc}

If \ang{alt} it has \fx{/.code} or \fx{/} in it, then it is expected to have one of the following syntaxes:

    {choice1/.code=callback1|A(keyparser) choice2/.code=callback2|A(keyparser) etc}

    {choice1/callback1|A(keyparser) choice2/callback2|A(keyparser) etc}

This means that if you have \fx{/.code} or \fx{/} in any of the callbacks, it has to be enclosed in curly braces. Please recall that the default value of \ang{keyparser} is \qsemicolon. \fx{keyparser} is a package option. This syntax also implies that if you have the \ang{keyparser} in \ang{defn}, it has to be wrapped in curly braces. The \ang{keyparser} in this syntax can also be \qcomma.

\Note Here is the rule for parsing the \ang{alt} list. First the package checks if the declared key parser (\ie, \ang{keyparser}) is in the \ang{alt} list. If the parser exists in \ang{alt}, then the list is parsed using this parser. Otherwise the list is parsed using comma as the parser. Moreover, the package checks if \fx{.code} separates \ang{choice} from \ang{callback}. If no \fx{.code} is found, then \fx{/} is assumed to be the separator. But note that when there is no \ang{callback}, then neither \fx{.code} nor \fx{/} is necessary.

It is possible to refer to the current value of \ang{key} as \fx{#1} in <alt>.

The \stform of \fx{\ltxkeys@choicekey} will convert the user input to lowercase before checking <alt> and executing the callbacks. The \plform will execute <fn> in place of <callback> if the user input isn't in <alt>.

<bin> has, \eg, the syntax \fx{[\userinput\nr]}, where \fx{\userinput} will hold the user input (in lowercase if the \stform of \fx{\ltxkeys@choicekey} is called), and \fx{\nr} will hold the serial number of the value in the list of nominations <alt>, starting from 0. If the input isn't valid, \fx{\userinput} will still hold the user input, but \fx{\nr} will be~-1.

Example (defining choice key):

  \ltxkeys@choicekey[KV]{fam}{keya}{%
    % There are no callbacks for these simple nominations:
    center,right,left,justified
  }[center]{% <- default value
    \def\x##1##2{==##1++#1++##2==}%
  }

  \ltxkeys@choicekey*+[KV]{fam}[mp@]{keya}[\userinput\nr]{%
    center,right,left,justified
  }[center]{%
    \def\x##1##2{==##1++#1++##2==}%
  }{%
    \@latex@error{Inadmissible value '\string#1' for keya}\@ehc
  }

  \ltxkeys@choicekey*+[KV]{fam}[mp@]{keyb}[\userinput\nr]{%
    % There are callbacks for these nominations:
    center/.code=\def\x##1{*##1*#1*##1};
    right/.code=\edef\z{\expandcsonce\ltxkeys@tval};
    left/.code=\edef\myinput{\cpttrimspaces{#1}};
    justified/.code=\letcsntocs{#1@align}\relax
  }[center]{%
    \def\x##1##2{==##1++#1++##2==}%
  }{%
    \@latex@error{Inadmissible value '\string#1' for keya}\@ehc
  }

  \ltxkeys@choicekey[KV]{fam}[mp@]{keyb}[\userinput\nr]{%
    % The callbacks can also take the following form:
    center/\def\x##1{*##1*#1*##1},
    right/\edef\z{\expandcsonce\ltxkeys@tval},
    left/\edef\userinput{\cpttrimspaces{#1}},
    justified/\letcsntocs{#1@align}\relax
  }[center]{%
    \def\x##1##2{==##1++#1++##2==}%
  }


\docsubsection{Defining boolean and command keys with one command}

More than one boolean and command keys can be defined simultaneously by the following command:

  \ltxkeys@definekeys[pref]<fam>[macro-pref]{%
    <key>=<default>/<callback>; another set of key; etc
  }

  \ltxkeys@definekeys*[pref]<fam>[macro-pref]{%
    <key>=<default>/<callback>; another set of key; etc
  }

<default> can be absent in the case of command keys, and <callback> can be absent for the two types of key. Boolean keys must, however, have default values {true | false}, to be distinguishable from command keys. The \plsign that separates the key name from the default value can be replaced with forward slash (/). That is, the following syntax is also permitted:

  \ltxkeys@definekeys[pref]<fam>[macro-pref]{%
    <key>/<default>/<callback>; another set of key; etc
  }

  \ltxkeys@definekeys*[pref]<fam>[macro-pref]{%
    <key>/<default>/<callback>; another set of key; etc
  }

You can use the command \fx{\CheckInput} in \ang{callback} to introduce choice keys as command keys (see example below).

Ordinary keys and conventional choice keys can't be introduced directly by this command (use \fx{\ltxkeys@declarekeys} instead).

The \stform can be used to define new keys (in the sense of \hx{\newcommand}).

\Note Keys defined by \fx{\ltxkeys@definekeys} are automatically set/initialized instantly, to provide default values for immediate use. Boolean keys are preset with value \quoted{false}, so that they aren't turned \quoted{true} prematurely.

\Note In \ffx'{\ltxkeys@definekeys, \ltxkeys@declarekeys} every line is assumed to end with a comment sign. This is to be specially noted if a space is desired at the end of line. You can insert such a space with a comment sign, or, if appropriate, use \hx{\space}.

  Example (\stform -> new keys):

  \ltxkeys@definekeys*[KV]<fam>[mp@]{%
    % command key with callback:
    keya={keepbraced}/\def\x##1{##1*#1*##1};
    % boolean key:
    keyb=true/\def\y##1{##1yyy#1};
    % command key with no callback:
    keyc=xxx;
    % choice-like command key:
    keyd=center/\CheckInput{#1}{left,right,center}
      \ifinputvalid
        \edef\myval{\expandcsonce\userinput}
        \edef\numberinlist{\number\nr}
        \edef\mychoices{\expandcsonce\nominations}
      \else
        \@latex@error{Input `#1' not valid}\@ehd
      \fi;
    % boolean key with no callback:
    keyc=false;
  }

In this example, \fx{\userinput} corresponds to \fx{#1}; \fx{\nr} is the numerical order of the user input in \fx{\nominations}; the list of valid values suggested at key definition time (\fnz{{left}{right}{center}} in this example). The boolean \fx{inputvalid} is associated with the command \fx{\CheckInput} and is available to the user. It is set \hx{true} when the user input is valid, and \hx{false} otherwise.


\docsubsection{Defining all types of key with one command}

\start{newmacro}[\ltxkeys@declarekeys]
\ltxkeys@declarekeys[|A(pref)]<|A(fam)>[|A(mp)]{% |label(mac:declarekeys)
  <|A(keytype)>/<|A(keyname)>/<|A(default)>/<|A(callback)>; another set of key; etc
}
\ltxkeys@declarekeys|*[|A(pref)]<|A(fam)>[|A(mp)]{%
  <|A(keytype)>/<|A(keyname)>/<|A(default)>/<|A(callback)>; another set of key; etc
}
\finish{newmacro}

Here, \ang{default} and \ang{callback} can be absent in all cases. \ang{keytype} may be any one of \fnz{{ord}{cmd}{sty}{sty*}{bool}{choice}}.

The star (\redstar) in <sty\RedStar> has the same meaning as in \fx{\ltxkeys@stylekey} above.

Choice keys must have their names associated with their admissible <alt> values in the format <keyname.{<alt>}> (see example below).

The \stform can be used to define new keys (in the sense of \hx{\newcommand}).

\Note Keys defined by \fx{\ltxkeys@declarekeys} are automatically set instantly, to provide default values for immediate use. Boolean keys are always initialized in this sense with \quoted{false}, so that they aren't turned \quoted{true} prematurely.

\start{example}[\ltxkeys@declarekeys]
\ltxkeys@declarekeys*[KV]<fam>[mp@]{%
  cmd/keya/mm/\def\x##1{##1*#1*##1};
  bool/keyb;
  sty/keyc/xxx/\def\y##1{##1yyy#1};
  sty*/keyd/blue/\def\y##1{##1#1}/
  cmd>keye>\parentval>\def\z####1{####1+##1+####1};
  choice/keyf.{left,right,center}/
    \ifcase\nr\def\shoot{0}\or\def\shoot{1}\or\def\shoot{2}\fi;
}
\finish{example}

Notice the \fx{>...>} used for the dependant key (\emph{keye}) attributes of style key \emph{keyd}. The default value of the dependant key \emph{keye} will in this example be whatever is submitted for \emph{keyd}. Notice also the syntax \keydotchoice{keyf}{left,right,center} for the choice key \emph{keyf}. It says that the alternate admissible values for \emph{keyf} are \emphlist'{left,right,center}.


\docsubsection{Need-value keys}

Sometimes you may want to create keys for which the user must always supply his/her own values, even if the keys originally have default values. The default values of keys may not always be suitable. Take, for example, the height and width of a graphics image. For functions that are meant to handle generic images, it would certainly be inappropriate to relieve the user of the need to call picture height and width without corresponding values.

To make a key a need-value key, simply attach the pointer \fx{\needvalue} to the key at definition time. This pointer can be used only when defining keys, and not when setting keys.

  Example:

  \ltxkeys@cmdkey[KV]{fam}[mp@]{\needvalue{keya}}[blue]{%
    \def\x##1{##1x#1x##1}%
  }
  \ltxkeys@setkeys[KV]{fam}{keya}
  % -> Error: the author of 'keya' designed it to require a user value.

See more about key pointers in Section \amref{sec:}.


\docsection{Setting keys}

Keys can be set by the following utilities:

\docsubsection{Set defined keys}

  \ltxkeys@setkeys[|A(pref)]{|A(pref)}[|A(na)]{|A(keyvals)}
  \ltxkeys@setkeys*+[|A(prefs)]{|A(fams)}[|A(na)]{|A(keyvals)}

Here, \ang{prefs}, \ang{fams} and \ang{keyvals} are comma-separated list of key prefixes, families and \keyval pairs, respectively. Keys listed in the comma-separated list \ang{na} are ignored. The \stform will save all undefined keys with prefix \ang{pref} and in family \ang{fam} in the macro \fnl{pref}{fam}{rmkeys}, to be set later, perhaps with \fx{\ltxkeys@setrmkeys}. The \plform will search in all the prefixes in \ang{prefs} and all families in \ang{fams} for a key before logging the key in \fnl{pref}{fam}{rmkeys} (if the \makered{$*+$}-form is used) or reporting it as undefined.

To avoid infinite re-entrance in \fx{\ltxkeys@setkeys} and the consequent bombing out of \fx{\ltxkeys@setkeys}, the package option \fx{keystacklimit} is introduced. Its default value is~4, meaning that \fx{\ltxkeys@setkeys} can't ordinarily be nested beyond level~4. If you must nest \fx{\ltxkeys@setkeys} beyond this level, you can raise the \fx{keystacklimit} as a package option via \hx{\usepackage} or, if \pkg'{catoptions} is loaded before \hx{\documentclass}, via \hx{\documentclass}. For example,

\start{example}
\usepackage[keystacklimit=6]{ltxkeys}
\finish{example}
\fxim*{keystacklimit}


\docsubsection{Setting `remaining' keys}

The command \fx{\ltxkeys@setrmkeys}, which has both star (\redstar) and plus (\redplus) variants is the counterpart of \fx{\setrmkeys} of the \pkg'{xkeyval}:

  \ltxkeys@setrmkeys[|A(pref)]{|A(pref)}[|A(na)]
  \ltxkeys@setrmkeys*+[|A(prefs)]{|A(fams)}[|A(na)]


\docsubsection{Setting aliased keys}

Alias and aliased keys differ from style keys. Two keys may be aliased to each other, such that when one is set, the alias is automatically set with the same or a different value. The concept is similar to, but not identical with, that of style keys. The two aliases must all be in the same family and have the same key and macro prefixes.

\ltxkeys@setmnkey{<key>}[<value>]

Here, \ang{value} is optional; if it is not given, \ang{key} will be set with the current value of its alias. The commands \ffx'{\setmnkey, \setaliaskey} are shortened variants of \fx{\ltxkeys@setmnkey}.

  Example:

  \ltxkeys@definekeys*[KV]<fam>[mp@]{%
    printsign=true;
    printmark=true/\ltxkeys@setmnkey{printsign}[false];
    keya=$+++$;
    keyb=star/\ltxkeys@setmnkey{keya}[$***$]
  }
  \ltxkeys@definekeys*[KV]<fam>[mp@]{%
    keya=sun/\CheckInput{#1}{star,sun,moon}
      \ifinputvalid
        \edef\givenval{\userinput}
        \edef\found{\ifcase\nr star@\or sun@\or moon@\fi}
      \else
        \@latex@error{Input `#1' not valid}\@ehd
      \fi;
    keyb=star/\ltxkeys@setmnkey{keya};
  }


The boolean \fx{inputvalid} associated with the command \fx{\CheckInput} is described above in \amref{sec:}.

The example of 'printsign' and 'printmark' is similar, but not equivalent, to the notion of biboolean keys. Biboolean keys have equal symmetry (\ie, they can call each other with equal propensity) and they won't bomb out in an infinite reentrance. This is not the case with aliased keys: only slave/alias can set or call master/main key. If they both call each other, the user will be alerted to the fact that there is an infinite reentrance of keys. The notion of 'slave' and 'master' used in the \pkg'{ltxkeys} may be counterintuitive but in reality it is quite logical.

Schemes like the following are disallowed for obviously reasons; the package will flag an error if they occur:

\start{example}[Nested \setmnkey]
\ltxkeys@ordkey[XWM]{main}{testa}[true]{\setmnkey{testb}}
\ltxkeys@ordkey[XWM]{main}{testb}[true]{\setmnkey{testa}}
\ltxkeys@setkeys[XWM]{main}{testa}
\finish{example}
\aidx*{Nested \headfx{\setmnkey}}


\docsubsection{Using key pointers}

The \ffx'{\savevalue,\usevalue} pointers of the \pkg'{xkeyval} are still available at key setting time, but with increased robustness and optimization. Curly braces in values are preserved throughout, and instead of saving the value of each key tagged with \fx{\savevalue} in a separate macro, we save all such keys and their values in only one macro (for each combination of <pref> and <fam>) and use a fast search technique to find the values when they are needed later (by any key tagged with \fx{\usevalue}).

Here is an interesting example (and test) of use of pointers:

  \ltxkeys@stylekey*[KV]{fam}{\needvalue{keya}}[{left}](%
    % #1 here refers to the value of the dependant key
    % at the time it is being set.
    ord/\needvalue{keyb}/\parentval/\edef\y##1{##1xx\unexpanded{#1}};
    cmd/keyc/{center}
  ){%
    % #1 here refers to the value of the parent key
    % at the time it is being set:
    \def\x##1{##1xx#1}
  }
  \ltxkeys@setkeys[KV]{fam}{\savevalue{keya}={\def\y##1{##1}},
    \savevalue{keyb}=\usevalue{keya},keyc=\usevalue{keyb}}


\docsubsection{Accessing the saved value of a key}

As mentioned earlier, the pointers \ffx'{\savevalue, \usevalue} are available only within \fx{\ltxkeys@setkeys}. But suppose you have used \fx{\savevalue} within \fx{\ltxkeys@setkeys} to set the value of a key, how do you access that value outside of \fx{\ltxkeys@setkeys}? You can do this by using the following \fx{\ltxkeys@storevalue} command:

    \ltxkeys@storevalue[<pref>]{<fam>}{<key>}<cs>
    \ltxkeys@storevalue+[<pref>]{<fam>}{<key>}<cs><fallback>

Here, <cs> is the macro (defined or undefined) that will receive the saved value of \ang{key}. The plain variant of this command will raise an error message if the value of the key wasn't previously saved, while the \plform will resort to the user-supplied function <fallback>. Only saved key values can be recovered by this command.

    Examples:

    \ltxkeys@cmdkey[KV]{fam}{\needvalue{keya}}[{left}]{%
      \def\x##1{##1xx#1}
    }
    \ltxkeys@setkeys[KV]{fam}{\savevalue{keya}={\def\y##1{##1}}}
    \ltxkeys@storevalue[KV]{fam}{keya}\tempa
    \ltxkeys@storevalue+[KV]{fam}{keya}\tempb{%
      \@latex@error{No value saved for key 'keya'}\@ehc
    }


\docsubsection{Pre-setting and post-setting keys}

\ltxkeys@presetkeys|![pref]{fam}{keys}
\ltxkeys@removepresetkeys|![pref]{fam}{keys}
\ltxkeys@undefpresetkeys|![pref]{fam}
\ltxkeys@postsetkeys|![pref]{fam}{keys}
\ltxkeys@removepostsetkeys|![pref]{fam}{keys}
\ltxkeys@undefpostsetkeys|![pref]{fam}

\fx{\ltxkeys@presetkeys} means \quoted{these keys should be set before setting other keys in any run of \fx{\ltxkeys@setkeys}}. \fx{\ltxkeys@postsetkeys} means \quoted{these keys are to be set after setting other keys in any run of \fx{\ltxkeys@setkeys}}. \ffx'{\ltxkeys@removepresetkeys, \ltxkeys@removepostsetkeys} remove \ang{keys} from preset and post-set lists, respectively. \ffx'{\ltxkeys@undefpresetkeys,\ltxkeys@undefpostsetkeys}, respectively, undefine all preset and post-set keys in the given family. The \RedPrime means that the assignments would be done (and the lists built) globally rather than locally.

Logically, you can't enter the same key twice in either preset or post-set list in the same family and prefix.

\start+{example}[\ltxkeys@presetkeys, \ltxkeys@postsetkeys, etc.]
\ltxkeys@definekeys*[KV1]<fam1>[mp@]{%
  keya/left/\def\x##1{#1x##1};
  \needvalue{keyb}/right;
  keyc/center;
  keyd
}
\ltxkeys@presetkeys|![KV1]{fam1}{keya=\flushleft,keyb=\flushright}
\ltxkeys@postsetkeys|![KV1]{fam1}{keyd=\flushleft}
...
|com(Eventually, only `keya' will be preset:)
\ltxkeys@removepresetkeys|![KV1]{fam1}{keyb=\flushright}
...
|com(Because of the |* and |+ signs, all unknown keys |(those in family `fam2'|))
|com(will be saved in the list of remaining keys, and can be set later)
|com(with \ltxkeys@setrmkeys:)
\ltxkeys@setkeys|*|+[KV1,KV2]{fam1,fam2}[keyd]{keya=xxx,keyb=yyy,keyc}
\finish{example}


\docsubsection{Initializing keys}

  \ltxkeys@initializekeys[<prefs>]{<fams>}[<na>]

This presets ALL keys previously defined in families \ang{fams} with their default values; it ignores keys listed in \ang{na}. If \ang{na} is a list of key-value pairs, the key names are extracted from the list before the family keys are initialized. Any key-value pairs in \ang{na} are not set at all. All keys defined by \ffx'{\ltxkeys@definekeys, \ltxkeys@declarekeys} are automatically instantly initialized, except slave/alias and dependant keys. Alias and dependant keys aren't initialized in this case in order to avoid cyclic re-entrance of \fx{\ltxkeys@setkeys}.

The command \fx{\ltxkeys@initializekeys} can be used in place of \fx{\ltxkeys@executeoptions}, since \fx{\ltxkeys@executeoptions} (similar to \latex kernel's \hx{\ExecuteOptions}) fulfils the sole purpose of setting up default values of options. Keys defined via \ffx'{\ltxkeys@definekeys, \ltxkeys@declarekeys} don't have to be initialized, since they're automatically initialized at  definition time.


\docsubsection{Launching keys}

  \ltxkeys@launchkeys[<pref>]{<fam>}[<curr>]

This presets ALL keys defined in family <fam> with their default values; it ignores keys listed in <curr>. <curr> is actually the list of key-value pairs that the user wants to use as current values of keys. Their keys are to be ignored when setting up defaults, \ie, when initializing the family keys. One major difference between \ffx'{\ltxkeys@launchkeys, \ltxkeys@initializekeys} is that in \fx{\ltxkeys@launchkeys} the key-value pairs in <curr> are immediately set after the family keys are initialized.

Note: Keys with multiple prefixes and from multiple families can't be launched at the same time.


\docsubsection{Handling undefined or unknown keys}

You can use the macro \fx{\ltxkeys@unknownkeyhandler} to declare to the \pkg'{ltxkeys} the course of action to take if, while setting keys, it discovers that a key is undefined or unknown. The syntax of this command is

  \ltxkeys@unknownkeyhandler[<prefs>]{<fams>}{<callback>}

where <callback> signifies the action to take. The default <callback> is to log the keys and warn the user, in each run, of the presence of unknown keys. The same <callback> can be used across key prefixes <prefs> and families \ang{fams}. You can use \fx{#1} (or \fx{\CurrentPref}) in this macro to represent the current key prefix, \fx{#2} (or \fx{\CurrentFam}) for the current family, #3 (or \fx{\CurrentKey}) for the current key name, and #4 (or \fx{\CurrentVal}) for the value of the current key. If \fx{\CurrentVal} contains undefined macros or active characters, then attempting to print it may cause problems. Therefore, when making entries in the transcript file, it will sometimes be preferable to use \fx{\InnocentVal} instead of \fx{\CurrentVal}. However, \fx{\InnocentVal} will give only the first eight characters of a key's value.

The following example provides an unknown key handler for two key prefixes (\ffx'{KVA, KVB}) and two key families (\ffx'{fam1,fam2}):

\start{example}[\ltxkeys@unknownkeyhandler]
\ltxkeys@unknownkeyhandler[KVA,KVB]{fam1,fam2}{%
  \@expandtwoargs\in@{,#3,}{,\myspecialkeylist,}%|amref(mac:handledkey)
  \ifin@
    % The reader may want to investigate what the parameter
    % characters ##1 and ####1 here stand for:
    \ltxkeys@ordkey[#1]{#2}{#3}[#4]{\def\x####1{####1xx##1}}%
  \else
    \@ltx@warn{Unknown key `#3' with value `#4' in family `#2' ignored}\@ehd
    % \@ltx@warn{Unknown key `\CurrentKey' with value
    %   `\InnocentVal' in family `\CurrentFam' ignored}\@ehd
  \fi
}
\finish{example}

The macro \fx{\myspecialkeylist} in the above example doesn't actually exist; it is only meant for illustration here. But \quoted{handled keys} may be introduced by the user to serve this purpose. This will be the set of keys for which special actions may apply at key setting time (see \amref{sec:}).


\Note Similar to \fx{\ltxkeys@unknownkeyhandler} (which applies to keys), there is also the \fxi{\ltxkeys@unknownoptionhandler} (which applies to package or class options---see \amref{sec:}).


\docsection{Checking if a key is defined}

  \ltxkeys@ifkeydefTF[<prefs>]{<fams>}{<key>}{<true text>}{<false text>}
  \ltxkeys@ifkeydefFT[<prefs>]{<fams>}{<key>}{<false text>}{<true text>}

These check if \ang{key} is defined with a prefix in <prefs> and in family in \ang{fams}.



\docsection{Disabling keys}

  \ltxkeys@disablekeys[<prefs>]{<fams>}{<keys>}
  \ltxkeys@disablekeys*[<prefs>]{<fams>}{<keys>}

The command \fx{\ltxkeys@disablekeys} causes an error to be issued when a disabled key is invoked. If the package option 'verbose' is true, undefined keys are highlighted by \fx{\ltxkeys@disablekeys} with a warning message. Because it is possible to mix prefixes and families in \fx{\ltxkeys@disablekeys}, undefined keys may be readily encountered. To see those undefined keys, enable the package option 'verbose'.

The plain form of \fx{\ltxkeys@disablekeys} disables the given keys instantly, while the \stform  variant disables the keys at \hx{\AtBeginDocument}. Authors can use this command to bar users of their keys from calling those keys after a certain point.


\docsection{Option and non-option keys}

Sometimes you want to create keys that can only appear in \hx{\documentclass}, \hx{\RequirePackage} or \hx{\usepackage}, and at other times you may not want the user to submit a certain set of keys via these commands. The \pkg'{xwatermark}, for example, uses this concept.

  \option@keys[<pref>]{<fam>}{<keys>}
  \option@keys*[<pref>]{<fam>}{<keys>}
  \notoption@keys[<pref>]{<fam>}{<keys>}

Keys listed in \option@keys can appear only in arguments of \hx{\documentclass}, \hx{\RequirePackage} or \hx{\usepackage}, while keys listed in \notoption@keys can't appear in these macros. The \stform of \option@keys is equivalent to \notoption@keys. Only defined keys may appear in \option@keys and \notoption@keys.

  \makeoption@keys[<pref>]{<fam>}
  \makeoption@keys*[<pref>]{<fam>}

The command \makeoption@keys makes all the keys with prefix <pref> and in family <fam> options keys. The \stform of \makeoption@keys is equivalent to \makenotoption@keys.


\docsection{Declaring and processing options}

  \ltxkeys@declareoption[<pref>]<<fam>>{<key>}[<default>]{<callback>}
  \ltxkeys@declareoption*[<pref>]<<fam>>{<key>}[<default>]{<callback>}

The command \fx{\ltxkeys@declareoption} is simply a form of \fx{\ltxkeys@ordkey}, with the difference that the key family <fam> is now optional and, when specified, must be given in angled brackets. The default family name is \quotedhx{\@currname.\@currext}, \ie, the name of the class file or package and its file extension.

The \stform of \fx{\ltxkeys@declareoption} prescribes the default action to be taken when undefined options with prefix <pref> and in family <fam> are passed to class or package. You may use \fx{\CurrentKey} and \fx{\CurrentVal} within this macro to pass the unknown option and its value to another class or package or to specify other actions. In fact, you can use \fx{#1} in this macro to represent the current key prefix, \fx{#2} for the current family, #3 for the current key name, and #4 for the value of the current key. The command \fx{\ltxkeys@unknownoptionhandler} is equivalent to the \stform of \fx{\ltxkeys@declareoption}.

\Note The \stform of \fx{\ltxkeys@declareoption} differs from the \stform of LaTeX's \hx{\DeclareOption} and the \stform of \pkg'{xkeyval}'s \hx{\DeclareOptionX}.

  +++
  Examples (of use of \stform of \fx{\ltxkeys@declareoption}):

  \ltxkeys@declareoption*[KV]<mypackage>{%
    \PackageWarning{mypackage}{%
      Unknown option `\CurrentKey' with value `\CurrentVal' ignored}%
  }

  \ltxkeys@declareoption*{\PassOptionsToClass{#3}{article}}

  \ltxkeys@unknownoptionhandler[KV]<mypackage>{%
    % The macro \myextraoptions doesn't actually exist;
    % it is only meant for illustration here:
    \@expandtwoargs\in@{,#3,}{,\myextraoptions,}%
    \ifin@
      % The reader may want to investigate what the parameter characters
      % ##1 and ####1 here stand for:
      \ltxkeys@ordkey[#1]{#2}{#3}[#4]{\def\x####1{####1xx##1}}%
    \else
      \PassOptionsToClass{#3}{myclass}%
    \fi
  }
  +++

  \ltxkeys@declarecmdoption[<pref>]<<fam>>[<mp>]{<key>}[<default>]{<callback>}
  \ltxkeys@declarebooloption[<pref>]<<fam>>[<mp>]{<key>}[<default>]{<callback>}
  \ltxkeys@declarechoiceoption[<pref>]<<fam>>[<mp>]{<key>}[<default>]{<callback>}

These are the equivalents of \ffx'{\ltxkeys@cmdkey, \ltxkeys@boolkey, \ltxkeys@choicekey}, respectively, but now the family <fam> is optional (as is \ang{pref}) and, when specified, must be given in angled brackets. The default family name for these new commands is \quotedhx{\@currname.\@currext}, \ie, the current style or class filename and filename extension.


  \ltxkeys@executeoptions[<pref>]<<fams>>[<na>]{<key-val>}

This executes/sets the key-value pairs given in \keyval. The optional \ang{na} specifies the list of keys (without values) to be ignored. \ang{fams} signifies families in which the keys suggested in \keyval have been defined. The command \fx{\ltxkeys@executeoptions} can thus be used to process keys from several families.


  \ltxkeys@processoptions[<pref>]<<fams>>[<na>]
  \ltxkeys@processoptions*[<pref>]<<fams>>[<na>]

The command \fx{\ltxkeys@processoptions} processes the keys and values passed by the user to the class or package. The optional argument \ang{na} can be used to specify keys that should be ignored. The optional argument \ang{fams} can be used to specify the families that have been used to define the keys. This macro doesn't protect expandable macros in the user inputs unless the \pkg'{catoptions} is loaded before \hx{\documentclass}, in which case it might be better using the command \hx{\XProcessOptions} of the \pkg'{catoptions}. When used in a class file, the macro \fx{\ltxkeys@processoptions} will ignore unknown keys or options. This allows the user to use global options in the \hx{\documentclass} command which can be inherinted by packages loaded afterwards.

The \stform of \fx{\ltxkeys@processoptions} works like the plain variant except that it also copies user input from the \hx{\documentclass} command. When the user specifies an option in the \hx{\documentclass} which also exists in the local family or families of the package issuing \fx{\ltxkeys@processoptions}\RedStar, the local key too will be set. In this case, \fx{#1} in the \fx{\ltxkeys@declareoption} (or a similar command) will be the value entered in the \hx{\documentclass} command for this key. First the global options from \hx{\documentclass} will set local keys and afterwards the local options, specified via \hx{\usepackage}, \hx{\RequirePackage} or \hx{\LoadClass}, will set local keys, which could overwrite the previously set global options, depending on the way the options sections are constructed.


\docsection{Handled keys}

As mentioned in \amref{sec:}, handled keys are keys defined in a macro that is key-prefix and key-family dependent. They are defined as a list in a macro so that they can be used for future applications, such as deciding if a dependant key of a style key should be defined or redefined on the fly. Handled keys should be defined, or added to, using key prefix, family and key names. You can define or add to handled keys by the following command:

\start{newmacro}[\ltxkeys@handledkeys]
\ltxkeys@handledkeys[|A(pref)]{|A(fam)}{|A(list)}
\finish{newmacro}
\fxim*{\ltxkeys@handledkeys}

where \ang{list} is a comma-separated list of key names. This command can be issued more than once for the same key prefix \ang{pref} and family \ang{fam}, since the content of \ang{list} is usually merged with the existing list rather than being merely added or overwritten.

\start{example}[\ltxkeys@handledkeys]
\ltxkeys@handledkeys[KVA,KVB]{fam1,fam2}{keya,keyb,keyc}
\finish{example}

For a given key prefix \ang{pref} and family \ang{fam}, you can recall the full list of handled keys (set up earlier by \fx{\ltxkeys@handledkeys}) by the command

\start{macro}[List of handled keys]
\|A(pref)@|A(fam)@handledkeys
\finish{macro}
\aidx*{Recalling the list of handled keys}
% \ipreffam{handledkeys}

If handled keys have been set up in, \eg, \fx{\KV@fam@handledkeys}, the example at \amref{mac:handledkey} can be recast as follows:

\start{example}[\ltxkeys@handledkeys]
\ltxkeys@unknownkeyhandler[KVA,KVB]{fam1,fam2}{%
  \@expandtwoargs\in@{,#3,}{,\KV@fam@handledkeys,}%
  \ifin@
    \ltxkeys@ordkey[#1]{#2}{#3}[#4]{\def\x####1{####1xx##1}}%
  \else
    \@ltx@warn{Unknown key `#3' with value `#4' in family `#2' ignored}\@ehd
  \fi
}
\finish{example}

You can remove handled keys from a given list of handled keys (in a family) by the following command:

\start{newmacro}[\ltxkeys@removehandledkeys]
\ltxkeys@removehandledkeys[|A(pref)]{|A(fam)}{|A(list)}
\finish{newmacro}
\fxim*{\ltxkeys@removehandledkeys}

Rather than remove individual handled keys from a list, you might prefer or need to simply undefine or \quoted{emptify} the entire list of handled keys in a family. You can do these with the following commands:

\start+{newmacro}[\ltxkeys@undefhandledkeys,\ltxkeys@emptifyhandledkeys]
\ltxkeys@undefhandledkeys[|A(pref)]{|A(fam)}
\ltxkeys@emptifyhandledkeys[|A(pref)]{|A(fam)}
\finish{newmacro}
\fxim*{\ltxkeys@undefhandledkeys,\ltxkeys@emptifyhandledkeys}


\docsection{Bad key names}

Some key names are indeed inadmissible. The \pkg{ltxkeys} considers the following key names as inadmissible:

\start'{macro}[default bad keys]
.code,ordkey,cmdkey,stylekey,choicekey,boolkey,handledkeys,presetkeys,postsetkeys
\finish{macro}

For reasons of efficiency, the \pkg{ltxkeys} will attempt to catch bad key names only if the package option \fx{verbose} is enabled.

You can add to the list of invalid key names by the following command:

\start{newmacro}[\ltxkeys@badkeynames]
\ltxkeys@badkeynames{|A(list)}
\finish{newmacro}
\fxim*{\ltxkeys@badkeynames}

where \ang{list} is a comma-separated list of inadmissible names. The updating is done by merging, so that entries are not repeated in the internal list of bad key names.

You can remove from the list of bad key names by using the following command:

\start{newmacro}[\ltxkeys@badkeynames]
\ltxkeys@removebadkeynames{|A(list)}
\finish{newmacro}
\fxim*{\ltxkeys@removebadkeynames}

where, again, \ang{list} is comma-separated.

TO-DO:

1. Reserved key names, reserved key prefixes, reserved key families.


\end{document}