Debian Codegraph @

texmf-dist/doc/luatex/lutabulartools/lutabulartools.tex

raw
1 % Kale Ewasiuk ([email protected])
2 % 2025-01-06
3 % Copyright (C) 2021-2025 Kale Ewasiuk
4 %
5 % Permission is hereby granted, free of charge, to any person obtaining a copy
6 % of this software and associated documentation files (the "Software"), to deal
7 % in the Software without restriction, including without limitation the rights
8 % to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 % copies of the Software, and to permit persons to whom the Software is
10 % furnished to do so, subject to the following conditions:
11 %
12 % The above copyright notice and this permission notice shall be included in
13 % all copies or substantial portions of the Software.
14 %
15 % THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
16 % ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
17 % TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
18 % PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
19 % SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
20 % ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
21 % ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22 % OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
23 % OR OTHER DEALINGS IN THE SOFTWARE.
24
25
26 \documentclass[11pt,parskip=half]{scrartcl}
27
28
29 \setlength{\parindent}{0ex}
30
31 \newcommand{\llcmd}[1]{\leavevmode\llap{\texttt{\detokenize{#1}\ }}}
32 \def\cmd{\bgroup\catcode`\\=12 \catcode`\ =12 \cmdA}
33 \def\cmdA#1{\egroup{\texttt{\detokenize{#1}}}}
34
35 \usepackage{url}
36 \usepackage{showexpl}
37 \lstset{explpreset={justification=\raggedright,pos=r,wide=true}}
38 \setlength\ResultBoxRule{0mm}
39 \lstset{
40 language=[LaTeX]TeX,
41 basicstyle=\ttfamily\small,
42 commentstyle=\ttfamily\small\color{gray},
43 frame=none,
44 numbers=left,
45 numberstyle=\ttfamily\small\color{gray},
46 prebreak=\raisebox{0ex}[0ex][0ex]{\color{gray}\ensuremath{\hookleftarrow}},
47 extendedchars=true,
48 breaklines=true,
49 tabsize=4,
50 }
51 \addtokomafont{title}{\raggedright}
52 \addtokomafont{author}{\raggedright}
53 \addtokomafont{date}{\raggedright}
54 \author{Kale Ewasiuk (\url{[email protected]})}
55 \usepackage[yyyymmdd]{datetime}\renewcommand{\dateseparator}{--}
56 \date{\,\,\today}
57
58
59
60
61
62 \newcommand{\tMC}{\cmd{\\MC}}
63
64
65 \usepackage{caption}
66
67 \usepackage{ltxtable}
68 \usepackage{longtable}
69
70 \usepackage{penlightplus}
71
72
73 \RequirePackage{lutabulartools}
74 \title{lutabulartools}
75 \subtitle{some useful LuaLaTeX-based tabular tools}
76
77 \usepackage{tabularx}
78 \usepackage{siunitx}
79
80 \lttdebugON
81
82 \usepackage{hyperref}
83
84
85 \begin{document}
86
87 \maketitle
88
89 \cmd{lutabulartools} is a package that contains a few useful Lua\LaTeX-based macros to help with tables.
90 A global \cmd{lua} variable \cmd{lutabt} is created.
91 This package redefines the {\ttfamily tabular} and {\ttfamily tabular*} environments as well as \cmd{\@arraycr} to add functionarlity.
92 The following packages are loaded by this one,
93 so if you have specific settings for these packages, load the \cmd{lutabulartools} package after:
94 \texttt{
95 {booktabs},
96 {multirow},
97 {makecell},
98 {xparse},
99 {array},
100 {xcolor},
101 {colortbl},
102 {luacode},
103 {penlightplus}}.
104
105 \section{\texttt{\textbackslash settabular}}
106
107 A key-val interface in the \cmd{\settabular{}} command is used to set some tabular settings.
108 \cmd{nopad} automatically adds \cmd{@{}} on each end of the column spec.\\
109 \cmd{tbrule} automatically adds \cmd{\toprule} as the first thing in the \cmd{tabular(*|x)} environment, and \cmd{\bottomrule} as the last.
110 Note that this automatic top/bottom rule adding is disabled in \cmd{longtable}.
111 \cmd{row/colsep} tweaks the row spacing with \cmd{arraystretch}
112 or adjusts the \cmd{tabcolsep} length (an integer must be used, the result is multiplied by 6pt). For example:
113 \begin{verbatim}
114 \settabular{nopad,tbrule,rowsep=2,colsep=2} % or
115 \settabular{nopad=false,tbrule=false} % to set the switches to off
116 \end{verbatim}
117
118 \settabular{nopad}
119 \settabular{!nopad}
120
121
122 \section{Debugging}
123 You can toggle log output debugging with \cmd{\lttdebugON} and \cmd{\lttdebugOFF}.
124 The messages will be printed in a format like so:
125 \begin{verbatim}
126 vvvvv msg1 (lutabulartools)
127 msg2
128 ^^^^^
129 \end{verbatim}
130
131 \cmd{\lttdebugprt} can be used pretty-print the \cmd{lutabt} module and its attributes---useful for checking the
132 ``state'' of the package.
133
134 \section{\texttt{\textbackslash MC} -- Magic Cell}
135 \texttt{\textbackslash MC} (magic cell) combines the facilities of
136 \cmd{\multirow} and \cmd{\multicolumn} from the \texttt{multirow} package, and \cmd{\makcell} from the titular package.
137 With the help of LuaLaTeX, it takes an easy-to-use cell specification and employs said commands as required.
138 \cmd{\MC} will not work properly if your table is only 1 column wide (you probably don't need \cmd{MC} in that case anyway...).
139 Here is the usage:
140
141 \texttt{\textbackslash MC * [cell spec] [override multicol] <cell format> \{contents\} }
142
143 \llcmd{*}This will wrap the entire command in \{\}. This is necessary for \texttt{siunitx} single-column width columns.
144 However, the \cmd{\MC} command attempts to detect this automatically.
145
146 \llcmd{[cell spec]}%
147 Any letters placed in this argument are used for cell alignment.
148 You can use one of three: \cmd{t}, \cmd{m}, \cmd{b} for top, middle, bottom (vertical alignment),
149 and/or \cmd{l}, \cmd{c}, \cmd{r} for horizontal alignment, in no particular order.
150 By default, \cmd{\MC} will try to autodetect the horizontal alignment based on the current column.
151 If it can't, it will be left-aligned.
152 The default vertical alginment is top. More on this in section \ref{s.def}.
153
154 This argument can also contain two integers, separated by a comma (if two are used).
155 \cmd{C,R}, \cmd{C}, or \cmd{,R} are a valid inputs,
156 where \cmd{R}=rows (int), and \cmd{C}=columns, (int).
157 If you want a 1 column wide, multirow cell,
158 you can pass \cmd{,R}. These numbers can be negative (positive numbers occupy columns to the right
159 and rows below, and negative numbers occupy columns to the left and rows above).
160 If no spec is passed, (argument empty), \cmd{\MC}
161 acts like a \texttt{makecell}.
162 Additionally, you can pass \cmd{+} in place of C (number of columns wide),
163 and it will make the cell width fill until the end of the current row.
164
165 Examples:\\
166 \cmd{\MC[2,2]} means two columns wide, two rows tall.\\
167 \cmd{\MC[2,1]} or \cmd{\MC[2]} means two columns wide, one row tall.\\
168 \cmd{\MC[1,2]} or \cmd{\MC[,2]} means one column wide, two rows tall.\\
169 \cmd{\MC[+,2]}, if placed in the first column, occupies the entire row and is two rows tall.\\
170 \cmd{\MC[+,2]}, if placed in the second column, occupies the second column to the end of the table and is two rows tall.\\
171 In any of these examples, you can place the alignment letters anywhere.
172 So, \cmd{\MC[l1,2b]} and \cmd{\MC[1,2 lb]} are both left-bottom aligned (spaces are ignored).\\
173 Put an \cmd{_} as the last thing to add a \cmd{cmidrule} under, followed by a trim spec (the thing that goes in \cmd{cmidrule()})
174 \cmd{\MC[+c_l]} will add a \cmd{cmidrule} underneath the cell (which fills until the end of the table), with the left side trimmed.
175
176 \llcmd{[override mc]}%
177 You may want to adjust the column specification of a multicolumn cell,\\
178 \texttt{[@\{\}c@\{\}]} for example to remove padding between the cell.
179
180 \llcmd{<cell format>}%
181 You can place formatting like \cmd{\bfseries} here.
182
183
184 \subsection{\texttt{\textbackslash MC} Defaults}\label{s.def}
185 The \cmd{tabular[*]} environment is re-defined to use Lua pattern matching
186 to parse the column specification of the table. This is done to determine how many columns there are,
187 and what the current column type is, even if specifications like \cmd{r@{.}l*{3}{r}} are used.
188 If you have defined a column that expands many, you should register it with
189 \cmd{\setMCrepl{?}{??}} where \cmd{?} is your column and \cmd{??} is what it expands to.
190 You can also specify default horizontal and vertical alignments (ie if alignment not passed to \cmd{\MC})
191 for an arbitrary column by \cmd{\setMChordef{?}{l|r|c}} and\\
192 \cmd{\setMChordef{?}{t|m|b}}, where \cmd{?} is the column.
193 To add a column that should be surrounded by brackets for \cmd{siunitx} purposes, do so with \cmd{\addMCsicol{?}}.
194 \cmd{S} is included by default.
195
196
197 \section{\texttt{\textbackslash midrulesat}}
198 If you'd rather specify the location of midrules outside the table, use \cmd{\midrulesat{1,2,3}}: a midrule will be
199 placed on rows 1, 2, and 3, for the next table only.
200
201
202 \section{Examples}
203
204 \let\nl\\
205
206 Change the settings for the rest of the doc.
207
208 \begin{LTXexample}
209 \settabular{nopad,tbrule}
210 \end{LTXexample}
211
212 \settabular{nopad,tbrule}
213
214
215 \subsubsection{A good use for headers}
216
217 \begin{LTXexample}
218 \begin{tabular}{ l l l }
219 \MC[+m]<\itshape>{A Decent
220 Example}\\\midrule
221 & \MC[2m_]{Heading} \\
222 \MC[b,-2]{Multi\\Line} & A & B \\\midrule
223 end & & \\
224 \end{tabular}
225 \end{LTXexample}
226
227 \subsubsection{A small example}
228 \begin{LTXexample}
229 \midrulesat{1,2,3}
230 \begin{tabular}{ l l l }
231 a \\
232 b \\
233 c \\
234 d \\
235 \end{tabular}
236 \end{LTXexample}
237
238
239 \subsubsection{A small example}
240
241 \begin{LTXexample}
242 \begin{tabular}{ l l l }\midrule
243 \MC[_]{A} & \MC[mc2,2]{Lttrs} \\
244 \MC[_r]{B} & \\ \cmidrule{2-3}
245 \MC[_r]{1} & \MC[_r]{A} & \MC[_r]{B} \\
246 \\
247 \end{tabular}
248 \end{LTXexample}
249
250
251 \subsubsection{A small bad example}
252 Notice that the top-aligned p-column
253 doesn't play particularly well with the middle aligned \cmd{\MC}
254 \begin{LTXexample}
255 \begin{tabular}{ p{1cm} l }
256 hello\newline world
257 & \MC[mr]{11\\2} \\
258 \end{tabular}
259 \end{LTXexample}
260
261
262 \subsubsection{If you insist on vertical lines}
263 \begin{LTXexample}
264 \begin{tabular}{|c|c|c|} \hline
265 1 & 2 & 3\\\hline
266 4 & \MC[2,2cm][@{}c@{}|]%
267 <\ttfamily>{5}\\\cline{1-1}
268 & \MC[2][r|]{} \\\hline%hacky fix
269 6 & 7 & 8\\\hline
270 \end{tabular}
271 \end{LTXexample}
272
273
274 \subsubsection{A perhaps useful example}
275
276 \begin{LTXexample}
277 \begin{tabularx}{\linewidth}{S[table-format=2.1,table-alignment=left]X}
278 % err & ... \\% ERROR, not wrap
279 \MC{Error,\%} & Comment \\% MC helps
280 3.1 & \MC[,2]{multi-line\\comment}\\
281 10.1& \\
282 \MC[2c]{... ...} \\
283 \end{tabularx}
284 \end{LTXexample}
285
286 \subsubsection{A messy example}
287
288 \begin{LTXexample}
289 \begin{tabular}{| c | c | c | c | c | c |}\toprule
290 \MC[2,2cm]<\ttfamily>{2,2cm} & \MC[2r]<\ttfamily>{2r} & 5 & \MC[,2b]<\ttfamily>{,2b}\\
291 & & 3 & 4 & 5 & \\\midrule
292 1 & 2 & \MC[2l][@{}l]<\ttfamily>{2l (\@\{\}l)} & 5 & 6666\\\cmidrule{3-4}
293 1 & \MC[+r]<\ttfamily>{+r} \\
294 \\
295 1 & 2 & 3 & 4 & 5 & \MC[,-2]<\ttfamily>{,\\-2}\\
296 \end{tabular}
297 \end{LTXexample}
298
299
300
301 \newpage
302
303
304 \section{Some additional rules}
305 This package also redefines the \texttt{booktabs} midrules.\\
306 \llcmd{\gmidrule}is a full gray midrule.\\
307 By taking advantage of knowing how many columns there are (if you chose to redefine \texttt{tabular}),
308 you can specify individual column numbers (for a one column wide rule),
309 or reference with respect to the last column (blank, \texttt{+1}, \texttt{+0}, or \texttt{+} means last column,
310 \texttt{+2} means second last column, for example)
311 or omit the last number.\\
312 \llcmd{\cmidrule}is a single partial rule, with the above features\\
313 \llcmd{\gcmidrule}is a single partial gray rule, with the above features\\
314 You can add multiple \cmd{cmidrule}'s with the \texttt{(g)cmidrules} command. Separate with a comma.
315 You can apply global trimming of the rules with the \cmd{()} optional argument, and then
316 override it for a specific rule by placing \cmd{r} or \cmd{l} with the span specification.\\
317 \llcmd{\gcmidrules}Can produce multiple, light gray partial rules\\
318 \llcmd{\cmidrules}Can produce multiple black partial rules.\\
319 Here's an example:
320
321 \begin{LTXexample}
322 \begin{tabular}{c c c c c c}
323 a & 2 & 3 & 4 & 5 & 6\\
324 \cmidrule{+1} % rule on last column
325 b & 2 & 3 & 4 & 5 & 6\\
326 \cmidrules{1,3-+3,+} % rule on first col, third to third last col, and last col
327 c & 2 & 3 & 4 & 5 & 6\\
328 \cmidrules{1,3-+3rl,+} % same as above, but trim middle
329 d & 2 & 3 & 4 & 5 & 6\\
330 \cmidrules(l){1,r3-+3,+1}% trim left for all, but only trim right for middle rule
331 e & 2 & 3 & 4 & 5 & 6\\
332 \gcmidrule{+1} % rule on last column
333 f & 2 & 3 & 4 & 5 & 6\\
334 \gcmidrules{1,3-+3,+} % rule on first col, third to third last col, and last col
335 g & 2 & 3 & 4 & 5 & 6\\
336 \gcmidrules{1,3-+3rl,+} % same as above, but trim middle
337 h & 2 & 3 & 4 & 5 & 6\\
338 \gcmidrules(l){1,r3-+3,+1}% trim left for all, but only trim right for middle rule
339 \end{tabular}
340 \end{LTXexample}
341
342
343 \section{\texttt{\textbackslash midruleX} - Midrule every X\textsuperscript{th} row}
344
345 With this command, you can place a rule
346 every X rows for the next table made (place command outside of table).
347 You can configure the step size and what kind of midrule you prefer with the following key-val syntax, with default values below:\\
348 \cmd{\midruleX{step=5,rule=midrule,cntr=0,head=0,long=false}}\\
349 \cmd{step} is the number of rows before applying the rule set by \cmd{rule}. \\
350
351 Concerning \cmd{longtable}s: If \cmd{long} is set to \cmd{true} (or the key is present),
352 \cmd{\midruleX} will also add a unique \cmd{\label{}} on each ro (to detect page changes), and if the row starts on a newpage,
353 resets the row counter.
354
355 Use optional parameter \cmd{\midruleX*[o|n|f]{}}
356 to control expansion of the key-val settings (\cmd{[n]} for not expanded is default).
357 Before you want counting to begin, or anywhere in the table, you could
358 apply \cmd{\resetmidruleX[cntr]} to an arbitrary value: \cmd{cntr} is normally incremented by 1 each row.
359 You may want to avoid header rows being counted, or rows being underlined near the end of a table, for example.
360 If you want to skip the first \cmd{x} rows with \cmd{\midruleX}, set \cmd{head=x} (which is equivalent to \cmd{cntr=-x}).
361 If you want to skip the auto-ruling at that ro \cmd{x} (say a gray one) and instead use a \cmd{midrule}, use \cmd{head*=x}.
362
363 Note: Use \cmd{\noalign{\resetmiduleX}} if you need place a rule on the same line the reset takes place (ie. in a cell before \cmd{\\}).
364
365
366 \subsection{\texttt{\textbackslash midruleX} examples}
367
368 \begin{LTXexample}
369 \midruleX{step=3,rule=gmidrule,head*=1}
370 \begin{tabular}{rclc}
371 % ^^^ inject midruleX
372 Num & . & . & . \\
373 1 & & & \\
374 2 & & & \\
375 3 & & & \\
376 4 & \MC[2,2]{Hi\\world} \\
377 5 & & & \\
378 6 & & & \\
379 7 & & & \\
380 8 & & & \\
381 9 & & & \\
382 10 & & & \\
383 11 & & & \\
384 \resetmidruleX % resest
385 % so no bottom gray rule
386 12 & & & \\
387 \end{tabular}
388 \end{LTXexample}
389
390 \pagebreak
391
392 Here's an example with long table. Notice the gray rules reliably appear 3 rows after each header.
393 \begin{verbatim}
394 \midruleX{long=true,step=3,rule="\gcmidrules{1r,2-}"}
395 \def\tblhead{\toprule No & Name & Place & other\\\midrule}
396 \def\tblcontinued{\MC[+l]{Continued...}\\}
397 \def\tblcontinues{\MC[+r]{...Continues}\\}
398 \begin{longtable}{rclc}
399 \tblhead\endfirsthead
400 \tblcontinued\tblhead\endhead % all the lines above this will be repeated on every page
401 \tblcontinues\endfoot
402 \bottomrule End.\endlastfoot
403 \resetmidruleX
404 1 & & & \\
405 2 & & & \\
406 3 & & & \\
407 4 & & & \\
408 5 & & & \\
409 6 & & & \\
410 7 & & & \\
411 8 & & & \\
412 9 & & & \\
413 10 & & & \\
414 11 & & & \\
415 12 & \MC[2,-2](){Hi\\world} \\
416 13 & & & \\
417 14 & & & \\
418 15 & & & \\\newpage
419 16 & \MC[2,2]{Hi\\world} \\
420 17 & & & \\
421 18 & & & \\\resetmidruleX
422 19 & & & \\
423 \end{longtable}
424 \end{verbatim}
425
426 \midruleX{long=true,rule="\gcmidrules{1r,2-}"}
427 \def\tblhead{\toprule No & Name & Place & other\\\\\midrule}
428 \def\tblcontinued{\MC[+l]{...\\Continued...}\\\noalign{\resetmidruleX} } % reset added to avoid line in header
429 \def\tblcontinues{\MC[+r]{...Continues}\\}
430 \begin{longtable}{rclc}
431 \tblhead\endfirsthead
432 \tblcontinued\tblhead\endhead % all the lines above this will be repeated on every page
433 \tblcontinues\endfoot
434 \bottomrule End.\endlastfoot
435 1 & & & \\
436 2 & \MC[_]{hi} & & \\
437 3 & & & \\
438 4 & & & \\
439 5 & & & \\
440 6 & & & \\
441 7 & & & \\
442 8 & & & \\
443 9 & & & \\
444 10 & & & \\
445 11 & & & \\
446 12 & \MC[2,-2_]{Hi\\world} \\
447 13 & & & \\
448 14 & & & \\
449 15 & & & \\\newpage
450 16 & \MC[2,-2_]{Hi\\world} \\
451 17 & & & \\
452 18 & & & \\\resetmidruleX
453 19 & & & \\
454 \end{longtable}
455
456
457 %Long table X example
458 %\LTXtable{\linewidth}{ltxexample}
459
460
461 \begin{tabular}{c}
462 \\
463 \\
464 \\
465 \\
466 \\
467 \\
468 \\
469 \end{tabular}
470
471 \end{document}