Debian Codegraph @

texmf-dist/source/latex/arraycols/arraycols.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2019-2024 by Antoine Missier <[email protected]>
4 %
5 % This file may be distributed and/or modified under the conditions of
6 % the LaTeX Project Public License, either version 1.3 of this license
7 % or (at your option) any later version. The latest version of this
8 % license is in:
9 %
10 % http://www.latex-project.org/lppl.txt
11 %
12 % and version 1.3 or later is part of all distributions of LaTeX version
13 % 2005/12/01 or later.
14 % \fi
15 %
16 % \iffalse
17 %<*driver>
18 \ProvidesFile{arraycols.dtx}
19 %</driver>
20 %<*package>
21 \NeedsTeXFormat{LaTeX2e}[2005/12/01]
22 \ProvidesPackage{arraycols}
23 [2024/05/04 v1.5 .dtx New column types for array and tabular]
24 %</package>
25 %<*driver>
26 \documentclass{ltxdoc}
27 \usepackage[utf8]{inputenc}
28 \usepackage[T1]{fontenc}
29 \usepackage[french,english]{babel}
30 \usepackage[charter]{mathdesign}
31 \usepackage{arraycols}
32 \usepackage{spacingtricks}
33 \usepackage{sectsty}
34 \usepackage{xcolor}
35 \definecolor{darkbrown}{rgb}{0.5,0.1,0.1}
36 \allsectionsfont{\color{darkbrown}}
37
38 \DisableCrossrefs
39 %\CodelineIndex
40 %\RecordChanges
41 \usepackage{hyperref}
42 \hypersetup{%
43 colorlinks,
44 linkcolor=blue,
45 citecolor=blue,
46 pdftitle={arraycols},
47 pdfsubject={LaTeX package},
48 pdfauthor={Antoine Missier}
49 }
50 \MakeShortVerb{"}
51 \begin{document}
52 \DocInput{arraycols.dtx}
53 %\PrintChanges
54 %\PrintIndex
55 \end{document}
56 %</driver>
57 % \fi
58 %
59 % \CheckSum{42}
60 %
61 % \CharacterTable
62 % {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
63 % 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
64 % Digits \0\1\2\3\4\5\6\7\8\9
65 % Exclamation \! Double quote \" Hash (number) \#
66 % Dollar \$ Percent \% Ampersand \&
67 % Acute accent \' Left paren \( Right paren \)
68 % Asterisk \* Plus \+ Comma \,
69 % Minus \- Point \. Solidus \/
70 % Colon \: Semicolon \; Less than \<
71 % Equals \= Greater than \> Question mark \?
72 % Commercial at \@ Left bracket \[ Backslash \\
73 % Right bracket \] Circumflex \^ Underscore \_
74 % Grave accent \` Left brace \{ Vertical bar \|
75 % Right brace \} Tilde \~}
76 %
77 % \changes{v0.1}{27/12/2011}{First personal version}
78 % \changes{v1.0}{2019/05/04}{Initial version, creating dtx and ins files}
79 % \changes{v1.0}{2019/06/17}{English translation by François Bastouil}
80 % \changes{v1.1}{2020/11/23}{Incompatibility with tablestyles mentioned,
81 % minor changes in documentation}
82 % \changes{v1.2}{2021/09/20}{Incompatibility with siunitx package
83 % (called by pstricks-add) is solved}
84 % \changes{v1.3}{2023/08/09}{A few changes in the documentation}
85 % \changes{v1.4}{2023/09/13}{More changes in the documentation}
86 % \changes{v1.5}{2024/05/04}{Mention of the tabularray and mdwtab packages in the doc;
87 % explanations about the gape and Gape macros from the makecell package}
88 %
89 % \GetFileInfo{arraycols.sty}
90 %
91 % \title{The \textsf{arraycols} package\thanks{This document
92 % corresponds to \textsf{arraycols}~\fileversion, dated \filedate.
93 % Thanks to François Bastouil for initial assistance with the English translation.}}
94 % \author{Antoine Missier \\ \texttt{[email protected]}}
95 % \date{May 4, 2024}
96 % \maketitle
97 %
98 % \section{Introduction}
99 %
100 % Although the remarkable \textsf{tabularray} package by Jianrui Lyu~\cite{TABUL},
101 % developed in \LaTeX 3, offers many new possibilities and great flexibility
102 % in composing tables, many users are still familiar with
103 % Frank Mittelbach and David Carlisle's \textsf{array} package~\cite{ARRAY}.
104 % In addition to \textsf{array}, this modest \textsf{arraycols} package introduces
105 % new predefined column types for tables and also includes a command
106 % for wide horizontal rule drawing.
107 % Below is a summary of the column types and macro defined by \textsf{arraycols},
108 % which will be detailed in the following section.
109 %
110 % \begin{center}\small \setlength{\extrarowheight}{1pt}
111 % \begin{tabular}{|cIm{7.9cm}|}
112 % \whline
113 % \multicolumn{2}{|c|}{\thead{Column definitions}} \\
114 % \Xhline{0.7pt}
115 % \texttt{L} & Left adjusted column (applicable in LR mode for \texttt{array} environments
116 % or math mode for \texttt{tabular} environment) \\
117 % \hline
118 % \texttt{C} & Centered-adjusted column (similar to L but centered) \\
119 % \hline
120 % \texttt{R} & Right-adjusted column (similar to L but right-adjusted) \\
121 % \hline
122 % \texttt{t}\marg{width} & Text column of fixed \meta{width} (LR mode), similar to \texttt{p},
123 % but with horizontal and vertical centering \\
124 % \hline
125 % \texttt{x} & Centered column in math mode with adjusted height to
126 % avoid touching the horizontal rules \\
127 % \hline
128 % \texttt{y} & Left-aligned column in math mode with adjusted height \\
129 % \hline
130 % \texttt{z}\marg{width} & Centered column in math mode, similar to \texttt{x},
131 % with adjusted height,
132 % but with fixed \meta{width} \\
133 % \hline
134 % \texttt{T} & Centered text column with adjusted width
135 % for \texttt{tabularx} environments (calculated like \texttt{X} column) \\
136 % \hline
137 % \texttt{Z} & Centered column for \texttt{tabularx}, similar to \texttt{T},
138 % but in math mode with adjusted height, like \texttt{x} and \texttt{z} \\
139 % \hline
140 % \texttt{I} & Thick vertical rule (1\,pt) \\
141 % \hline
142 % \texttt{V}\marg{thickness} & Vertical rule with variable \meta{thickness} \\
143 % \hline \hline
144 % \multicolumn{2}{|c|}{\thead{Horizontal rules}} \\
145 % \Xhline{0.7pt}
146 % |\whline| & Wide horizontal rule (1\,pt) \\
147 % \whline
148 % \end{tabular}
149 % \end{center}
150 %
151 % If a column type has been previously defined by another package,
152 % using \textsf{arraycols} will overwrite it and display a warning message.
153 %
154 % In addition to loading the \textsf{array} package, \textsf{arraycols}
155 % also requires \textsf{cellspace}~\cite{CELLSP},
156 % which is necessary for the \texttt{x}, \texttt{y}, \texttt{z} and \texttt{Z} column types.
157 % Moreover it relies on
158 % \textsf{tabularx}~\cite{TABX} for \texttt{T} and \texttt{Z} column types and
159 % loads \textsf{makecell}~\cite{MKCELL} for creation of multilined tabular cells.
160 % Note that the \textsf{tablestyles} package~\cite{TBLSTY}
161 % also defines the column types L, C, R and Z, but differently.
162 % However, \textsf{tablestyles} is incompatible with \textsf{makecell}
163 % and therefore also with \textsf{arraycols} as well.
164 %
165 % \section{Usage}
166 %
167 %\medskip
168 % \DescribeEnv{L} \DescribeEnv{C} \DescribeEnv{R}
169 % Referring to an example from the \textsf{array} package documentation,
170 % the |L|, |C| and |R| columns types, enable the
171 % reversal of the mathematical mode.
172 % This allows to achieve centered, left-aligned or right-aligned
173 % LR-mode in an \texttt{array} environment or an equivalent math-mode
174 % in a \texttt{tabular} environment.
175 % For instance, using the declaration "\begin{tabular}{|l|C|r|}" sets the second column
176 % in centered mathematical mode. Similarly, using the declaration "\begin{array}{|L|c|c|}"
177 % sets the first column in text mode, left-aligned
178 % \footnote{The declarations \texttt{L, C, R} do not work in a \texttt{tabularx} environment.
179 % Additionally, the \mbox{\textsf{tabulary}} package by David Carlisle~\cite{TABY}
180 % already defines the \texttt{L, C, R} (and \texttt{J}) column types for specific alignments
181 % in tables of the same type as \texttt{tabularx}.
182 % However, there is no incompatibility with \textsf{arraycols} because these
183 % column definitions apply exclusively within \texttt{tabulary} environments.}.
184 %
185 % \medskip
186 % \DescribeEnv{t\marg{width}}
187 % The newly introduced column type definition \texttt{t}\{\meta{width}\}
188 % horizontally and vertically centers paragraphs within the column,
189 % with a specified \meta{width}.
190 % In contrast, the traditional \texttt{p}\marg{width} (in standard \LaTeX)
191 % and \texttt{m}\marg{width} (from the \textsf{array} package) column types,
192 % justifies paragraphs, while text in \texttt{t}\{\meta{width}\} is centered.
193 %
194 % \medskip
195 % \DescribeEnv{x} \DescribeEnv{y}
196 % In order to guarantee adequate row heights, especially for displaymath mode
197 % formulas, the package includes the column types \texttt{x} (centered)
198 % and \texttt{y} (left aligned).
199 % These column types activate the mathematical mode and
200 % allow automatic adjustment of row heights to prevent any overlap with
201 % horizontal rules in cases where the content is too tall,
202 % thanks to a functionality of the \textsf{cellspace} package
203 % by Josselin Noirel~\cite{CELLSP}.
204 % While \textsf{cellspace} is initially designed for \texttt{tabular} environments,
205 % the new \texttt{x} and \texttt{y} column types
206 % are applicable in both \texttt{tabular} and \texttt{array} environments.
207 % Examine the following examples created using
208 % "\begin{array}{|c|}" and "\begin{array}{|x|}".
209 % \[
210 % \begin{array}{|c|}
211 % \hline
212 % \text{bad}\\
213 % \hline
214 % \displaystyle\lim_{\substack{x \to 1\\x>1}} \ln\left(\dfrac{x^2}{x-1}\right) \\
215 % \hline
216 % \dfrac{a}{b} \\
217 % \hline
218 % \displaystyle\int_{1}^{X} \frac{1}{t}\,\mathrm{d} t \\
219 % \hline
220 % \end{array}
221 % \qquad
222 % \begin{array}{|x|}
223 % \hline
224 % \text{good}\\
225 % \hline
226 % \displaystyle\lim_{\substack{x \to 1\\x>1}} \ln\left(\dfrac{x^2}{x-1}\right) \\
227 % \hline
228 % \dfrac{a}{b} \\
229 % \hline
230 % \displaystyle\int_{1}^{X} \frac{1}{t}\,\mathrm{d} t \\
231 % \hline
232 % \end{array}
233 % \]
234 %
235 % The \textsf{cellspace} package is loaded with the \texttt{math} option
236 % \footnote{The \texttt{math} option loads the \textsf{amsmath} package.
237 % As mentionned in the \textsf{cellspace} package documentation:
238 % \og the \textsf{amsmath} package can be loaded beforehand with other
239 % packages (such as \texttt{empheq} or \texttt{mathtools}),
240 % were an incompatibility to arise from one’s loading it later\fg.}
241 % to efficiently manage row heights, including in matrices.
242 % Another option of \textsf{cellspace}, \texttt{column=Q}
243 % (with \texttt{S} being the default in \textsf{cellspace})
244 % \footnote{The letter Q is a substitute for the default column modifier
245 % S of the \textsf{cellspace} package.},
246 % was necessary to prevent any compatibility issues
247 % with the \textsf{siunitx} package (also loaded by \textsf{pstricks-add}).
248 % The \texttt{Q} declaration serves as a \og modifier \fg{}
249 % that, when placed before a column type declaration,
250 % permits the adjustment of cell height,
251 % for instance ``\texttt{Qc}'' for a vertical adjustment
252 % within a centered column type.
253 %
254 % \medskip
255 % Notice that another package, \textsf{booktabs}~\cite{BOOK}, also offers
256 % excellent row height adjustment. However, regrettably, it doesn't handle the height
257 % of vertical separators ``"|"''.
258 % In order to achieve a similar vertical adjustment as \textsf{booktabs},
259 % we set the \textsf{cellspace} parameters as follows:
260 % \begin{center}
261 % \begin{tabular}{l}
262 % "\setlength{\cellspacetoplimit}{3pt}", \\
263 % "\setlength{\cellspacebottomlimit}{2pt}".
264 % \end{tabular}
265 % \end{center}
266 %
267 % \medskip
268 % A common issue with \LaTeX\ tables is that there isn’t enough space
269 % around horizontal rules. As seen previously,
270 % \textsf{cellspace} partially addresses this issue,
271 % but if you want to add some more space around the horizontal rules, it's not straightforward.
272 % First, note that Donald Arsenau's \textsf{tabls} package~\cite{TABLS} produces
273 % a nice and automatic solution in this regard, but is not compatible with \textsf{array}
274 % nor with \textsf{numprint}.
275 %
276 % Several other methods can be employed:
277 % you can increase the space on top or bottom of a particular cell
278 % by using
279 % \begin{center}
280 % "\gape"\oarg{\texttt{t} or \texttt{b}}\marg{text}
281 % or "\Gape"\oarg{height}\oarg{depth}\marg{text}
282 % \end{center}
283 % from the \textsf{makecell} package~\cite{MKCELL}.
284 % You have also the "\bigstrut" command from the \textsf{bigstrut} package~\cite{STRUT},
285 % but it's less efficient and convenient.
286 % An efficient method is provided by the \textsf{mdwtab} package
287 % of Mark Wooding~\cite{MDWTAB} with its macros
288 % "\vgap"\marg{length} or "\hlx"\marg{hlx-cmd},
289 % where in \marg{hlx-cmd} you can place "h", representing "\hline", and "s"\oarg{length},
290 % meaning "\vgap" (among others).
291 % This package provides also many other interesting features.
292 % Finally, manual adjustments of particular rows can be achieved using
293 % the "\vstrut"\oarg{depth}\marg{height} command
294 % from the \textsf{spacingtricks} package~\cite{SPA},
295 % These packages are not loaded by \textsf{arraycols}, except \textsf{makecell}.
296 % Have a look at their documentation.
297 %
298 % \medskip
299 % \DescribeEnv{z\marg{width}}
300 % The \texttt{z}\marg{width} column type activates the mathematical mode
301 % and allows to define the column width,
302 % similar to \texttt{t}\marg{width}.
303 % It also adjusts the row height, akin to the \texttt{x} column type.
304 % The content consist of a single line. When it becomes too wide, it may protrude to the right.
305 %
306 % \medskip
307 % \DescribeEnv{T} \DescribeEnv{Z}
308 % The \textsf{tabularx} package by David Carlisle~\cite{TABX} introduces
309 % the \texttt{X} column definition, which calculates its width in relation to
310 % the required width for the entire table. It aligns text to the left
311 % similar to \texttt{p}\marg{width}.
312 % Using "\begin{tabularx}{8cm}{|c|X|X|}"
313 % adjusts the width of the \texttt{X} columns
314 % to achieve a total width of 8\,cm. To complement this, we offer
315 % the \texttt{T} declaration, which performs a similar function
316 % but centers the content horizontally.
317 % Additionally the \texttt{Z} declaration activates mathematical
318 % mode and adjusts
319 % line heights, comparable to \texttt{x} or \texttt{z}).
320 % The following example is obtained with
321 % \begin{center}
322 % "\begin{tabularx}{\linewidth}{|T|y|x|Z|T|}".
323 %
324 % \medskip
325 % \begin{tabularx}{\linewidth}{|T|y|x|Z|T|}
326 % \hline
327 % A good job &
328 % \displaystyle\lim_{\substack{x \to 1\\x>1}} \ln\left(\dfrac{x^2}{x-1}\right) &
329 % \dfrac{a}{b} &
330 % \dfrac{a}{b} + \displaystyle \int_{1}^{X} \frac{1}{t}\,\mathrm{d}t &
331 % \makecell{a multi-line \\ piece of text}\\
332 % \hline
333 % \end{tabularx}
334 % \end{center}
335 %
336 % Observe that cells 3 and 4 are not vertically centered to preserve
337 % the precise alignment of fraction bars within mathematical formulas
338 % across cells.
339 % For achieving accurate vertical positioning
340 % within the last cell, we have used the powerful "\makecell"\oarg{pos}\marg{content}
341 % command from
342 % the \textsf{makecell} package by Olga Lapko~\cite{MKCELL}:
343 % "\makecell{a multi-line \\ piece of text}".
344 %
345 % \bigskip
346 % \DescribeEnv{I} \DescribeEnv{V\marg{thickness}}
347 % The column definition \texttt{I} is mentioned in The \LaTeX\ Companion~\cite{COMP}
348 % and allows for drawing a thicker \emph{vertical} line (1\,pt thick)
349 % compared to the one achieved
350 % with the standard declaration ``"|"''. For selecting the line thickness,
351 % we additionally provide the column
352 % definition \texttt{V}\marg{thickness}
353 % \footnote{The definition of \texttt{V}
354 % would have been simplified by utilizing an optional argument for \texttt{I},
355 % but unfortunately, this approach doesn't function.}.
356 %
357 % \medskip
358 % \DescribeMacro{\whline}
359 % Similarly, the "\whline" command, suggested in The \LaTeX\ Companion, enables the drawing of
360 % a thicker \emph{horizontal} line (1\,pt thick) compared to the line obtained with "\hline".
361 % Moreover, the \textsf{makecell} package provides the command "\Xhline"\marg{thickness}
362 % enabling the choice of horizontal rule thickness.
363 %
364 % \medskip
365 % The introductory table has been typeset with a column declaration \texttt{I}
366 % serving as a separator between the two text columns.
367 % Horizontal rules at the beginning and end of the table are accomplished using "\whline",
368 % while a "\Xhline{0.8pt}" rule is employed after the legend rows.
369 % The formatting of header rows is achieved using the "\thead" command
370 % from the \textsf{makecell} package.
371 % Lastly, following a recommendation of the \textsf{array} package~\cite{ARRAY},
372 % an additional 1\,pt has been added to the standard height of each row within this table.
373 % This adjustment is implemented with the command
374 % "\setlength{\extrarowheight}{1pt}"
375 % \footnote{As stated in the \textsf{array} package documentation:
376 % \og This is important for tables with horizontal lines because those
377 % lines normally touch the capital letters\fg.}.
378 %
379 % \StopEventually{}
380 %
381 % \section{Implementation}
382 % \begin{macrocode}
383 \RequirePackage{array}
384 \RequirePackage[math,column=Q]{cellspace}
385 \RequirePackage{tabularx} % must be loaded after cellspace
386 \RequirePackage{makecell}
387
388 \newcolumntype{C}{>{$}c<{$}}
389 \newcolumntype{L}{>{$}l<{$}}
390 \newcolumntype{R}{>{$}r<{$}}
391 \newcolumntype{t}[1]{>{\centering\arraybackslash}m{#1}}
392 % \end{macrocode}
393 % The \textsf{cellspace} package provides the \texttt{S} modifier
394 % (we used \texttt{Q} instead), which,
395 % when placed before a column declaration, allows for the adjustment of cell content height
396 % to prevent any overlap with horizontal rules. The spacing between the content and the
397 % horizontal rules is governed by the parameters
398 % "\cellspacetoplimit" and "\cellspacebottomlimit".
399 %
400 % \begin{macrocode}
401 \newcolumntype{x}{>{$}Qc<{$}}
402 \newcolumntype{y}{>{$}Ql<{$}}
403 \setlength{\cellspacetoplimit}{3pt}
404 \setlength{\cellspacebottomlimit}{2pt}
405 \newcolumntype{z}[1]{>{$}Q{>{\centering\arraybackslash}p{#1}}<{$}}
406 % \end{macrocode}
407 % For the \texttt{z} column type, we employed the \texttt{p} declaration
408 % instead of \texttt{m} (which should automatically center content).
409 % This choice ensures proper alignment of mathematical
410 % expressions within cells of the same row.
411 % The same result can be achieved with the following definition:
412 % "\newcolumntype{z}[1]{>{$}Q{W{c}{#1}}<{$}}" with "W{c}" defined
413 % in the \textsf{array} package.
414 %
415 % \medskip
416 % \begin{macrocode}
417 \newcolumntype{T}{>{\centering\arraybackslash}X}
418 \newcolumntype{Z}{>{$}QT<{$}}
419 % \end{macrocode}
420 % Like \texttt{X}, the \texttt{T} columns are not vertically centered.
421 % Although it's possible to achieve this
422 % by using the command "\renewcommand{\tabularxcolumn}[1]{m{#1}}"
423 % (with \texttt{m} instead of default value \texttt{p}),
424 % unfortunately, this approach has a global effect on all column declarations based
425 % on \texttt{X}, including \texttt{T} and \texttt{Z}. As a result, it could disrupt the
426 % alignment of mathematical expressions within cells of the same row.
427 %
428 % \medskip
429 % \begin{macrocode}
430 \newcolumntype{I}{!{\vrule width 1pt}}
431 \newcolumntype{V}[1]{!{\vrule width #1}}
432 \newlength\savedwidth
433 \newcommand{\whline}{%
434 \noalign{\global\savedwidth\arrayrulewidth
435 \global\arrayrulewidth 1pt}
436 \hline
437 \noalign{\global\arrayrulewidth\savedwidth}
438 }
439 % \end{macrocode}
440 %
441 % \bigskip
442 % \begin{thebibliography}{13}
443 % \bibitem{TABUL} \emph{Tabularray -- Typeset Tabulars and Arrays with \LaTeX 3},
444 % Jianrui Lyu, CTAN, 2024A 2024/02/16.
445 % \bibitem{ARRAY} \emph{A new implementation of LATEX’s \textsf{tabular} and \textsf{array}
446 % environment}, Frank Mittelbach, David Carlisle, CTAN, v2.4k revised 2018/12/30.
447 % \bibitem{CELLSP} \emph{The \textsf{cellspace} package}, Josselin Noirel, CTAN,
448 % v1.8.1 2019/03/11.
449 % \bibitem{TABX} \emph{The \textsf{tabularx} package}, David Carlisle, CTAN, v2.11.b 2016/02/03.
450 % \bibitem{MKCELL} \emph{The \textsf{makecell} package}, Olga Lapko, CTAN, v0.1e 2009/08/03.
451 % \bibitem{TBLSTY} \emph{The \textsf{tablestyles} package}, Matthias Pospiech, CTAN,
452 % v0.1 2014/06/27.
453 % \bibitem{TABY} \emph{The \textsf{tabulary} package}, David Carlisle, CTAN, v1.10 2014/06/11.
454 % \bibitem{BOOK} \emph{Publication quality tables in \LaTeX}, package \textsf{booktabs} by
455 % Simon Fear, CTAN, v1.618033 2016/04/29.
456 % \bibitem{TABLS} \emph{The \textsf{tabls} package}, Donald Arseneau, CTAN, v3.5 2010/02/26.
457 % \bibitem{STRUT} \emph{The \textsf{multirow}, \textsf{bigstrut}
458 % and \textsf{bigdelim} packages},
459 % Piet van Oostrum, Øystein Bache, Jerry Leichter, CTAN, v2.4 2019/01/01.
460 % \bibitem{MDWTAB} \emph{The \textsf{mdwtab} package}, Mark Wooding, CTAN, v1.9 1998/04/28.
461 % \bibitem{SPA} \emph{The \textsf{spacingtricks} package}, Antoine Missier,
462 % CTAN, v1.8 2023/12/06.
463 % \bibitem{COMP} \emph{The \LaTeX\ Companion}. Frank Mittelbach, Michel Goossens,
464 % Johannes Braams, David Carlisle, Chris Rowley, 2nd edition, Pearson Education, 2004.
465 % \end{thebibliography}
466
467 % \Finale
468 \endinput