summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/arraycols/arraycols.dtx
blob: 43dc0fe7eaa89b0f837f4a67c35985dd6a466708 (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
% \iffalse meta-comment
%
% Copyright (C) 2019-2023 by Antoine Missier <antoine.missier@ac-toulouse.fr>
%
% This file may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, either version 1.3 of this license
% or (at your option) any later version.  The latest version of this
% license is in:
%
%   http://www.latex-project.org/lppl.txt
%
% and version 1.3 or later is part of all distributions of LaTeX version
% 2005/12/01 or later.
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{arraycols.dtx}
%</driver>
%<*package> 
\NeedsTeXFormat{LaTeX2e}[2005/12/01]
\ProvidesPackage{arraycols}
    [2023/08/09 v1.3 .dtx arraycols file]
%</package>
%<*driver>
\documentclass{ltxdoc}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[french,english]{babel}
\usepackage{lmodern}
\usepackage{arraycols}
\DisableCrossrefs
%\CodelineIndex
%\RecordChanges
\usepackage{hyperref}
\hypersetup{%
    colorlinks,
    linkcolor=blue,
    citecolor=blue,
    pdftitle={arraycols},
    pdfsubject={LaTeX package},
    pdfauthor={Antoine Missier}
}
\MakeShortVerb{"}
\begin{document}
\DocInput{arraycols.dtx}
%\PrintChanges
%\PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{46}
%
% \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}{27/12/2011}{First personal version}
% \changes{v1.0}{2019/05/04}{Initial version, creating dtx and ins files}
% \changes{v1.0}{2019/06/17}{English translation by François Bastouil}
% \changes{v1.1}{2020/11/23}{Incompatibility with tablestyles mentioned, 
% minor changes in documentation}
% \changes{v1.2}{2021/09/20}{Incompatibility with siunitx package (called by pstricks-add) is solved}
% \changes{v1.3}{2023/09/08}{Small changes in the documentation}
%
% \GetFileInfo{arraycols.sty}
%
% \title{The \textsf{arraycols} package\thanks{This document
% corresponds to \textsf{arraycols}~\fileversion, dated \filedate. 
% Thanks to François Bastouil for assistance with the English translation.}}
% \author{Antoine Missier \\ \texttt{antoine.missier@ac-toulouse.fr}}
% \date{August 9, 2023}
% \maketitle
%
% \section{Introduction}
%
% This package introduces new predefined column types for tables, alongside
% the \textsf{array} package by Frank Mittelbach and David Carlisle~\cite{ARRAY}. It also includes a command for wide horizontal rule drawing.
% Below is a summary of the column types and macro defined by \textsf{arraycols},
% with further to follow.
% 
% \begin{center}\small \setlength{\extrarowheight}{1pt}
% \begin{tabular}{|cIm{7.9cm}|}
% \whline
% \multicolumn{2}{|c|}{\thead{Column definitions}} \\
% \Xhline{0.7pt}
% \texttt{L} & Left adjusted column (applicable in LR mode for \texttt{array} environments 
% or math mode for \texttt{tabular} environment) \\
% \hline
% \texttt{C} & Centered-adjusted column (similar to L but centered) \\
% \hline
% \texttt{R} & Right-adjusted column (similar to L but right-adjusted) \\
% \hline
% \texttt{t}\marg{width} & Text column of fixed \meta{width} (LR mode), similar to \texttt{p},
%  but with horizontal and vertical centering  \\
% \hline
% \texttt{x} & Centered column in math mode with adjusted height to
% avoid touching the horizontal rules \\
% \hline
% \texttt{y} & Left-aligned column in math mode with adjusted height \\
% \hline
% \texttt{z}\marg{width} & Centered column in math mode, similar to \texttt{x}, with adjusted height, 
% but with fixed \meta{width}  \\
% \hline
% \texttt{T} & Centered text column with adjusted width 
% for \texttt{tabularx} environments (calculated like \texttt{X} column)  \\
% \hline
% \texttt{Z} &  Centered column for \texttt{tabularx}, similar to \texttt{T},
% but in math mode with adjusted height, like \texttt{x} and \texttt{z} \\
% \hline
% \texttt{I} & Thick vertical rule (1\,pt) \\
% \hline
% \texttt{V}\marg{thickness} & Vertical rule with variable \meta{thickness} \\
% \hline \hline
% \multicolumn{2}{|c|}{\thead{Horizontal rules}} \\
% \Xhline{0.7pt}
% |\whline| & Wide horizontal rule (1\,pt) \\
% \whline
% \end{tabular}
% \end{center}
%
% Note that if a column type has been previously defined,
% using \textsf{arraycols} will overwrite it and display a warning message.
%
% In addition to loading the \textsf{array} package, \textsf{arraycols} also requires the \textsf{cellspace} package~\cite{CELLSP},
% which is necessary for the \texttt{x}, \texttt{y}, \texttt{z} and \texttt{Z} column types. Moreover it relies on
% \textsf{tabularx}~\cite{TABX} for \texttt{T} and \texttt{Z} column types and 
% loads \textsf{makecell}~\cite{MKCELL} for creation of multilined tabular cells.
% It's worth mentioning that the \textsf{tablestyles} package~\cite{TBLSTY}
% also defines L, C, R and Z column types differently.
% Nevertheless, \textsf{tablestyles} is incompatible with \textsf{makecell}
% and consequently with \textsf{arraycols} as well.
%
% Despite its minimal code, this package does not aim to introduce new macros. 
% Its main purpose is to combine and configure features derived from other packages.
%
% \section{Usage}
%
%\medskip
% \DescribeEnv{L}  \DescribeEnv{C}  \DescribeEnv{R}
% Referring to an example from the \textsf{array} package documentation, 
% the |L|, |C| and |R| columns types, offered by \textsf{arraycols}, provide the convenience
% of reversing the mathematical mode.
% This allows to achieve centered, left-aligned or right-aligned 
% LR-mode in an \texttt{array} environment or an equivalent math-mode 
% in a \texttt{tabular} environment.
% For instance, using the declaration "\begin{tabular}{|l|C|r|}" sets the second column 
% in centered mathematical mode. Similarly, using the declaration "\begin{array}{|L|c|c|}" 
% sets the first column\footnote{The declarations 
% \texttt{L, C, R} do not work in a \texttt{tabularx} environment.
% Additionally, the \mbox{\textsf{tabulary}} package by David Carlisle~\cite{TABY}
% already defines the \texttt{L, C, R} and \texttt{J} column types for specific alignments 
% in tables of the same type as \texttt{tabularx}. 
% However there is no incompatibility with \textsf{arraycols} because these column definitions
% apply exclusively in \texttt{tabulary} environments.
% } in text mode, left-aligned.
% 
% \medskip
% \DescribeEnv{t\marg{width}}
% The newly introduced column type definition \texttt{t}\{\meta{width}\} (text in LR-mode)
% achieves both horizontal and vertical centering within the column. It is distinct from the traditional
% \texttt{p}\marg{width} (in standard \LaTeX) and \texttt{m}\marg{width}
% (from the \textsf{array} package) column types, which are equivalent to
% "\parbox[t]" or "\parbox".
%
% \medskip
% \DescribeEnv{x} \DescribeEnv{y}
% In order to guarantee adequate row heights, especially for displaymath mode
% formulas, the package includes the column types \texttt{x} (centered)
% and \texttt{y} (left aligned), based on the \textsf{cellspace} package 
% by Josselin Noirel~\cite{CELLSP}.
% These column types allow automatic adjustment of row heights to prevent any overlap with
% horizontal rules in cases where the content is too tall.
% While \textsf{cellspace} is initially designed for \texttt{tabular} environments,
% the new \texttt{x} and \texttt{y} column types, introduces by \mbox{\textsf{arraycols}}, 
% generate mathematically well-adjusted columns. 
% They are applicable in both \texttt{tabular} and \texttt{array} environments.
% Examine the following examples created using
% "\begin{array}{|c|}" and "\begin{array}{|x|}".
% \[
% \begin{array}{|c|}
% \hline
% \text{bad}\\
% \hline
% \displaystyle\lim_{\substack{x \to 1\\x>1}} \ln\left(\dfrac{x^2}{x-1}\right) \\
% \hline
% \dfrac{a}{b} \\
% \hline
% \displaystyle\int_{1}^{X} \frac{1}{t}\,\mathrm{d} t  \\
% \hline
% \end{array}
% \qquad 
% \begin{array}{|x|}
% \hline
% \text{good}\\
% \hline
% \displaystyle\lim_{\substack{x \to 1\\x>1}} \ln\left(\dfrac{x^2}{x-1}\right) \\
% \hline
% \dfrac{a}{b} \\
% \hline
% \displaystyle\int_{1}^{X} \frac{1}{t}\,\mathrm{d} t  \\
% \hline
% \end{array}
% \]
%
% The \textsf{cellspace} package is loaded with the \texttt{math} option\footnote{The 
% \texttt{math} option loads the \textsf{amsmath} package.
% As mentionned in the \textsf{cellspace} package documentation:
% \og the \textsf{amsmath} package can be loaded beforehand with other
% packages (such as \texttt{empheq} or \texttt{mathtools}), 
% were an incompatibility to arise from one’s loading it later\fg.}
% to effectively manage row heights in matrix tables.
% Another option of \textsf{cellspace}, \texttt{column=Q}
% (with \texttt{S} being the default in \textsf{cellspace})\footnote{The
% selection of the letter Q to substitute the default column modifier S of the \textsf{cellspace}
% package is here arbitrary.}, was necessary to prevent any compatibility issues
% with the	\textsf{siunitx} package (also loaded by \textsf{pstricks-add}). 
% The \texttt{Q} column type serves as a \og modifier \fg{}
% that, when combined with the traditional
% column types \texttt{l, c, r}, permits the adjustment of cell height.
% 
% \medskip
% Notice that another package, \textsf{booktabs}~\cite{BOOK}, also offers 
% excellent row height adjustment. However, regrettably, it doesn't handle the height 
% of vertical separators "|".
% In order to achieve a similar vertical adjustment as \textsf{booktabs}, 
% we configure the \textsf{cellspace} parameters as follows:\\
% "\setlength{\cellspacetoplimit}{3pt}", \\
% "\setlength{\cellspacebottomlimit}{2pt}".
%
% Additionally, it's worth mentioning the \textsf{tabls} package by Donald Arneseau~\cite{TABLS}
% that makes a good adjustment of row heights as well, but it is incompatible 
% with the \textsf{array} and \textsf{numprint} packages.
%
% \medskip
% Finally, manual adjustments can also be achieved using the "\vstrut" command 
% from the \textsf{spacingtricks} package~\cite{SPA}, or by utilizing "\gape" and "\Gape"
% from the \textsf{makecell} package~\cite{MKCELL}, 
% as well as employing "\bigstrut" from the \textsf{bigstrut} package~\cite{STRUT}.
%
% \medskip
% \DescribeEnv{z\marg{width}}
% The \texttt{z}\marg{width} column type allows you to define the column width, 
% just like \texttt{t}\marg{width}, 
% and it also activates math mode and adjusts the row height,
% similar to the \texttt{x} column type.
%
% \medskip
%  \DescribeEnv{T}  \DescribeEnv{Z}
% The \textsf{tabularx} package by David Carlisle~\cite{TABX} introduces
% the \texttt{X} column definition, which calculates its width based on 
% the required width for the entire table. It aligns text to the left
% akin to \texttt{p}\marg{width}.
% For instance, using "\begin{tabularx}{8cm}{|c|X|X|}" adjusts the width of the \texttt{X} columns 
% to achieve a total width of 8\,cm. To complement this, we offer 
% the \texttt{T} declaration, which performs a similar function but centers the content horizontally.
% Additionally the \texttt{Z} declaration goes further by activating mathematical mode and adjusting
% line heights, comparable to \texttt{x} or \texttt{z}). Here's an example with
% "\begin{tabularx}{\linewidth}{|T|y|x|Z|T|}".
% \begin{center}
% \begin{tabularx}{\linewidth}{|T|y|x|Z|T|}
% \hline
% A good job &
% \displaystyle\lim_{\substack{x \to 1\\x>1}} \ln\left(\dfrac{x^2}{x-1}\right) &
% \dfrac{a}{b} & 
% \dfrac{a}{b} + \displaystyle \int_{1}^{X} \frac{1}{t}\,\mathrm{d}t & 
% \makecell{a multi-line \\ piece of text}\\
% \hline
% \end{tabularx} 
% \end{center}
% In order to maintain precise alignment of fraction bars within mathematical formulas, 
% cells are deliberately not vertically centered. Nevertheless, for achieving accurate vertical positioning
% within the last cell, we have used the powerful "\makecell" command from
% the \textsf{makecell} package by Olga Lapko~\cite{MKCELL}:
% "\makecell{a multi-line \\ piece of text}".
%
% \bigskip
%  \DescribeEnv{I} \DescribeEnv{V\marg{thickness}}
% The column definition \texttt{I} is mentioned in The \LaTeX\ Companion~\cite{COMP} 
% and allows for drawing a thicker \emph{vertical} line (1\,pt thick) compared to the one achieved
% with the standard declaration "|". For selecting the line thickness, we additionally provide the column 
% definition \texttt{V}\marg{thickness}\footnote{The definition of \texttt{V}
% would have been simplified by utilizing an optional argument for \texttt{I}, but unfortunately, this approach doesn't function.}.
%
% \medskip
% \DescribeMacro{\whline}
% Similarly, the "\whline" command, suggested in The \LaTeX\ Companion, allows for drawing a 
% thicker \emph{horizontal} line (1\,pt thick) compared to the line obtained with "\hline".
% Moreover, the \textsf{makecell} package provides the command "\Xhline"\marg{thickness}
% enabling the choice of horizontal rule thickness.
%
% \medskip
% The introductory table has been typeset with a column declaration \texttt{I} 
% serving as a separator between the two text columns. 
% Horizontal rules at the beginning and end of the table are accomplished using "\whline",
% while a "\Xhline{0.8pt}" rule is employed after the legend rows.
% The formatting of header rows is achieved using the "\thead" command from the \textsf{makecell}
% package. By default, \textsf{arraycols} sets:
% "\renewcommand\theadfont{\footnotesize\sffamily}"
% (initially |\footnotesize| only, without "\sffamily").
% Lastly, following a recommendation of the \textsf{array} package~\cite{ARRAY},
% an additional 1\,pt has been added to the standard height of each row within this table. This adjustment is implemented with the command
% "\setlength{\extrarowheight}{1pt}"\footnote{As stated 
% in the \textsf{array} package documentation: 
% \og This is important for tables with horizontal lines because those 
% lines normally touch the capital letters\fg.}.
%
% \StopEventually{}
%
% \section{Implementation}
%    \begin{macrocode}
\RequirePackage{array}
\RequirePackage[math,column=Q]{cellspace}
\RequirePackage{tabularx} % must be loaded after cellspace
\RequirePackage{makecell}

\newcolumntype{C}{>{$}c<{$}}
\newcolumntype{L}{>{$}l<{$}}
\newcolumntype{R}{>{$}r<{$}}
\newcolumntype{t}[1]{>{\centering\arraybackslash}m{#1}}
%    \end{macrocode}
% The \textsf{cellspace} package offers the \texttt{S} modifier (we used \texttt{Q} instead), which, 
% when placed before a column declaration, allows for the adjustment of cell content height 
% to prevent any overlap with horizontal rules. The spacing between the content and the rules
% is governed by the parameters
% "\cellspacetoplimit" and "\cellspacebottomlimit".
% 
%    \begin{macrocode}
\newcolumntype{x}{>{$}Qc<{$}}
\newcolumntype{y}{>{$}Ql<{$}}
\setlength{\cellspacetoplimit}{3pt}
\setlength{\cellspacebottomlimit}{2pt}
\newcolumntype{z}[1]{>{$}Q{>{\centering\arraybackslash}p{#1}}<{$}}
%    \end{macrocode}
% When defining the \texttt{z} column type, we employ the \texttt{p} column type instead of \texttt{m}
% (which centers content automatically). This choice ensures proper alignment of mathematical 
% expressions within cells of the same row.
% \medskip
%    \begin{macrocode}
\newcolumntype{T}{>{\centering\arraybackslash}X}
\newcolumntype{Z}{>{$}QT<{$}}
%    \end{macrocode}
% The \texttt{T} columns are not centered automatically. Although it's possible to achieve this
% by using the command "\renewcommand{\tabularxcolumn}[1]{m{#1}}"
% (with \texttt{m} instead of default value \texttt{p}), 
% unfortunately, this approach has a global effect on all column declarations  based 
% on \texttt{X}, including \texttt{T} and \texttt{Z}. As a result, it could disrupt the
% alignment of mathematical expressions within cells of the same row.
%    \begin{macrocode}
\newcolumntype{I}{!{\vrule width 1pt}}
\newcolumntype{V}[1]{!{\vrule width #1}}
\newlength\savedwidth
\newcommand{\whline}{%
    \noalign{\global\savedwidth\arrayrulewidth\global\arrayrulewidth 1pt}
    \hline
    \noalign{\global\arrayrulewidth\savedwidth}
}
\renewcommand\theadfont{\footnotesize\sffamily}
%    \end{macrocode}
%
% \begin{thebibliography}{11}
% \bibitem{ARRAY} \emph{A new implementation of LATEX’s \textsf{tabular} and \textsf{array} 
% environment}, Frank Mittelbach, David Carlisle, CTAN, v2.4k revised 2018/12/30.
% \bibitem{CELLSP} \emph{The \textsf{cellspace} package}, Josselin Noirel, CTAN, 
% v1.8.1 2019/03/11. 
% \bibitem{TABX} \emph{The \textsf{tabularx} package}, David Carlisle, CTAN, v2.11.b 2016/02/03.
% \bibitem{MKCELL} \emph{The \textsf{makecell} package}, Olga Lapko, CTAN, v0.1e 2009/08/03.
% \bibitem{TABY} \emph{The \textsf{tabulary} package}, David Carlisle, CTAN, v1.10 2014/06/11.
% \bibitem{TBLSTY} \emph{The \textsf{tablestyles} package}, Matthias Pospiech, CTAN, 
% v0.1 2014/06/27.
% \bibitem{BOOK} \emph{Publication quality tables in \LaTeX}, package \textsf{booktabs} by
% Simon Fear, CTAN, v1.618033 2016/04/29.
% \bibitem{TABLS} \emph{The \textsf{tabls} package}, Donald Arseneau, CTAN, v3.5 2010/02/26.
% \bibitem{STRUT} \emph{The \textsf{multirow}, \textsf{bigstrut} and \textsf{bigdelim} packages},
% Piet van Oostrum, Øystein Bache, Jerry Leichter, CTAN, v2.4 2019/01/01.
% \bibitem{SPA} \emph{The \textsf{spacingtricks} package}, Antoine Missier, 
% CTAN, v1.3 2020/11/02.
% \bibitem{COMP} \emph{The \LaTeX\ Companion}. Frank Mittelbach, Michel Goossens, 
% Johannes Braams, David Carlisle, Chris Rowley, 2nd edition, Pearson Education, 2004.
% \end{thebibliography}

% \Finale
\endinput