summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/tools/array.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-04-06 21:33:45 +0000
committerKarl Berry <karl@freefriends.org>2018-04-06 21:33:45 +0000
commit588be4d1b7e254f46ac3c678ef1b3f38833f6491 (patch)
treec73b58d23db18c19737ff12c67e208fd7a89c4c6 /Master/texmf-dist/source/latex/tools/array.dtx
parentc436d9d03043bac0aac83254a8f1a2a45e4aaafd (diff)
latex2e (6apr18)
git-svn-id: svn://tug.org/texlive/trunk@47330 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/tools/array.dtx')
-rw-r--r--Master/texmf-dist/source/latex/tools/array.dtx223
1 files changed, 209 insertions, 14 deletions
diff --git a/Master/texmf-dist/source/latex/tools/array.dtx b/Master/texmf-dist/source/latex/tools/array.dtx
index 2a648888065..1502265d962 100644
--- a/Master/texmf-dist/source/latex/tools/array.dtx
+++ b/Master/texmf-dist/source/latex/tools/array.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 1993-2016
+% Copyright 1993-2017
%
% The LaTeX3 Project and any individual authors listed elsewhere
% in this file.
@@ -12,7 +12,7 @@
% conditions of the LaTeX Project Public License, either version 1.3c
% 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
+% https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
@@ -26,7 +26,7 @@
%% Copyright (C) 1989-1998 Frank Mittelbach, all rights reserved.
%<+package>\NeedsTeXFormat{LaTeX2e}[1995/06/01]
%<+package>\ProvidesPackage{array}
-%<+package> [2016/10/06 v2.4d Tabular extension package (FMi)]
+%<+package> [2017/11/07 v2.4f Tabular extension package (FMi)]
%
% \fi
%
@@ -225,7 +225,7 @@
% For example, we used =\setlength{\extrarowheight}{1pt}=
% in table~\ref{tab:opt}.
%
-% \begin{table}[t]
+% \begin{table}[!t]
% \begin{center}
% \setlength{\extrarowheight}{1pt}
% \begin{tabular}{|>{\tt}c|m{9cm}|}
@@ -271,6 +271,23 @@
% vertical line, so this option doesn't
% suppress the normally inserted space between
% columns in contrast to =@{...}=.\\
+% \hline\hline
+% w\{align\}\{width\} & Sets the cell content in a box of the
+% specified \texttt{width} aligned according to
+% the \texttt{align} parameter which could be
+% either \texttt{l}, \texttt{c} or
+% \texttt{r}. Works essentially like
+% =\makebox[=width=][=align=]{=cell=}= so
+% silently overprints if the cell content is
+% wider than the specified width. If that is
+% not desired use \texttt{W} instead.\\
+% \hline
+% W\{align\}\{width\} & Like \texttt{w} but spits out an overfull
+% box warning (and an overfullrule marker in
+% draft mode) when the cell content is too wide
+% to fit. This also means that the alignment is
+% different if there is too much material,
+% because it then always protrudes to the right!\\
% \hline
% \end{tabular}
% \end{center}
@@ -324,6 +341,13 @@
% columns which is enlarged by one centimeter, while
% =c@{\hspace{1cm}}c= gives you exactly one centimeter
% space between two columns.
+%
+% \item
+% A declaration like =w{l}{3cm}= (or even shorter =wl{3cm}=)
+% works like an =l= column except that the width will always be
+% =3cm= regardless of the cell content. Same with =w{c}= or
+% =w{r}=. This means that it is easy to set up tables in which all
+% columns have predefined widths.
% \end{itemize}
%
% \subsection{Defining new column specifiers}
@@ -594,6 +618,16 @@
% note below).
% \end{itemize}
%
+% Prior to version 2.4f the space added by the optional argument to "\\"
+% was added inside an m-cell if the last column was of type
+% \texttt{m}. As a result that cell was vertically centered with that
+% space inside, resulting in a strange offset. Since 2.4f, this space
+% is now added after centering the cell.
+%
+% A similar problem happened when "\extrarowheight" was used. For that
+% reason m-cells now manually position the cell content which
+% allows to ignore this extra space request during the vertical aligment.
+%
%
% \subsection{Bugs and Features}
%
@@ -1267,6 +1301,16 @@
% \begin{macrocode}
\let\@sharp\relax \let\@startpbox\relax \let\@endpbox\relax
% \end{macrocode}
+% Two more are needed to deal with the code that handles struts
+% for extra space after a row from =\\[<space>]=
+% (=\do@row@strut=) and code that manages m-cells depending on
+% their heights (=\align@mcell=).
+% \changes{v2.4e}{2016/10/07}{Fixing SX68732}
+% \changes{v2.4f}{2017/11/04}{Managing m-cells without \cs{vcenter}}
+% \begin{macrocode}
+ \let\do@row@strut\relax
+ \let\align@mcell\relax
+% \end{macrocode}
% Now we remove possible $*$-forms in the user preamble with the
% command =\@xexpast=. As we already know, this command saves
% its result in the macro =\@tempa=.
@@ -1510,8 +1554,10 @@
% \end{macrocode}
% We end this case with =\d@llarend= and =\hfil= where =\d@llarend=
% again is either =$= or =\endgroup=.
+% The strut to enforce a regular row height is placed between the two.
+% \changes{v2.4e}{2016/10/07}{Fixing SX68732}
% \begin{macrocode}
- \d@llarend \hfil \or
+ \d@llarend \do@row@strut \hfil \or
% \end{macrocode}
% The templates for \texttt{l} and \texttt{r} (i.e.\ =\@chnum= $1$
% or $2$) are generated the same way. Since one =\hfil= is
@@ -1526,16 +1572,19 @@
% internal/2122}
% \changes{v2.3i}{1996/06/14}
% {Change both \cs{kern}\cs{z@} to \cs{hskip}1sp for latex/2160}
+% \changes{v2.4e}{2016/10/07}{Fixing SX68732}
% \begin{macrocode}
- \hskip1sp\d@llarbegin \insert@column \d@llarend \hfil \or
- \hfil\hskip1sp\d@llarbegin \insert@column \d@llarend \or
+ \hskip1sp\d@llarbegin \insert@column \d@llarend \do@row@strut \hfil \or
+ \hfil\hskip1sp\d@llarbegin \insert@column \d@llarend \do@row@strut \or
% \end{macrocode}
% The templates for \texttt{p}, \texttt{m} and \texttt{b} mainly
% consist of a \textsf{box}. In case of \texttt{m} it is generated
% by =\vcenter=. This command is allowed only in math
% mode. Therefore we start with a~=$=.
+% \changes{v2.4f}{2017/11/04}{Managing m-cells without \cs{vcenter}}
% \begin{macrocode}
- $\vcenter
+% $\vcenter
+ \setbox\mcell@box\vbox
% \end{macrocode}
% The part of the templates which is the same in all three cases
% (\texttt{p}, \texttt{m} and \texttt{b})
@@ -1545,15 +1594,22 @@
% \textsf{token} (i.e.\ =\@nextchar=).
% Between these two macros we find the well known
% =\insert@column=.
+% The strut is places after the box
+% \changes{v2.4e}{2016/10/07}{Fixing SX68732}
+% \changes{v2.4f}{2017/11/04}{Managing m-cells without \cs{vcenter}}
% \begin{macrocode}
- \@startpbox{\@nextchar}\insert@column \@endpbox $\or
+ \@startpbox{\@nextchar}\insert@column \@endpbox
+ \align@mcell
+%$
+ \do@row@strut \or
% \end{macrocode}
% The templates for \texttt{p} and \texttt{b} are generated in the
% same way though we do not need the =$= characters because we use
% =\vtop= or =\vbox=.
+% \changes{v2.4e}{2016/10/07}{Fixing SX68732}
% \begin{macrocode}
- \vtop \@startpbox{\@nextchar}\insert@column \@endpbox \or
- \vbox \@startpbox{\@nextchar}\insert@column \@endpbox
+ \vtop \@startpbox{\@nextchar}\insert@column \@endpbox\do@row@strut \or
+ \vbox \@startpbox{\@nextchar}\insert@column \@endpbox\do@row@strut
% \end{macrocode}
% Other values for =\@chnum= are impossible. Therefore we
% end the arguments to =\@addtopreamble= and =\ifcase=.
@@ -1564,6 +1620,65 @@
% \end{macrocode}
% \end{macro}
%
+
+%
+% \begin{macro}{\mcell@box}
+% When dealing with m-cells we need a box to measure the cell
+% height.
+% \changes{v2.4f}{2017/11/04}{Managing m-cells without \cs{vcenter}}
+% \begin{macrocode}
+\newbox\mcell@box
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\align@mcell}
+% M-cells are supposed to be vertically centered within the table
+% row. In the original implementation that was done using
+% =\vcenter= but the issue with that approach is that it centers
+% the material based on the math-axis. In most situations that
+% comes out quit right, but if, for example, an m-cell has only a
+% single line worth of material inside it will be positioned
+% differently to a =l=, =c= or =r= cell or to a =p= or =b= cell
+% with the same content.
+%
+% For that reason the new implementation does the centering
+% manually: First we check the height of the cell and if that is
+% less or equal to =\ht\@arstrutbox= we assume that this is a
+% single line cell. In that case we don't do any vertical maneuvre
+% and simply output the box, i.e., make it behave like a single
+% line p-cell.
+% \changes{v2.4f}{2017/11/04}{Managing m-cells without \cs{vcenter}}
+% \begin{macrocode}
+\def\align@mcell{%
+ \ifdim \ht\mcell@box > \ht\@arstrutbox
+% \end{macrocode}
+% Otherwise we realign vertically by lowering the box. The question
+% is how much do we need to move down? If there is any
+% =\arraystretch= in place then the first line will have some
+% unusual height and we don't want to consider that when finding
+% the middle point. So we substract from the cell height the height
+% of that strut. But of course we want to include the normal height
+% of the first line (which would be something like =\ht\strutbox=)
+% so we need to add that. On the other hand, when centering around
+% the mid-point of the cell, we also need to account for the depth
+% of the last line (which is nominally something like
+% =\dp\strutbox=). Both together equals =\baselineskip= so that is
+% what we add and then lower the cell by half of the resulting value.
+% \begin{macrocode}
+ \begingroup
+ \dimen@\ht\mcell@box
+ \advance\dimen@-\ht\@arstrutbox
+ \advance\dimen@\baselineskip
+ \lower.5\dimen@\box\mcell@box
+ \endgroup
+ \else % assume one line and align at baseline
+ \box\mcell@box
+ \fi}
+% \end{macrocode}
+% \end{macro}
+%
+
%
% \begin{macro}{\@classix}
% In case of class $9$ (\texttt{>}--\textsf{token}) we first check
@@ -2038,10 +2153,15 @@
% \begin{macro}{\@xargarraycr}
% \begin{macro}{\@yargarraycr}
% The following macros were already explained above.
+% \changes{v2.4e}{2016/10/07}{Fixing SX68732}
+% \begin{macrocode}
+\def\@xargarraycr#1{\unskip\gdef\do@row@strut
+ {\@tempdima #1\advance\@tempdima \dp\@arstrutbox
+ \vrule \@depth\@tempdima \@width\z@\global\let\do@row@strut\relax}\cr}
+\let\do@row@strut\relax
+% \end{macrocode}
+%
% \begin{macrocode}
-\def\@xargarraycr#1{\unskip
- \@tempdima #1\advance\@tempdima \dp\@arstrutbox
- \vrule \@depth\@tempdima \@width\z@ \cr}
\def\@yargarraycr#1{\cr\noalign{\vskip #1}}
% \end{macrocode}
% \end{macro}
@@ -2541,9 +2661,13 @@
% The main modification to "\@mkpream" is to replace the call to
% "\@xexpast" (which expanded $*$-forms) by a loop which expands
% all "\newcolumntype" specifiers.
+% \changes{v2.4e}{2016/10/07}{Fixing SX68732}
+% \changes{v2.4f}{2017/11/04}{Managing m-cells without \cs{vcenter}}
% \begin{macrocode}
\def\@mkpream#1{\gdef\@preamble{}\@lastchclass 4 \@firstamptrue
\let\@sharp\relax \let\@startpbox\relax \let\@endpbox\relax
+ \let\do@row@strut\relax
+ \let\align@mcell\relax
% \end{macrocode}
% Now we remove possible $*$-forms and user-defined column
% specifiers in the user preamble by repeatedly executing the list
@@ -2807,6 +2931,77 @@
%</package>
% \end{macrocode}
% \end{macro}
+
+% \subsection{Implementing column types \texttt{w} and \texttt{W}}
+%
+% In TugBoat 38/2 an extension was presented that implemented two
+% aditional column types \texttt{w} and \texttt{W}. These have now
+% been added to the package itself.
+%
+%
+% \begin{macro}{\ar@cellbox}
+% For \texttt{w} and \texttt{W} column types we need a box to
+% temporarily hold the cell content.
+% \changes{v2.4f}{2017/11/07}{Macro added}
+% \begin{macrocode}
+\newsavebox\ar@cellbox
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\newcolumntype w}
+% The \texttt{w} column type has two arguments: the first holds the
+% alignment which is either "l", "c", or "r" and the second is the
+% nominal width of the column.
+% \changes{v2.4f}{2017/11/07}{Column type added}
+% \begin{macrocode}
+\newcolumntype{w}[2]{%
+% \end{macrocode}
+% Before the cell content we start an "lrbox"-environment to
+% collect the cell material into the previously allocated box
+% "\ar@cellbox".
+% \begin{macrocode}
+ >{\begin{lrbox}\ar@cellbox}%
+% \end{macrocode}
+% Then comes a specifier for the cell content. We use "c", but
+% that doesn't matter as in the end we will always put a box of a
+% specific width ("#2") into the cells of that column, so "l" or
+% "r" would give the same result. There is only a difference if
+% there are also very wide "\multicolumn" rows overwriting the
+% setting in which case "c" seems to be slightly better.
+% \begin{macrocode}
+ c%
+% \end{macrocode}
+% At the end of the cell we end the "lrbox" environment so that all
+% of the cell content is now in box "\ar@cellbox". As a final step we
+% put that box into a "\makebox" using the optional arguments of
+% that command to achieve the correct width and the desired
+% alignment within that width.
+% \begin{macrocode}
+ <{\end{lrbox}%
+ \makebox[#2][#1]{\usebox\ar@cellbox}}}
+% \end{macrocode}
+% \end{macro}
+
+%
+%
+% \begin{macro}{\newcolumntype W}
+% The \texttt{W} is similar but in this case we want a warning if
+% the cell content is too wide.
+% \changes{v2.4f}{2017/11/07}{Column type added}
+% \begin{macrocode}
+\newcolumntype{W}[2]
+ {>{\begin{lrbox}\ar@cellbox}%
+ c%
+ <{\end{lrbox}%
+ \let\hss\hfil
+ \makebox[#2][#1]{\unhbox\ar@cellbox}}}
+% \end{macrocode}
+% This is a bit sneaky, as it temporarily disables "\hss", but
+% given that we know what goes into that box it should be
+% sufficient.
+% \end{macro}
+%
%
% \PrintIndex
% \PrintChanges