summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/arraycols/arraycols.dtx
blob: b3a438be983727f8fe495485f5790c76b56bd121 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
% \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/09/13 v1.4 .dtx arraycols file]
%</package>
%<*driver>
\documentclass{ltxdoc}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[french,english]{babel}
\usepackage{lmodern}
\usepackage{arraycols}

\usepackage{sectsty}
\usepackage{xcolor}
\definecolor{darkbrown}{rgb}{0.5,0.1,0.1}
\allsectionsfont{\color{darkbrown}}

\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/08/09}{Small changes in documentation}
% \changes{v1.4}{2023/09/13}{More changes in 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{September 13, 2023}
% \maketitle
%
% \section{Introduction}
%
% This package introduces new predefined column types for tables, in addition to
% 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},
% which will be detailed in the following section.
% 
% \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 by another package,
% using \textsf{arraycols} will overwrite it and display a warning message.
%
% In addition to loading the \textsf{array} package, \textsf{arraycols} 
% also requires \textsf{cellspace}~\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, but differently.
% Nevertheless, \textsf{tablestyles} is incompatible with \textsf{makecell}
% and consequently with \textsf{arraycols} as well.
%
% With its minimal code, \textsf{arraycols} makes no claim to develop new macros. 
% Its purpose is to combine and configure functionalities 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, enable the
% reversal of 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 in text mode, left-aligned\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 within \texttt{tabulary} environments.
% }.
% 
% \medskip
% \DescribeEnv{t\marg{width}}
% The newly introduced column type definition \texttt{t}\{\meta{width}\} 
% horizontally and vertically centers paragraphs within the column,
% with a specified \meta{width}.
% In contrast, the traditional \texttt{p}\marg{width} (in standard \LaTeX) 
% and \texttt{m}\marg{width} (from the \textsf{array} package) column types, 
% justifies paragraphs, while text in \texttt{t}\{\meta{width}\} is centered.
%
% \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).
% These column types activate the mathematical mode and
% allow automatic adjustment of row heights to prevent any overlap with
% horizontal rules in cases where the content is too tall,
% thanks to a functionality of the \textsf{cellspace} package 
% by Josselin Noirel~\cite{CELLSP}.
% While \textsf{cellspace} is initially designed for \texttt{tabular} environments,
% the new \texttt{x} and \texttt{y} column types
% 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 efficiently manage row heights, including in matrices.
% Another option of \textsf{cellspace}, \texttt{column=Q}
% (with \texttt{S} being the default in \textsf{cellspace})\footnote{The
% letter Q is a substitute for the default column modifier S of the \textsf{cellspace}
% package.}, was necessary to prevent any compatibility issues
% with the	\textsf{siunitx} package (also loaded by \textsf{pstricks-add}). 
% The \texttt{Q} declaration serves as a \og modifier \fg{}
% that, when placed before a column type declaration,
%  permits the adjustment of cell height,
% for instance ``\texttt{Qc}'' for a vertical adjustment
% within a centered column type.
% 
% \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 set the \textsf{cellspace} parameters as follows:\\
% \indent\indent"\setlength{\cellspacetoplimit}{3pt}", \\
% \indent\indent"\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 activates the mathematical mode 
% and allows to define the column width, 
% similar to \texttt{t}\marg{width}.
% It also adjusts the row height, akin to the \texttt{x} column type.
% The content consist of a single line. When it becomes too wide, it may protrude to the right.
%
% \medskip
%  \DescribeEnv{T}  \DescribeEnv{Z}
% The \textsf{tabularx} package by David Carlisle~\cite{TABX} introduces
% the \texttt{X} column definition, which calculates its width in relation to 
% the required width for the entire table. It aligns text to the left
% similar 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 activates mathematical 
% mode and adjusts
% 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}
% Observe that cells 3 and 4 are not vertically centered to preserve
% the precise alignment of fraction bars within mathematical formulas
% across cells.
% For achieving accurate vertical positioning
% within the last cell, we have used the powerful "\makecell"\oarg{pos}\marg{content}
% 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, enables the drawing of
% 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}"
% (in \textsf{makecell} it is |\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 provides 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}
% For the \texttt{z} column type, we employed the \texttt{p} declaration
% instead of \texttt{m} (which should automatically center content). 
% This choice ensures proper alignment of mathematical 
% expressions within cells of the same row.
% The same result can be achieved with the following definition:
% "\newcolumntype{z}[1]{>{$}Q{W{c}{#1}}<{$}}" with "W{c}" defined
% in the \textsf{array} package.
%
% \medskip
%    \begin{macrocode}
\newcolumntype{T}{>{\centering\arraybackslash}X}
\newcolumntype{Z}{>{$}QT<{$}}
%    \end{macrocode}
% Like \texttt{X}, the \texttt{T} columns are not vertically centered. 
% 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.
%
% \medskip
%    \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}
%
% \bigskip
% \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