path: root/macros/latex/contrib/arraycols/arraycols.dtx

% \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