-
Notifications
You must be signed in to change notification settings - Fork 0
/
keyvaltable.dtx
4676 lines (4675 loc) · 184 KB
/
keyvaltable.dtx
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
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% \iffalse meta-comment
%
% Copyright (C) 2016-2020 by Richard Grewe <[email protected]>
% -------------------------------------------------------
%
% Thie file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
% https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008 or later.
%
% This file has the LPPL maintenance status "maintained".
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{keyvaltable.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{keyvaltable}
%<*package>
[2020/08/09 v2.3 Package for filling tables using key-value lists]
%</package>
%
%<*driver>
\documentclass[svgnames]{ltxdoc}
\usepackage{rgltxdoc}[2019/12/21 v1.3]
\usepackage{etoc}
\usepackage{amssymb}% \checkmark
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\usepackage{xspace}
\newcommand\thispackage{\pkgname{keyvaltable}\xspace}
% the following packages are additional for the examples
\usepackage{xintexpr}
\usepackage{makecell,cellspace}
\usepackage{gensymb}% for \degree
\usepackage{tabularx,longtable,xltabular,tabu}
\usepackage{filecontents}
\usepackage{keyvaltable}
\usepackage{datatool,csvsimple}
\NewKeyValTable[
showhead=false,headformat={\bfseries\footnotesize},
rowbg=black!7!white..black!3!white,
showrules=false,
backend=tabu]{GoalApproach}{
id: align=r, default=(\alph{kvtRow}), head=\#;
goal: align=X[l];
approach: align={X[2,l]};
}
\newcommand\RecipePreset{%
\NewKeyValTable{Recipe}{amount:align=r;ingredient:align=l;step:align=X}}
%
\usepackage{fontawesome}
\makeatletter
\newenvironment{NiceText}[2]{%
\medskip\par\noindent
\rgltxdoc@inmargin{\smash{\textcolor{#1}{\large#2}}}{\quad}%
\ignorespaces}{\medskip\par\noindent}
\newenvironment{NiceNote}{\NiceText{DarkBlue}{\faInfoCircle}}{\endNiceText}
\newenvironment{NiceTipp}{\NiceText{DarkBlue}{\faLightbulbO}}{\endNiceText}
\newenvironment{NiceWarn}{\NiceText{DarkBlue}{\faWarning}}{\endNiceText}
% \end{macrocode}
\makeatother
%
\begin{filecontents*}{recipes.csv}
id,amount,ingredient,step
snowman,3,balls of snow,staple all 3 balls
snowman,1,carrot,stick into top ball
snowman,2,coffee beans,put diagonally above carrot
cherries,150g,ice cream,put into bowl
cherries,50g,cherries,heat up and add to bowl
\end{filecontents*}
%
\begin{document}
\DocInput{keyvaltable.dtx}
\PrintChanges
\PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
% Digits \0\1\2\3\4\5\6\7\8\9
% Exclamation \! Double quote \" Hash (number) \#
% Dollar \$ Percent \% Ampersand \&
% Acute accent \' Left paren \( Right paren \)
% Asterisk \* Plus \+ Comma \,
% Minus \- Point \. Solidus \/
% Colon \: Semicolon \; Less than \<
% Equals \= Greater than \> Question mark \?
% Commercial at \@ Left bracket \[ Backslash \\
% Right bracket \] Circumflex \^ Underscore \_
% Grave accent \` Left brace \{ Vertical bar \|
% Right brace \} Tilde \~}
%
% \changes{v0.1}{2016/03/13}{Initial version}
% \changes{v0.3b}{2018/11/01}{Package author's name change}
%
% \GetFileInfo{keyvaltable.dtx}
%
% \DoNotIndex{\newcommand,\newenvironment,\def,\gdef,\edef}
%
%
% \title{The \thispackage package\thanks{This document
% corresponds to \thispackage~\fileversion, dated \filedate.
% The package is available online at
% \url{http://www.ctan.org/pkg/keyvaltable} and
% \url{https://github.com/Ri-Ga/keyvaltable}.}}
% \author{Richard Grewe \\ \texttt{[email protected]}}
%
% \maketitle
%
% \begin{abstract}\noindent
% The \thispackage package's main goal is to facilitate
% typesetting tables\ldots\medskip\\
% \begin{KeyValTable}{GoalApproach}
% \Row{
% goal={\ldots easily and yet still looking rather nicely},
% approach={through horizontal rules and alternating row background
% colors by default;}}
% \Row{
% goal={\ldots in a way that separates content from presentation},
% approach={by table rows that are specified as lists of key-value
% pairs, where the keys are column names and the corresponding
% values are the content of the cell in this row in the respective
% column;}}
% \Row{
% goal={\ldots with re-usable layout for tables of the same type},
% approach={through named table types, of which each has a list of
% columns as well as further properties such as the background
% colors of rows; each column, in turn, has a name as well as
% further properties such as the heading of the column and the
% alignment of the column's content.}}
% \end{KeyValTable}
% \end{abstract}
%
% \etocsetnexttocdepth{1}
% \etocmulticol[2]{\section*{Contents}}
% \clearpage
%
% \section{Basic Usage}\label{sec:basic}
%
% We start with a basic usage example. An explanation of the involved
% macros follows afterwards.\medskip
%
% \begin{LTXexample}[morekeywords={NewKeyValTable,Row,KeyValTable}]
% \NewKeyValTable{Recipe}{
% amount: align=r;
% ingredient: align=l;
% step: align=X;
% }
% \begin{KeyValTable}{Recipe}
% \Row{amount=150g, ingredient=ice cream,
% step=put into bowl}
% \Row{amount= 50g, ingredient=cherries,
% step=heat up and add to bowl}
% \end{KeyValTable}
% \end{LTXexample}
% The example code first defines a new table type, |Recipe|, along with
% the columns that belong to this type. There are three columns
% (|amount|, |ingredient|, and |step|), whose specifications are separated
% with semicolons. After the separating |:|, for each column, the macro
% configures the column alignment using the |align| key. The alignments
% |r| (right) and |l| (left) are the standard |tabular| alignments; the
% |X| alignment is provided by the \pkgname{tabularx} package (see the
% documentation there).
%
% After defining the table type, the example creates a table of
% the newly defined type. For this, the example uses the |KeyValTable|
% environment and the |\Row| macro, once for each row. The parameter
% |Recipe| of the |KeyValTable| identifies the type of the table.
% In the parameter of the |\Row| macro, the content of the individual
% cells can be specified by key-value pairs such as |amount=150g|, which
% puts ``150g'' into the |amount| column of the respective row.
%
% The example above already shows that producing a rather nice-looking
% table -- including alternating row colors as well as horizontal rules
% -- without further ado. How the \thispackage package can be
% used in the general case and how its visual appearance can be
% customized is subject of the remainder of this documentation.
%
% \begin{NiceTipp}
% To quickly sketch a table type, one can even omit properties
% of columns and just list their names, separated by semicolons, as the
% following example shows. All columns then get the default alignment:
% |l|.
% \end{NiceTipp}
% \begin{LTXexample}
% \NewKeyValTable{Recipe}{amount;ingredient;step}
% \begin{KeyValTable}{Recipe}
% \Row{amount=150g, ingredient=ice cream,
% step=put into bowl}
% \Row{amount= 50g, ingredient=cherries,
% step=heat up and add to bowl}
% \end{KeyValTable}
% \end{LTXexample}
%
%
% \section{Defining Table Types}
%
% As the example in \cref{sec:basic} shows,
% |\NewKeyValTable| defines a table type.
%
% \NiceDescribeMacro{\NewKeyValTable}{\oarg{options}\marg{tname}\marg{colspecs}\oarg{layout}}
% The macro defines a table type with name \meta{tname} whose columns
% are specified by \meta{colspecs}.
% The \meta{colspecs} parameter must be a semicolon-separated list.
% Each column specification is of the form
% \begin{center}
% \meta{colname}|:| \meta{property}|=|\meta{value}|,|
% \meta{property}|=|\meta{value}|,|\ldots
% \end{center}
% In such a specification, \meta{colname} represents the name of the
% column. The \meta{property}|=|\meta{value} pairs configure certain
% properties of the column. The \meta{property} can be one of the
% following:
%
% \NiceDescribeKey{align}{vals={l,c,r,p,X,\ldots}, init=l}
% This property specifies the alignment of content in the
% column. The \meta{value} can be set to any column alignment
% understood by table environments.\footnote{More complex values, for
% instance using the notation of the \pkgname{array} package for
% inserting material before or after a column, are permitted but not
% further tested. Use at your own risk.}
%
% \NiceDescribeKey{default}{vals=\vmeta{content}, init=\vmeta{empty}}
% This property specifies the default \meta{content} of a cell in this
% column, i.e., in case that a \cmd{\Row} does not provide content for
% the cell. Initially (i.e., if unset for a column), this is an
% empty string.
%
% \NiceDescribeKey{format}{vals=\vmeta{single argument macro}, init=\vmeta{"identity"}}
% This property specifies a formatting macro for content of the cell.
% The macro can take one argument and is provided with the content of
% the cell as its argument. Initially, the format is defined to take
% the content as is.\footnote{Prior to version~2.3 of \thispackage,
% the initial format setting was to put \cmd{\strut} before and after
% the content to yield a better vertical row spacing in some
% situations. See also \cref{sec:VertSpacing}.}
%
% \NiceDescribeKey{head}{vals=\vmeta{content}, init=\vmeta{colname}}
% This property specifies the \meta{content} of the column's header
% row. The initial value for this property is the name of the column.
%
% \NiceDescribeKey{hidden}{vals={true,false}, init=false, def=true}
% This property specifies whether a table column shall be displayed or
% not. The \meta{value} for this property can be |true| (to hide the
% cell) or |false| (to display the cell). Using |hidden| without
% \meta{value} is equivalent to specifying |hidden=true|.
%
% The following example shows all of the above column properties in
% action.
%
% \begin{LTXexample}[morekeywords={align,default,format,head,hidden}]
% \NewKeyValTable{ShoppingList}{
% what: head=article, format=\textbf;
% amount: align=r, default=1;
% why: hidden;
% }
% \begin{KeyValTable}{ShoppingList}
% \Row{what=melon}
% \Row{what=apples, amount=6}
% \Row{what=bicycle, why=Bob's birthday}
% \end{KeyValTable}
% \end{LTXexample}
%
% The \meta{options} and \meta{layout} parameters of |\NewKeyValTable|
% are described in \cref{sec:TableAppearance} and, respectively,
% \cref{sec:CustomHeaders} of this documentation.
%
%
% \section{Typesetting Tables}\label{sec:typesetting-tables}
%
% The \thispackage package offers three possibilities for typesetting
% tables.
% The first is in the traditional \hologo{LaTeX} form, in which there is
% an environment that encloses the individual row specifications.
% The second possibility is to specify rows throughout the document, bind
% them to a name, and finally typeset a table from all rows bound to
% the particular name.
% The third possibility is to source the row specifications from a
% file.
%
% \subsection{Specifying Rows in a Table Environment}
%
% The first possibility for typesetting a table using the
% \thispackage package, is via the |KeyValTable| environment.
% \cref{sec:basic} presents an example of this possibility.
%
% \NiceDescribeEnv{KeyValTable}{\oarg{options}\marg{tname}}
% The |KeyValTable| environment creates a table of type \meta{tname}.
% The type \meta{tname} must have been created using |\NewKeyValTable|
% before. The environment itself already produces a table with the
% columns specified for the table type, produces a header row and some
% horizontal lines, and sets up background colors of rows.
% The \meta{options} are described in \cref{sec:TableAppearance}.
%
% \NiceDescribeMacro{\Row}{\oarg{options}\marg{content}}
% A table row is produced by the |\Row| macro. The
% \meta{content} must be a comma-separated list of
% \meta{cname}|=|\meta{text} pairs. The \meta{cname} identifies a column
% that was registered for the table type \meta{tname}. The \meta{text}
% specifies the content of the cell in the respective column. Each
% column for which no \meta{text} is provided in \meta{content}, will
% result in a cell that is filled with the column's default value.
% The \meta{options} argument customizes row properties and is further
% explained in \cref{sec:RowOptions}.
%
%
% \subsection{Tables of Collected Rows}\label{sec:collected}
%
% The content of a table's rows might logically belong to locations that
% are scattered throughout a document, e.g., to individual sections of
% the document. In this situation, it can be convenient to have the rows
% specified close to the locations their contents belong to, instead of
% specified in the table environment.
%
% The following example illustrates the use of this feature for taking
% and collecting notes in a document:
% \begin{LTXexample}[width=0.475\hsize,morekeywords={NewCollectedTable,CollectRow,ShowCollectedTable}]
% \NewKeyValTable{Notes}{type; text}
% \NewCollectedTable{notes}{Notes}
%
% \subsection*{Notes}
% \ShowCollectedTable{notes}
%
% \section{Introduction}
% \CollectRow{notes}{type=remark, text=intro too long}
% Lorem ipsum dolor sit amet, \ldots
%
% \section{Analysis}
% \CollectRow{notes}{type=task, text=proofread Analysis}
% Lorem ipsum dolor sit amet, \ldots
% \end{LTXexample}
% See \cref{sec:referencing} on how to (automatically) include
% references to, e.g., section or page numbers in tables.
% The key macros (highlighted in bold font) used in the example are the
% following three.
%
% \NiceDescribeMacro{\NewCollectedTable}{\marg{cname}\marg{tname}}
% This macro defines the name \meta{cname} for a new collection of
% rows. The collection is associated with the table type \meta{tname}.
% This macro must be used before |\CollectRow| for a \meta{cname}.
%
% \NiceDescribeMacro{\CollectRow}{\oarg{options}\marg{cname}\marg{content}}
% This macro adds the row content \meta{content} and row options
% \meta{options} to the row collection \meta{cname}.
%
% \NiceDescribeMacro{\ShowCollectedTable}{\oarg{options}\marg{cname}}
% This macro typesets a table of the row collection \meta{cname}, with
% the table options \meta{options}.
% The table includes rows that are collected only afterwards in the
% document. For this, \hologo{LaTeX} must be run at least two times.
%
%
% \subsection{Sourcing Rows From a File}
%
% Rather than specifying the rows of a table inside a |KeyValTable|
% environment, the rows can also be sourced from a file.
% More concretely, this file must consist of the |\Row| macros that
% specify the content of the rows.
% For information on how to source rows from CSV files, see
% \cref{sec:CSV}.
%
% \NiceDescribeMacro{\ShowKeyValTableFile}{\oarg{options}\marg{tname}\marg{filename}}
% This macro produces a |KeyValTable| environment of type \meta{tname}
% whose content is taken from the file \meta{filename}.
% The \meta{options} specify the table options, which are directly
% passed to the options argument of the |KeyValTable| environment.
%
% \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={ShowKeyValTableFile}]
% \begin{filecontents}{snowman.kvt}
% \Row{amount=3, ingredient=balls of snow,
% step=staple all 3 balls}
% \Row{amount=1, ingredient=carrot,
% step=stick into top ball}
% \Row{amount=2, ingredient=coffee beans,
% step=put diagonally above carrot}
% \end{filecontents}
% \ShowKeyValTableFile{Recipe}{snowman.kvt}
% \end{LTXexample}
%
%
% \subsection{Tables of Collected Rows (Legacy Interface)}
%
% This section documents legacy functionality of \thispackage, that is
% now superseded by the functionality described in \cref{sec:collected}.
% The legacy functionality compares to the new functionality as follows:
% \begin{itemize}[noitemsep]
% \item Rows must be collected \emph{before} the place in the document
% where they are displayed in a table.
% \item For each table type, there can be only one collection of rows.
% After the collection has been typeset in a table the collection is
% emptied again.
% \item Row content is not written into the aux file. This might be
% relevant for very large tables.
% \end{itemize}
% The following macros and environments implement the functionality.
%
% \NiceDescribeMacro{\AddKeyValRow}{\marg{tname}\oarg{options}\marg{content}}
% A table row is produced by the
% |\AddKeyValRow| macro. The \meta{tname}
% identifies the table type and the \meta{content} provides the content
% of the cells in the row. The format of the \meta{content} is the same
% as for the |\Row| macro described in
% Section~\ref{sec:typesetting-tables}.
%
% \NiceDescribeMacro{\ShowKeyValTable}{\oarg{options}\marg{tname}}
% A table of all the rows defined via |\AddKeyValRow| can be displayed
% by the |\ShowKeyValTable| macro. The
% parameters have the same meaning as for the |KeyValTable| environment.
% This macro resets the list of rows for the specified table type.
%
% \NiceDescribeEnv{KeyValTableContent}{\marg{tname}}
% For simplifying the addition of rows, the
% |KeyValTableContent| environment can be used. In this
% environment, the |\Row| macro can be used just like in the
% |KeyValTable| environment. The only difference is that the
% |KeyValTableContent| environment does not cause the table to be
% displayed. For displaying the content collected in
% |KeyValTableContent| environments, the |\ShowKeyValTable| macro can be
% used.
%
% The following example demonstrates the use, based on the previously
% defined |Recipe| table type.
% \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={AddKeyValRow,KeyValTableContent,ShowKeyValTable}]
% \AddKeyValRow{Recipe}{amount=3,
% ingredient=balls of snow,
% step=staple all 3 balls}
% \begin{KeyValTableContent}{Recipe}
% \Row{amount=1, ingredient=carrot,
% step=stick into top ball}
% \Row{amount=2, ingredient=coffee beans,
% step=put diagonally above carrot}
% \end{KeyValTableContent}
% \ShowKeyValTable{Recipe}
% \end{LTXexample}
%
%
% \section{Row Numbering\,\&\,Labeling}\label{sec:row-numbering}
%
% The mechanism of default column values enables a simple means for
% automatic row numbering, labeling, and referencing document entities.
%
% \subsection{Row Numbering}
%
% For row numbering, one can use one of three row counters provided by
% the \thispackage package: |kvtRow|, |kvtTypeRow|, and |kvtTotalRow|.
% The counters are explained after the following example, which
% demonstrates the use for the case of the |kvtRow| counter.
%
% \begin{LTXexample}[morekeywords={thekvtRow,thekvtTypeRow}]
% \NewKeyValTable[headformat=\textbf]{Numbered}{
% line: align=r, head=\#,
% format=\textbf,
% default=\thekvtRow;
% text: align=l, head=Text}
% \begin{KeyValTable}{Numbered}
% \Row{text=First row}
% \Row{text=Second row}
% \end{KeyValTable}
% \end{LTXexample}
%
% \NiceDescribeCounter{kvtRow}{}
% The |kvtRow| counter counts the row in the \emph{current} table. The
% row number excludes the header row of the table. If the table spans
% multiple pages, the row number also excludes the repeated headings on
% subsequent pages.
%
% \NiceDescribeCounter{kvtTypeRow}{}
% The |kvtTypeRow| counter counts the rows in the current table and
% includes the number of rows of all previous tables of the same type.
%
% \NiceDescribeCounter{kvtTotalRow}{}
% The |kvtTotalRow| counter counts the rows in the current table and
% includes the number of rows of all previous tables produced using the
% \thispackage package.
%
% By default, all rows are counted by the aforementioned counters.
% However, this default can be changed.
%
% \NiceDescribeKey{uncounted}{vals={true,false}, init=false, def=true}
% This row option specifies whether the row shall not be counted
% (|true|) or shall be counted (|false|).
% If only |uncounted| is used without a value, this is equivalent to
% |uncounted=true|.
% The following example illustrates the option.
%
% \begin{LTXexample}[morekeywords={uncounted},
% morepreset={\NewKeyValTable[headformat=\textbf]{Numbered}{
% line: align=r,head=\#,format=\textbf,default=\thekvtRow;
% text: align=l,head=Text}}]
% \begin{KeyValTable}{Numbered}
% \Row{text=First row}
% \Row[uncounted]{line={--}, text=interlude}
% \Row{text=Second row}
% \end{KeyValTable}
% \end{LTXexample}
%
% By default, all counters start at value $1$. Through the following
% possibilities, this behavior can be changed.
%
% \NiceDescribeKey{resume}{vals={true,false}, init=false, def=true}\label{opt:resume}
% This option is available in |KeyValTable| environments. When this
% option is set to |true|, the value of the |kvtRow| counter is resumed
% from the previous |KeyValTable| environment. The other two counters
% are not affected by this option.
%
% \subsection{Row Labeling}
%
% Row numbering can easily be combined with row labeling.
% The following example shows how the |format| column property can be
% used for this purpose.
% \begin{LTXexample}[morekeywords={kvtLabel}]
% \NewKeyValTable{Labeled}{
% label: align=r, head=\textbf{\#},
% format=\kvtLabel{kvtRow};
% text: align=l, head=\textbf{Text}}
% \begin{KeyValTable}{Labeled}
% \Row{text=First row, label=first}
% \Row{text=After row \ref{first}}
% \end{KeyValTable}
% \end{LTXexample}
%
% \NiceDescribeMacro{\kvtLabel}{\oarg{labelopts}\marg{counter}\marg{label}}
% The |\kvtLabel| macro shows the current value of the \meta{counter} --
% in particular |kvtRow|, |kvtTypeRow|, and |kvtTotalRow| -- and sets
% the \meta{label} to the value of \meta{counter}. When using the macro
% with the |format| property, only the first argument (\meta{counter})
% must be provided, as the above example shows. The second argument
% (\meta{label}) is provided by the respective cell content.
%
% The |\kvtLabel| macro should work well with packages that change the
% referencing, like \pkgname{cleveref} or \pkgname{varioref}. When using a
% package that adds an optional argument to the |\label| command (like
% \pkgname{cleveref} does), the \meta{labelopts} can be used to pass an
% optional argument to |\label|. This feature is demonstrated in
% \cref{sec:package-cleveref}.
%
% \subsection{Referencing in Collected Rows}\label{sec:referencing}
%
% The previous sections show examples of referencing row numbers.
% In tables of collected rows, it may be desirable to reference the
% point in the document at which a row was collected.
% The example in \cref{sec:collected} illustrates such a situation.
% In the following, we augment that example by references to section and
% page numbers.
%
% \begin{LTXexample}[width=0.5\hsize,morekeywords={NewCollectedTable,CollectRow,ShowCollectedTable}]
% \NewKeyValTable{Notes2}{
% id: default=\thekvtRow.;
% type; text;
% where: default={\S\thesection\ (p.\@\thepage)};}
% \NewCollectedTable{notes2}{Notes2}
%
% \subsection*{Notes}
% \ShowCollectedTable{notes2}
%
% \section{Introduction}
% \CollectRow{notes2}{type=remark, text=intro too long}
% Lorem ipsum dolor sit amet, \ldots
%
% \section{Analysis}
% \CollectRow{notes2}{type=task, text=proofread!}
% Lorem ipsum dolor sit amet, \ldots
% \end{LTXexample}
%
% The above example demonstrates that the correct section number is
% referenced. Since the whole example is contained on a single page, the
% example does not demonstrate that the page number (|\thepage|) in the
% "where" column actually references the page in the document on which
% the |\CollectRow| takes place. Note that the correct page will be
% produced even when the |\CollectRow| is placed in a float, such as a
% figure or table.
% \begin{NiceWarn}
% \hologo{LaTeX} internally implements a special treatment of
% |\thepage| to make page references possible. For this reason, using
% something like |\arabic{page}| to produce the page number will
% presumably not work correctly.
% \end{NiceWarn}
%
% The \thispackage package
% \begin{itemize}[nosep]
% \item takes the values of row counters (like |\thekvtRow|) from the
% position of \emph{the row in the table}
% but
% \item takes the values of other counters such as the page counter and
% the section counter from the \emph{point in the document where
% \cmd{\CollectRow} is used}.
% \end{itemize}
% This takes into account that counter values can be obtained via
% \cmd{\the\meta{ctrname}} (like |\thekvtRow| or |\thepage|) as well as
% via macros like |\arabic|, |\roman| etc.
% The following macros allow for declaring additional counters and
% formatting macros to be taken into account by \thispackage.
%
% \NiceDescribeMacros{2}
% {\kvtDeclareTableMacros}{\marg{macro-list}}
% {\kvtDeclareTableCounters}{\marg{counter-list}}
% These macros take a comma-separated list of macros (respectively
% counters) and declares these as "table macros" ("table counters").
% A macro or counter declared this way is expanded only inside the table
% environment and not at the point where |\CollectRow| is used.
% The \thispackage already declares |\thekvtRow|, |\thekvtTypeRow|, and
% |\thekvtTotalRow| as table macros and declares |kvtRow|, |kvtTypeRow|,
% and |kvtTotalRow| as table counters.
%
% \NiceDescribeMacro{\kvtDeclareCtrFormatters}{\marg{macro-list}}
% This macro takes a comma-separated list of macros and declares them as
% macros for formatting counter values. Examples for such macros are
% |\arabic|, |\alph|, |\Alph|, |\roman|, |\Roman|, |\fnsymbol|, which
% \thispackage already declares.
% When other counter-formatting macros shall be used in the |default|
% value of a column, such as |\ordinal| of the \pkgname{fmtcount}
% package, they have to be passed to |\kvtDeclareCtrFormatters| first.
%
%
% \section{Changing the Appearance}
%
% The appearance (e.g., colors, rules) of a table can be changed at
% the level of the overall table as well as for individual rows,
% columns, and cells.
%
% \subsection{Table Appearance}\label{sec:TableAppearance}
%
% The appearance of a table can be configured through the \meta{options}
% parameters of
% \begin{itemize}[nosep]
% \item |KeyValTable|, |\ShowKeyValTable|, and |\ShowKeyValTableFile|
% (affecting the particular table),
% \item |\NewKeyValTable| (affecting all tables of the table type), and
% \item |\kvtSet| (affecting all tables).
% \end{itemize}
% In this list, the former take precedence over the latter. That is,
% table options override table type options and table type options
% override global options for all tables.
%
% In each case, \meta{options} must be specified as a comma-separated
% list of \meta{property}|=|\meta{value} pairs.
% The following \meta{property} keys can be configured.
%
% \NiceDescribeKeys{2}
% {backend}{vals={tabular,tabularx,longtable,xltabular,tabu,longtabu}}
% {shape}{vals={multipage,onepage}, init=multipage}
% The |backend| property specifies the table environment to be used for
% producing the table. A set of six environments is currently supported,
% including environments that can span multiple pages and environments
% whose columns can stretch/shrink to fill the available space ("|X|"
% columns).
% The |shape| property abstracts from the concrete environments.
% In case of |multipage|, the table may span multiple pages and
% depending on whether |X|-columns are used or not, an appropriate
% environment is selected. In case of |onepage|, the table does not
% split into multiple pages.
% See \cref{sec:AltTabEnv} for more details on the available shapes and
% backends.
% Only one of |shape| and |backend| can be specified. If both are
% specified, the property that is specified last wins.
%
% \NiceDescribeKey{width}{vals=\vmeta{dimension}, init=\cmd\linewidth}
% This property specifies the width of the table, if the selected
% |shape|/|backend| supports it (see \cref{sec:AltTabEnv}).
%
% \NiceDescribeKeys{2}
% {valign}{vals={t,c,b}, init=\vmeta{empty}}
% {halign}{vals={l,c,r}, init=\vmeta{empty}}
% These two properties specify the vertical and, respectively, horizontal
% alignment of the table, if the selected |shape|/|backend| supports it (see
% \cref{sec:AltTabEnv}).
%
% \NiceDescribeKey{showhead}{vals={true,false}, init=true}
% This property specifies whether the header row shall be shown. The
% \meta{value} must be a Boolean (i.e., |true| or |false|), where |true|
% specifies that the header row is shown and |false| specifies that the
% header row is not shown.
%
% \NiceDescribeKeys{2}
% {showrules}{vals={true,false}, init=true}
% {norules}{vals={true,false}, init=false, def=true}
% The |showrules| property specifies whether top and bottom rules as
% well as a rule below the header row are drawn (|true|) or not
% (|false|). The |norules| property serves the same purpose, but the
% value |true| hides the rules and the value |false| causes the rules to
% be drawn.
% Note that both properties only affect the rules that \thispackage
% produces automatically; rules manually added, e.g., via |\hline|,
% |\midrule|, or |\MidRule| (see Section~\ref{sec:rules}) are not
% affected by the properties.
%
% \NiceDescribeKey{headalign}{vals={\vmeta{empty} or \vmeta{coltype}}, init=\vmeta{empty}}
% This property specifies the alignment for header cells. If left
% empty, each header cell receives the same alignment as the respective
% column.
%
% \NiceDescribeKey{headbg}{vals=\vmeta{color}, init={black!14}}
% This property specifies the background color of the header rows. The
% \meta{color} must be a single color specification that is understood
% by the \pkgname{xcolor} package. The \meta{color} is passed directly
% to the \cs{rowcolor} macro. If \meta{color} is empty, then no
% background color is produced for the header row.
%
% \NiceDescribeKey{headformat}{vals=\vmeta{single argument macro}, init=\vmeta{"identity"}}
% This property specifies a format to be applied to all header cells.
% The value specified for the |headformat| key is used to format each
% header. The value can be a macro that takes once argument, through
% which it is provided the header (as specified in the column's |head|
% property). Initially, an "identity" macro is used, meaning that each
% |head| is taken without change.
%
% \NiceDescribeKey{rowbg}{vals=\vmeta{color}, init={white..black!10}}
% This property specifies the background colors of content rows. The
% \meta{value} for this property must be of the format
% \meta{oddcolor}|..|\meta{evencolor}. The first row after the header is
% colored with \meta{oddcolor}, the second row with \meta{evencolor},
% and so forth. Both colors must be understood by the \pkgname{xcolor}
% package. If \meta{color} is empty, then no background color is
% produced for content rows.
%
% \NiceDescribeKeys{2}
% {norowbg}{vals={true,false}, init=false, def=true}
% {nobg}{vals={true,false}, init=false, def=true}
% These properties are shorthands for |rowbg={}| (turning off
% background colors for content rows) and, respectively, for
% |rowbg={},headbg={}| (turning off background colors for header rows
% and for content rows). Using these options without a value is
% equivalent to using |true| for the value. For instance, |nobg| is
% equivalent to |nobg=true|.
%
% \vref{fig:TableOptionExamples} demonstrates the \meta{options} in
% examples.
% \begin{figure}
% \begin{LTXexample}[morekeywords={showhead,rowbg}]
% \kvtSet{format=\texttt}
% \NewKeyValTable[showhead=false,
% rowbg=blue!10..blue!15,
% ]{TabOptions}{opt; val}
% \begin{KeyValTable}{TabOptions}
% \Row{opt=showhead, val=false}
% \Row{opt=rowbg, val=blue!10..blue!15}
% \end{KeyValTable}
% \end{LTXexample}
% \begin{LTXexample}[morepreset={\kvtSet{format=\texttt}},morekeywords={showrules,headbg,headalign,headformat,halign,norowbg}]
% \NewKeyValTable[showrules=false,headbg=blue!25,
% headalign=c,headformat=\textbf,norowbg,
% halign=r,
% ]{TabOptions2}{opt; val}
% \begin{KeyValTable}{TabOptions2}
% \Row{opt=showrules, val=false}
% \Row{opt=headbg, val=blue!25}
% \Row{opt=headalign, val=c}
% \Row{opt=headformat, val=\string\textbf}
% \Row{opt=norowbg, val=true}
% \Row{opt=halign, val=r}
% \end{KeyValTable}
% \end{LTXexample}
% \begin{LTXexample}[morepreset={\kvtSet{format=\texttt}},morekeywords={nobg,norules,valign,shape,width}]
% \NewKeyValTable[valign=t,nobg,norules,
% shape=onepage,width=3cm,headformat=\textbf,
% ]{TabOptions3}{opt: align=X;}
% \begin{KeyValTable}{TabOptions3}
% \Row{opt=nobg}
% \Row{opt=norules}
% \end{KeyValTable}
% \begin{KeyValTable}{TabOptions3}
% \Row{opt={shape=onepage}}
% \Row{opt={valign=t}}
% \Row{opt={width=3cm}}
% \end{KeyValTable}
% \end{LTXexample}
% \caption{Examples for table options}
% \label{fig:TableOptionExamples}
% \end{figure}
%
% \subsubsection{Table Styles and Resumable Options}
%
% Rather than specifying properties for individual tables or table
% types, \thispackage also supports named \emph{table styles}.
%
% \NiceDescribeKey{style}{vals=\vmeta{list of style names}, init=\vmeta{empty}}
% Through this property of tables or table types, a list of styles can
% be applied to a single table or, respectively, a table type. Each
% style must have been defined with |\kvtNewTableStyle| before.
%
% \NiceDescribeMacro{\kvtNewTableStyle}{\marg{name}\marg{options}}
% This macro declares a new table style with the given \meta{name} and
% defines it to be equivalent to using the given \meta{options}.
% The \meta{name} must not already be defined.
%
% \NiceDescribeMacro{\kvtRenewTableStyle}{\marg{name}\marg{options}}
% This macro re-defines an existing table style \meta{name} with new
% \meta{options}.
%
% The following example demonstrates table styles for an individual
% table.
%
% \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={style,kvtNewTableStyle}]
% \kvtNewTableStyle{plain}{
% norules,nobg,headformat=\textbf}
% \begin{KeyValTable}[style=plain]{Recipe}
% \Row{amount=150g, ingredient=ice cream,
% step=put into bowl}
% \Row{amount= 50g, ingredient=cherries,
% step=heat up and add to bowl}
% \end{KeyValTable}
% \end{LTXexample}
%
% \begin{NiceNote}
% The \meta{options} in |\kvtNewTableStyle| can be left
% empty. In this case, the table style does not have any effect on the
% appearance of tables. However, the style can already be used for
% "tagging" tables and table types, while the final options for the
% style can be configured at a later point in time.
% \end{NiceNote}
%
% Even without table styles, the appearance of the previous
% |KeyValTable| can be used again through the following option.
% \NiceDescribeKey{resume*}{vals={true,false}, init=false, def=true}
% When set to |true|, this option makes the table use the options from
% the previous |KeyValTable| environment. This option also implies the
% |resume| option (see \vref{opt:resume}).
% If the previous environment also used |resume*|, then the options of
% its predecessor environment are used, and so forth.
% Note that this means that table options are not accumulated over
% subsequent uses of |resume*|.
% This behavior is the same as in the \pkgname{enumitem} package.
%
%
% \subsection{Column Appearance}
%
% Column appearance is configured through the parameters |align|,
% |head|, |format|, and |default| of columns in |\NewKeyValTable|.
%
%
% \subsection{Row Appearance}\label{sec:RowOptions}
%
% Through the \meta{options} argument of the
% |\Row|
% and the
% |\KeyValRow|
% macros, the appearance of rows can be configured.
% As with other option arguments of the \thispackage package, the
% options must be a comma-separated list of key-value pairs.
% The following options are supported.
%
% \NiceDescribeKey{hidden}{vals={true,false}, init=false, def=true}
% This property specifies whether the row shall be hidden (|true|) or
% not (|false|). If only |hidden| is used without a value, this is
% equivalent to |hidden=true|.
%
% \NiceDescribeKey{align}{vals={\vmeta{empty} or \vmeta{coltype}}, init=\vmeta{empty}}
% This property specifies the alignment of the cells in the row.
% If this property is not specified, the respective columns' alignment
% is used. The alignment applies to normal cells as well as to cells
% in column groups.\footnote{Note that the alignment does not override
% the alignment specified in any \cs{multicolumn} if it is assigned to
% a cell in the row.}
%
% \NiceDescribeKey{bg}{vals=\vmeta{color}, init=\vmeta{empty}}
% This property specifies the background color for the particular row.
% If this option is not specified (or set to an empty value
% explicitly), the background color is determined by the |rowbg|
% option of the table.
%
% \NiceDescribeKeys{3}
% {format}{vals=\vmeta{single argument macro}, init=\vmeta{"identity"}}
% {format*}{vals=\vmeta{single argument macro}, init=\vmeta{"identity"}}
% {format!}{vals=\vmeta{single argument macro}, init=\vmeta{none}}
% These properties specify formatting for all cells of the particular
% row. The difference between the three properties is how they
% interact with the column formats of the respective cells in the row.
% The |format| property is applied to the cell content \emph{before}
% the column format, and the |format*| property is applied
% \emph{after} the column format.
% The |format!| property overrides any column formats in the
% respective row and also renders the |format| and |format*|
% properties ineffective.
%
% \NiceDescribeKey{headlike}{vals={true,false}, init=false, def=true}
% This property, when used without a value or with value |true|,
% specifies that the row shall be formatted like a header row.
% Concretely, the alignment, background color, and format of the row's
% cells is then set to the values of the table's |headalign|,
% |headbg|, and |headformat| properties.
%
% \begin{NiceNote}
% Initial values for all row options can be set with
% |\kvtSet{Row/|\meta{option}|=|\meta{value}|}| (see also
% \cref{sec:kvtSet}).
% \end{NiceNote}
%
% The following example demonstrates some of the options.
% \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={hidden,above,bg,format}]
% \begin{KeyValTable}{Recipe}
% \Row{amount=150g, ingredient=ice cream,
% step=put into bowl}
% \Row{amount= 50g, ingredient=cherries,
% step=heat up and add to bowl}
% \Row[hidden]{amount=25g, ingredient=cream,
% step=decorate on top}
% \Row[above=1ex,bg=Gold,format=\textit]{
% step=serve with a smile}
% \end{KeyValTable}
% \end{LTXexample}
%
%
% \subsubsection{Vertical Row Size \& Spacing}\label{sec:VertSpacing}
%
% When rows are narrow or appear to be narrow, extra spacing above and
% below can be configured. There are (at least) three options for this.
%
% The first option is to use the following |\Row| options.
% \NiceDescribeKeys{3}
% {above}{vals=\vmeta{dimension}, init=\vmeta{empty}}
% {below}{vals=\vmeta{dimension}, init=\vmeta{empty}}
% {around}{vals=\vmeta{dimension}, init=\vmeta{empty}}
% These properties specify extra vertical space above and,
% respectively, below the row. The |around| property is a short-hand
% for setting both, |above| and |below|, to the same value.
% Note that the vertical space is currently not colored with the
% row's background color but with the page's background color.
% The argument, if provided, is directly passed to |\vspace|.
%
% The second option is to use the row |format| or a column's |format|
% property to insert |\strut| macros around cell content.
% For the |format|, the following macro exists.
%
% \NiceDescribeMacro{\kvtStrutted}{\oarg{inner}\marg{arg}}
% This macro places a |\strut| before \meta{arg} and a |\strut| after
% \meta{arg}. This has the effect that the first and last row of
% \meta{arg} obtain a "natural" height and depth even if their content
% is smaller.
% The second |\strut| is omitted when it would cause a new line to be
% produced.
% See \cref{sec:row-numbering} for an example.
%
% The third option is using the \pkgname{cellspace} package and its
% column alignments (e.g., |Sl| instead of |l|) along with the configurable dimensions |\cellspacetoplimit| and |\cellspacebottomlimit|.
% The following example shows the second and the third option.
%
% \begin{LTXexample}[morekeywords={cellspace,kvtStrutted,cellspacetoplimit}]
% \usepackage{cellspace}
% \setlength{\cellspacetoplimit}{3pt}
% \NewKeyValTable{VertSpacing}{
% normal;
% struts: format=\kvtStrutted;
% cellspace: align=Sl;
% }
% \begin{KeyValTable}{VertSpacing}
% \Row{normal=normal size}
% \Row{normal=\large Large}
% \Row{struts=\large Large}
% \Row{cellspace=\large Large}
% \end{KeyValTable}
% \end{LTXexample}
%
%
% \subsubsection{Row Styles}
%
% Rather than specifying properties for individual rows, \thispackage
% also supports named \emph{row styles}.
%
% \NiceDescribeKey{style}{vals=\vmeta{list of style names}, init=\vmeta{empty}}
% Through this property of rows, a list of styles can be applied to the
% row. Each style must have been defined with |\kvtNewRowStyle| before.
%
% \NiceDescribeMacro{\kvtNewRowStyle}{\marg{name}\marg{row-options}}
% This macro declares a new row style with the given \meta{name} and
% defines it to be equivalent to using the given \meta{row-options}.
% The \meta{name} must not already be defined.
%
% \NiceDescribeMacro{\kvtRenewRowStyle}{\marg{name}\marg{row-options}}
% This macro re-defines an existing row style \meta{name} with new
% \meta{row-options}.
%
% The following example produces the same output as the previous
% example, but uses row styles.
%
% \begin{LTXexample}[morepreset=\RecipePreset,morekeywords={style,kvtNewRowStyle}]
% \kvtNewRowStyle{optional}{hidden}
% \kvtNewRowStyle{highlight}{above=1ex,bg=Gold}
% \begin{KeyValTable}{Recipe}
% \Row{amount=150g, ingredient=ice cream,
% step=put into bowl}
% \Row{amount= 50g, ingredient=cherries,
% step=heat up and add to bowl}
% \Row[style=optional]{amount=25g,
% ingredient=cream, step=decorate on top}
% \Row[style=highlight]{step=serve with a smile}
% \end{KeyValTable}
% \end{LTXexample}