summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/supertabular/supertabular.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/supertabular/supertabular.dtx')
-rw-r--r--macros/latex/contrib/supertabular/supertabular.dtx272
1 files changed, 216 insertions, 56 deletions
diff --git a/macros/latex/contrib/supertabular/supertabular.dtx b/macros/latex/contrib/supertabular/supertabular.dtx
index 130ad13dd0..be31a2d113 100644
--- a/macros/latex/contrib/supertabular/supertabular.dtx
+++ b/macros/latex/contrib/supertabular/supertabular.dtx
@@ -1,17 +1,17 @@
% \iffalse meta-comment
%
-% Copyright 1989-2004 Johannes L. Braams. All rights reserved.
+% Copyright 1989-2020 Johannes L. Braams. All rights reserved.
%
% This file is part of the supertabular package.
% ---------------------------------------------
%
% It may be distributed and/or modified under the
-% conditions of the LaTeX Project Public License, either version 1.3
+% 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
-% and version 1.3 or later is part of all distributions of LaTeX
-% version 2003/12/01 or later.
+% and version 1.3c or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status "maintained".
%
@@ -25,12 +25,12 @@
% extension .ins) which are part of the distribution.
% \fi
%
-% \CheckSum{1025}
+% \CheckSum{1132}
% \iffalse
%% Sourcefile `supertabular.dtx'.
%%
%% Copyright (C) 1988 by Theo Jurriens
-%% Copyright (C) 1990-2004 by Johannes Braams texniek at braams.cistron.nl
+%% Copyright (C) 1990-2020 by Johannes Braams texniek at braams.xs4all.nl
%% Kersengaarde 33
%% 2723 BP Zoetermeer NL
%% all rights reserved.
@@ -43,11 +43,11 @@
%<package>\ProvidesPackage{supertabular}
%<driver>\ProvidesFile{supertabular.drv}
%\ProvidesFile{supertabular.dtx}
- [2004/02/20 v4.1e the supertabular environment]
+ [2020/02/02 v4.1g the supertabular environment]
%
%<*driver>
\documentclass{ltxdoc}
-\usepackage{supertabular}
+\usepackage[debugshow]{supertabular}
\newcommand{\tbsp}{\rule{0pt}{18pt}}
\begin{document}
\providecommand{\Lenv}[1]{\textsf{#1}}
@@ -187,16 +187,16 @@
% of the table with the command |\shrinkheight{...pt}| after the
% first |\\| of the supertabular.
% \item The \Lenv{mpsupertabular} environment sometimes has problems
-% with pagesbreaks when footnotes appear in the lower part of the
+% with pagebreaks when footnotes appear in the lower part of the
% tabular.
% \end{itemize}
%
% \section{Examples}
%
% \DeleteShortVerb{\|}
-% Here is an example of a \Lenv{supertabular}. You will find the
-% definitions after the table.
-%
+% Here is an example of a \Lenv{supertabular}.
+% First, here is (part of) the user input for the table below:
+%\begin{verbatim}
% \begin{center}
% \tablefirsthead{%
% \hline
@@ -222,32 +222,18 @@
% \bottomcaption{This table is split across pages}
%
% \begin{supertabular}{|r@{\hspace{6.5mm}}|r@{\hspace{5.5mm}}|r|r|}
-% 1\tbsp & 1 & 1 & 1 \\
+% 1 & 1 & 1 & 1 \\
% 2 & 4 & 16 & 2 \\
% 3 & 9 & 81 & 6 \\
% 4 & 16 & 256 & 24 \\[5mm]
-% 5 & 25 & 625 & 120 \\
-% 6 & 36 & 1296 & 720 \\
-% 7 & 49 & 2401 & 5040 \\
-% 8 & 64 & 4096 & 40320 \\
-% 9 & 81 & 6561 & 362880 \\
-% 10 & 100 & 10000 & 3628800 \\
-% 11 & 121 & 14641 & 39916800 \\
-% 12 & 144 & 20736 & 479001600 \\[.5cm]
-% \hline & & & \\
-% 13 & 169 & 28561 & 6.22702080E+9 \\[1cm]
-% 14 & 196 & 38416 & 8.71782912E+10\\
-% 15 & 225 & 50625 & 1.30767437E+12\\
-% 16 & 256 & 65536 & 2.09227899E+13\\
-% 17 & 289 & 83521 & 3.55687428E+14\\[5mm]
-% 18 & 324 & 104976 & 6.40237370E+15\\
+% ...
% 19 & 361 & 130321 & 1.21645100E+17\\
% 20 & 400 & 160000 & 2.43290200E+18\\
% \end{supertabular}
% \end{center}
+%\end{verbatim}
%
-% And here is (part of) the user input for the table above:
-%\begin{verbatim}
+% Then the table should be split across the page boundary:
% \begin{center}
% \tablefirsthead{%
% \hline
@@ -273,16 +259,29 @@
% \bottomcaption{This table is split across pages}
%
% \begin{supertabular}{|r@{\hspace{6.5mm}}|r@{\hspace{5.5mm}}|r|r|}
-% 1 & 1 & 1 & 1 \\
+% 1\tbsp & 1 & 1 & 1 \\
% 2 & 4 & 16 & 2 \\
% 3 & 9 & 81 & 6 \\
% 4 & 16 & 256 & 24 \\[5mm]
-% ...
+% 5 & 25 & 625 & 120 \\
+% 6 & 36 & 1296 & 720 \\
+% 7 & 49 & 2401 & 5040 \\
+% 8 & 64 & 4096 & 40320 \\
+% 9 & 81 & 6561 & 362880 \\
+% 10 & 100 & 10000 & 3628800 \\
+% 11 & 121 & 14641 & 39916800 \\
+% 12 & 144 & 20736 & 479001600 \\[.5cm]
+% \hline & & & \\
+% 13 & 169 & 28561 & 6.22702080E+9 \\[1cm]
+% 14 & 196 & 38416 & 8.71782912E+10\\
+% 15 & 225 & 50625 & 1.30767437E+12\\
+% 16 & 256 & 65536 & 2.09227899E+13\\
+% 17 & 289 & 83521 & 3.55687428E+14\\[5mm]
+% 18 & 324 & 104976 & 6.40237370E+15\\
% 19 & 361 & 130321 & 1.21645100E+17\\
% 20 & 400 & 160000 & 2.43290200E+18\\
% \end{supertabular}
% \end{center}
-%\end{verbatim}
%
% Here is another example whith a \texttt{p} column-definition. The
% tablehead is the same as above. The tabletail is a double
@@ -290,6 +289,13 @@
% the font size is \verb|\small|.
%
% \begin{center}
+% \tablefirsthead{%
+% \hline
+% \multicolumn{1}{|c}{\tbsp Number} &
+% \multicolumn{1}{c}{Number$^2$} &
+% Number$^4$ &
+% \multicolumn{1}{c|}{Number!} \\
+% \hline}
% \tablelasttail{\hline\hline}
% \topcaption{This table should also be split accross pages.}
% \renewcommand{\arraystretch}{1.5}
@@ -337,6 +343,13 @@
% full width of the text.
%
% \begin{center}
+% \tablefirsthead{%
+% \hline
+% \multicolumn{1}{|c}{\tbsp Number} &
+% \multicolumn{1}{c}{Number$^2$} &
+% Number$^4$ &
+% \multicolumn{1}{c|}{Number!} \\
+% \hline}
% \tablelasttail{\hline\hline}
% \topcaption{This table should also be split accross pages.}
% \renewcommand{\arraystretch}{1.5}
@@ -407,12 +420,16 @@
% \StopEventually{}
%
% \section{The Implementation}
-%
+% First we define a few options that control the level of tracing
+% output this package delivers. the option \textsf{errorshow} is the
+% default situation.
+% \changes{v4.1f}{2019/01/16}{The value for \cs{C@tracingst} needs to
+% be 3 instead of 2}
% \begin{macrocode}
%<*package>
\newcount\c@tracingst
\DeclareOption{errorshow}{\c@tracingst\z@}
-\DeclareOption{pageshow}{\c@tracingst\tw@}
+\DeclareOption{pageshow}{\c@tracingst\thr@@}
\DeclareOption{debugshow}{\c@tracingst5\relax}
\ProcessOptions
% \end{macrocode}
@@ -487,6 +504,22 @@
% \end{macro}
% \end{macro}
%
+% \begin{macro}{\ST@captionroom}
+% \changes{v4.1g}{2020/02/02}{New macro}
+% When a supertabular is preceded by a caption that fact might not
+% yet be visible in the amount of space occupoed on the page
+% sofar. Therefore we include the possibility to reduce the height
+% of the first part of the supertabular. In order to this we need a
+% macro that indicates a aption has been put in front of the
+% table. We do this to reduce the risk that the first part of the
+% table is too high after all and is pushed onto the next page due
+% to an overfull |\vbox| condition.
+% \begin{macrocode}
+\def\ST@captionroom{\z@}
+% \end{macrocode}
+% \end{macro}
+%
+%
% \begin{macro}{\ST@caption}
% This is a redefinition of LaTeX's |\@caption|, |\@makecaption| is
% called within a group so as not to return to |\normalsize|
@@ -496,6 +529,8 @@
% and \textbf{none} at the bottom. If a user wants to precede his
% table with a caption this results in a collision.
%
+% \changes{v4.1g}{2020/02/02}{Record the fact that a caption has
+% preceeded the table by setting \cs{ST@captionroom}}
% \begin{macrocode}
\long\def\ST@caption#1[#2]#3{\par%
\addcontentsline{\csname ext@#1\endcsname}{#1}%
@@ -506,7 +541,7 @@
\normalsize
\if@topcaption \vskip -10\p@ \fi
\@makecaption{\csname fnum@#1\endcsname}{\ignorespaces #3}\par
- \if@topcaption \vskip 10\p@ \fi
+ \if@topcaption \vskip 10\p@ \gdef\ST@captionroom{20\p@}\fi
\endgroup}
% \end{macrocode}
% \end{macro}
@@ -528,7 +563,25 @@
#1%
\noalign{\global\let\\=\@savcr}}}
\tablehead{}
-\newcommand\tablefirsthead[1]{\gdef\@table@first@head{#1}}
+% \end{macrocode}
+% It's possible to specify a different tablehead for the first
+% `part' of the table. That only needs to be used once so it
+% `undefines' itself at the end. That way we make sure that it
+% doesn't accidentally get used for a second supertabular in the
+% document.
+% \changes{v4.1f}{2019/01/12}{\cs{\@table@first@head} needs the same
+% definition as \cs{\@tablehead} (found by FMi)}
+% \begin{macrocode}
+\newcommand\tablefirsthead[1]{%
+ \gdef\@table@first@head{%
+ \noalign{%
+ \global\let\@savcr=\\
+ \global\let\\=\org@tabularcr}%
+ #1%
+ \noalign{%
+ \global\let\\=\@savcr
+ \global\let\@table@first@head\undefined
+ }}}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -539,7 +592,7 @@
% |\multicolumn|) in |\tabletail| \TeX\ starts looping because of
% the definition of |\ST@cr|. So make |\\| act just like a
% |\@tabularcr| inside this tail to prevent the loop. Save and
-% restore the value of |\\|
+% restore the value of |\\|.
%
% \changes{v4.0i}{1997/09/18}{Don't reset \cs{}\cs{} to \cs{cr}, but
% to \cs{@tabularcr}}
@@ -554,7 +607,25 @@
#1%
\noalign{\global\let\\=\@savcr}}}
\tabletail{}
-\newcommand\tablelasttail[1]{\gdef\@table@last@tail{#1}}
+% \end{macrocode}
+% It's possible to specify a different tabletail for the last
+% `part' of the table. That only needs to be used once so it
+% `undefines' itself at the end. That way we make sure that it
+% doesn't accidentally get used for a second supertabular in the
+% document.
+% \changes{v4.1f}{2019/01/12}{\cs{\@table@last@tail} needs the same
+% definition as \cs{\@tabletail}}
+% \begin{macrocode}
+\newcommand\tablelasttail[1]{%
+ \gdef\@table@last@tail{%
+ \noalign{%
+ \global\let\@savcr=\\
+ \global\let\\=\org@tabularcr}%
+ #1%
+ \noalign{%
+ \global\let\\=\@savcr
+ \global\let\@table@last@tail\undefined
+ }}}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -587,6 +658,39 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macro}{\ST@trace@cr}
+% A variant of |\ST@trace| that can be called from within |\\| as
+% that command is looking for an optional argument will end up
+% scanning the next line.
+% \begin{macro}{\ST@save@lineno}
+% \changes{v4.1f}{2019/01/18}{Added a macro to save the current input
+% linenumber}
+% But because this variant is called from within |\\| we need to
+% save the current input linenumber before \TeX\ starts scanning
+% for the optional argument. If we don't, the reported linenumber
+% depends on whether or not the optional argument is present...
+% \begin{macrocode}
+\newcommand\ST@save@lineno{%
+ \expandafter\gdef\expandafter\ST@LineNo\expandafter{%
+ \the\inputlineno}}
+% \end{macrocode}
+% Within |\ST@trace@cr| we can than locally modify |\on@line| to
+% use this saved line number.
+% \begin{macrocode}
+\newcommand\ST@trace@cr[2]{%
+ \ifnum\c@tracingst>#1\relax
+ \begingroup
+ \edef\on@line{ on input line \ST@LineNo}%
+ \GenericWarning
+ {(supertabular)\@spaces\@spaces}
+ {Package supertabular: #2}%
+ \endgroup
+ \fi
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
% \begin{macro}{\ST@pageleft}
% \changes{v3.7b}{1994/05/16}{Renamed from \cs{maxsize}}
% \changes{v4.0a}{1996/11/28}{Renamed from \cs{page@left}}
@@ -662,9 +766,11 @@
% height of the previous line to use it as an estimate for the
% height of the next line. This is needed for a better estimate of
% when to break the tabular.
+% \changes{v4.1g}{2020/02/02}{\cs{ST@stretchht} is no longer needed,
+% will be removed in a future release}
% \begin{macrocode}
\newdimen\ST@lineht
-\newdimen\ST@stretchht
+%\newdimen\ST@stretchht
\newdimen\ST@prevht
% \end{macrocode}
% \end{macro}
@@ -701,10 +807,13 @@
% |\@xtabularcr|.
%
% All redefined macros have names that are similar to the original
-% names, except with a leading 'ST'
+% names, except with a leading 'ST'.
% \begin{macrocode}
+% \changes{v4.1f}{2019/01/18}{Save the input linenumber before \TeX\
+% scans for an optional argument}
\def\ST@tabularcr{%
{\ifnum0=`}\fi
+ \ST@save@lineno
\@ifstar{\ST@xtabularcr}{\ST@xtabularcr}}
\def\ST@xtabularcr{%
\@ifnextchar[%]
@@ -797,15 +906,40 @@
% \end{macrocode}
% \end{macro}
% \end{macro}
-%
+%
+% \begin{macro}{\ST@compute@lineht}
+% \changes{v4.1g}{2020/02/02}{New macro \cs{ST@compute@lineht} to
+% replacte \cs{estimate@lineht}}
+% The height of a line in an array environemnt can be computed as:
+% \begin{itemize}
+% \item the height of the strutbox |\ht\strutbox| (plus
+% |\extrarowheight| when the \pkg{array} package is loaded),
+% \item multiplied by arraystretch,
+% \item plus the depth of the strutbox (|\dp\strutbox|) mulitplied
+% by |\arraystretch|.
+% \end{itemize}
+% \begin{macrocode}
+\def\ST@compute@lineht{%
+ \ST@lineht=\ht\strutbox
+ \ifx\extrarowheight\undefined\else
+ \advance \ST@lineht by \extrarowheight
+ \fi
+ \ST@lineht = \arraystretch\ST@lineht
+ \advance\ST@lineht \arraystretch\dp\strutbox
+ \ST@trace\tw@{Normal Line height: \the\ST@lineht}%
+ }
+% \end{macrocode}
+% \end{macro}
+%
% \begin{macro}{\estimate@lineht}
% Estimates the height of normal line taking |\arraystretch| into
% account. Also computes the difference between a normal line and a
% `stretched' one.
% \changes{v4.0b}{1997/02/04}{Removed use of \cs{ST@pboxcorr}}
% \changes{v4.0g}{1997/04/12}{Added the computation of
-% \cs{ST@stretchht}}
-% \begin{macrocode}
+% \cs{ST@stretchht}}
+% This macro will be removed in a future release.
+% \begin{macrocode}
\def\estimate@lineht{%
\ST@lineht=\arraystretch \baslineskp
\global\advance\ST@lineht by 1\p@
@@ -813,7 +947,7 @@
\ifdim\ST@stretchht<\z@\ST@stretchht\z@\fi
\ST@trace\tw@{Average line height: \the\ST@lineht}%
\ST@trace\tw@{Stretched line height: \the\ST@stretchht}%
- }
+}
% \end{macrocode}
% \end{macro}
%
@@ -900,6 +1034,13 @@
\global\ST@pagesofar\z@
\fi
\fi
+% \end{macrocode}
+% When a caption preceeds the first part of the tabular we need to
+% reduce the available height on the page by |\ST@captionroom|.
+% \changes{v4.1g}{2020/02/02}{Reduce the available height left on the
+% page when a caption preceeded the table}
+% \begin{macrocode}
+ \if@topcaption\advance\ST@pageleft-\ST@captionroom\fi
\ST@trace\tw@{Available height: \the\ST@pageleft}%
% \end{macrocode}
% Now we need to know the height of the head of the table. In order
@@ -953,6 +1094,15 @@
\ST@trace\tw@{starting new page}%
\newpage\@calnextpageht
\fi
+% \end{macrocode}
+% Take the height of the table into account,sosubstract it from the
+% available height. We need to do it like this because the |\\|
+% inside the definition of |\@@tablehead| have their normal
+% definition.
+% \changes{v4.1g}{2020/02/02}{Subtract the height of the tablehead
+% from the available space}
+% \begin{macrocode}
+ \advance\ST@pageleft-\ST@headht
}
% \end{macrocode}
% \end{macro}
@@ -968,6 +1118,13 @@
\global\ST@pageleft\@colroom
\global\ST@pagesofar=\z@
\ST@trace\tw@{Maximum height of tabular: \the\ST@pageleft}%
+% \end{macrocode}
+% Take the height of the head into account by subtracting it from
+% the avalable space.
+% \changes{v4.1g}{2020/02/02}{Subtract \cs{ST@headht} from
+% \cs{ST@pageleft}}
+% \begin{macrocode}
+ \advance\ST@pageleft-\ST@headht
}
% \end{macrocode}
% \end{macro}
@@ -1019,7 +1176,7 @@
% Save old |\@tabularcr| and insert the definition of
% \changes{v4.1c}{1997/11/07}{For standard \LaTeX\ we need to change
% \cs{@@startpbox}, \emph{not} \cs{@startpbox}}
-% |\@stabularcr|.
+% |\ST@tabularcr|.
% \begin{macrocode}
\let\org@tabularcr\@tabularcr
\let\@tabularcr\ST@tabularcr
@@ -1054,7 +1211,7 @@
% \end{macrocode}
% The first part of a supertabular may be moved on to the next page
% if it doesn't fit on the current page afterall. Subsequent parts
-% can not be moved; therefore we will have to switch the definition
+% can not be moved; therefor we will have to switch the definition
% of |\ST@skippart| around.
% \changes{v4.0e}{1997/04/09}{Make sure that only the first part of a
% supertabular can be moved to the next page.}
@@ -1064,8 +1221,9 @@
% Now we can estimate the average line height and the height of the
% first page of the \Lenv{supertabular}.
% \changes{v4.0i}{1997/09/18}{Added \cs{noindent}}
+% \changes{v4.1g}{2020/02/02}{Now call \cs{ST@compute@lineht}}
% \begin{macrocode}
- \estimate@lineht
+ \ST@compute@lineht
\@calfirstpageht
\noindent
}
@@ -1361,7 +1519,7 @@
% In order to facilitate complete \Lenv{tabular} environments to be
% in a cell of a \Lenv{supertabular} environment we need to adapt
% the definition of the orginal environments somewhat. For the
-% inner \Lenv{tabular} a number of definitions needs to be
+% inner \Lenv{tabular} a number of definitions need to be
% restored.
% \changes{v4.0i}{1997/09/18}{Added \cs{noindent}}
% \begin{macrocode}
@@ -1390,7 +1548,7 @@
% \end{macrocode}
% If there is a non-empty line, but an empty parbox, then
% |\ST@pboxht| might be non-zero, but too small thereby breaking
-% the algorithm. Therefore we estimate the height of the line to be
+% the algorithm. Therefor we estimate the height of the line to be
% |\ST@lineht| in this case.
% \begin{macrocode}
\global\advance\ST@pageleft -\ST@lineht
@@ -1406,11 +1564,13 @@
% (plus a bit extra).
% \changes{v4.0g}{1997/04/12}{Also take \cs{ST@stretchht} into
% account and store the height of the parbox in \cs{ST@prevht}}
+% \changes{v4.1f}{2019/03/01}{Use \cs{ST@trace@cr} instead of
+% \cs{ST@trace}}
+% \changes{v4.1g}{2020/02/02}{\cs{ST@stretchht} is no longer needed}
% \begin{macrocode}
- \ST@trace\thr@@{Added par box with height \the\ST@pboxht}%
+ \ST@trace@cr\thr@@{Added par box with height \the\ST@pboxht}%
\global\advance\ST@pageleft -\ST@pboxht
\global\advance\ST@pageleft -0.1\ST@pboxht
- \global\advance\ST@pageleft -\ST@stretchht
\global\ST@prevht\ST@pboxht
\global\ST@pboxht\z@
\fi
@@ -1419,7 +1579,7 @@
% \begin{macrocode}
\global\advance\ST@pageleft -\ST@toadd
\global\ST@toadd=\z@
- \ST@trace\thr@@{Space left for tabular: \the\ST@pageleft}%
+ \ST@trace@cr\thr@@{Space left for tabular: \the\ST@pageleft}%
}
% \end{macrocode}
% This line is necessary because the tablehead has to be inserted
@@ -1445,8 +1605,8 @@
\else
% \end{macrocode}
% When there is not enough space left on the current page, we start
-% a new page. To compute the amount of space needed we use the
-% height of the previous line (|\ST@prevht|) as an estimation of
+% a new page. To compute the amount of space need we use the
+% height of the previous line (|\ST@prevht|) as an estimation of
% the height of the next line. If we are processing a
% \Lenv{mpsupertabular} we need to take the height of the footnotes
% into account.
@@ -1494,7 +1654,7 @@
% \global\advance\ST@pageleft-\ST@dimen
%\end{verbatim}
% When you examine the code you will note that |\@colroom| is added
-% \emph{and} subtracted. Therefore the code above can be simplified
+% \emph{and} subtracted. Therefor the code above can be simplified
% to:
% \begin{macrocode}
\global\advance\ST@pageleft\pagetotal