diff options
Diffstat (limited to 'macros/latex/contrib/supertabular/supertabular.dtx')
-rw-r--r-- | macros/latex/contrib/supertabular/supertabular.dtx | 323 |
1 files changed, 207 insertions, 116 deletions
diff --git a/macros/latex/contrib/supertabular/supertabular.dtx b/macros/latex/contrib/supertabular/supertabular.dtx index be31a2d113..6bde17bbfa 100644 --- a/macros/latex/contrib/supertabular/supertabular.dtx +++ b/macros/latex/contrib/supertabular/supertabular.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright 1989-2020 Johannes L. Braams. All rights reserved. +% Copyright 1989-2021 Johannes L. Braams. All rights reserved. % % This file is part of the supertabular package. % --------------------------------------------- @@ -25,14 +25,13 @@ % extension .ins) which are part of the distribution. % \fi % -% \CheckSum{1132} +% \CheckSum{1188} % \iffalse %% Sourcefile `supertabular.dtx'. %% %% Copyright (C) 1988 by Theo Jurriens -%% Copyright (C) 1990-2020 by Johannes Braams texniek at braams.xs4all.nl -%% Kersengaarde 33 -%% 2723 BP Zoetermeer NL +%% Copyright (C) 1990-2024 by Johannes Braams texniek at texniek.nl +%% The Netherlands %% all rights reserved. %% %% @@ -43,11 +42,11 @@ %<package>\ProvidesPackage{supertabular} %<driver>\ProvidesFile{supertabular.drv} %\ProvidesFile{supertabular.dtx} - [2020/02/02 v4.1g the supertabular environment] + [2024/07/20 v4.2c the supertabular environment] % %<*driver> \documentclass{ltxdoc} -\usepackage[debugshow]{supertabular} +\usepackage[debugshow,calculate]{supertabular} \newcommand{\tbsp}{\rule{0pt}{18pt}} \begin{document} \providecommand{\Lenv}[1]{\textsf{#1}} @@ -59,17 +58,19 @@ %</driver> % \fi % -% \changes{v4.0a}{1996/11/28}{Cleanup of the code, now a \file{.dtx} -% source file} -% \changes{v4.0c}{1997/02/20}{Replace \cs{tableformat} by -% \cs{ST@tableformat} to prevent a clash with the \pkg{KOMA} -% pacakage} -% \changes{v4.0f}{1997/04/10}{Repaired a few typos in the -% documentation} -% \changes{v4.1a}{1997/09/18}{Repaired a number of typos and added -% contributed mpsupertabular environemnts} -% \changes{v4.1b}{1997/10/08}{Renamed \cs{@@tabularcr} to -% \cs{org@tabularcr}} +% \changes{v4.0a}{1996/11/28}{Cleanup of the code, now a \file{.dtx} +% source file} +% \changes{v4.0c}{1997/02/20}{Replace \cs{tableformat} by +% \cs{ST@tableformat} to prevent a clash with the \pkg{KOMA} +% pacakage} +% \changes{v4.0f}{1997/04/10}{Repaired a few typos in the +% documentation} +% \changes{v4.1a}{1997/09/18}{Repaired a number of typos and added +% contributed mpsupertabular environemnts} +% \changes{v4.1b}{1997/10/08}{Renamed \cs{@@tabularcr} to +% \cs{org@tabularcr}} +% \changes{v4.2a}{2020-06-27}{renamed \cs{ST@lineht} to \cs{ST@rowht}} +% \changes{v4.2c}{2024/07/20}{A few documentation changes} % % \GetFileInfo{supertabular.dtx} % \title{The \texttt{supertabular} environment\thanks{This file @@ -110,7 +111,13 @@ % and why \pkg{supertabular} decides to break the tabular % environment in order to produce a new page. % \item The option \textsf{debugshow} also adds information about -% each line that is added to the tabular. +% each row that is added to the tabular. +% \item The option \textsf{estimate} (the default) has the package +% use the old estimation-based algortihm to establish the height +% of individual rows. +% \item The option \textsf{calculate} has the package use the new +% calculation-based algortihm to establish the height +% of individual rows. % \end{enumerate} % % Below is a description of the new commands and environments that @@ -172,15 +179,15 @@ % % \begin{itemize} % \item When the material of a normal entry (not a p-arg) becomes -% larger than the estimated |\ST@lineht|, overfull |\vbox|es -% will be produced at all. +% larger than the estimated |\ST@rowht|, overfull |\vbox|es +% will be produced. % \item When the last p-arg on a page gets more than 4 lines % (probably even more than 3 lines) it will result in an overfull % |\vbox|. Also some combinations of |\baselinestretch| -% |\arraystretch| and a large font may lead to one line too much. -% \item if accidentally the last line of the tabular produces a +% |\arraystretch| and a large font may lead to one row too much. +% \item if accidentally the last row of the tabular produces a % newpage, on the next page the tabletail will be written -% immediately after the tablehead. Depending on the contents this +% immediately after the tablehead. Depending on the contents, this % may result in an error message regarding misplaced |\noalign|. % % A quick but not very elegant solution: shrink the allowed height @@ -431,6 +438,36 @@ \DeclareOption{errorshow}{\c@tracingst\z@} \DeclareOption{pageshow}{\c@tracingst\thr@@} \DeclareOption{debugshow}{\c@tracingst5\relax} +% \end{macrocode} +% In version 4.1g a new way of determining the height of the +% average row was introduced. Instead of using an estimation, based +% on the value of |\baselineskip| a computation was introduced, +% based on the size of the |\strutbox|. The effect of this new +% method was that the parial tabulars fill the page better, so less +% \texttt{underfull vbox} message would appear. Unfortunately this +% had a negative effect on existing documents (that don;t come out +% like they used to) and especially when a very small font +% (|\tiny| or |\scriptsize| was chosen for the tabular and the +% cells contain subscripts or superscripts. It turned out that the +% heigth and depth of a formula like $5^5_5$ exceeds the size of +% |\strutbox|. The result is that the rows have more height (and/or +% depth) thatn what the algorithm computed. Hence, when more rows +% are added to the partial tabular than fit on the page. Especially +% on the first part thisis a probem as the partial tabular becomes +% too high and doesn't fit in the avialbale space. \TeX\ then +% decides to move it to the next page, resulting in two +% consecutive pages that have a lot of white space on them. +% \changes{v4.2a}{2020-06-27}{Two new options to choose the +% computation algorithhm} +% \begin{macrocode} +\DeclareOption{calculate}{\def\ST@calculate@rowht{\ST@compute@rowht}} +\DeclareOption{estimate}{\def\ST@calculate@rowht{\ST@estimate@rowht}} +%\def\ST@calculate@rowht{\ST@estimate@rowht} +% \end{macrocode} +% The default for the options is to only show errors and use the +% old estmation algorithm (so as not to break old documents). +% \begin{macrocode} +\ExecuteOptions{errorshow,estimate} \ProcessOptions % \end{macrocode} % @@ -510,7 +547,7 @@ % 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 +% macro that indicates a caption 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. @@ -523,7 +560,7 @@ % \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| -% globally. also a fix is made for the `feature' of the +% globally. Also a fix is made for the `feature' of the % |\@makecaption| of the document class \cls{article} and friends % that a caption \textbf{always} gets a |\vskip 10pt| at the top % and \textbf{none} at the bottom. If a user wants to precede his @@ -554,14 +591,19 @@ % to \cs{@tabularcr}} % \changes{v4.1b}{1997/10/08}{Not \cs{@tabularcr} but % \cs{org@tabularcr}} +% \changes{v4.2b}{2021-02-14}{When the argument is empty the internal +% macro \cs{@tablehead} needs to be empty as well.} % \begin{macrocode} \newcommand\tablehead[1]{% - \gdef\@tablehead{% - \noalign{% - \global\let\@savcr=\\ - \global\let\\=\org@tabularcr}% - #1% - \noalign{\global\let\\=\@savcr}}} + \def\@ST@arg{#1}% + \ifx\@ST@arg\@empty\gdef\@tablehead{}\else + \gdef\@tablehead{% + \noalign{% + \global\let\@savcr=\\ + \global\let\\=\org@tabularcr}% + #1% + \noalign{\global\let\\=\@savcr}}% + \fi} \tablehead{} % \end{macrocode} % It's possible to specify a different tablehead for the first @@ -571,17 +613,22 @@ % document. % \changes{v4.1f}{2019/01/12}{\cs{\@table@first@head} needs the same % definition as \cs{\@tablehead} (found by FMi)} +% \changes{v4.2b}{2021-02-14}{When the argument is empty the internal +% macro \cs{@table@first@head} needs to be empty as well.} % \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 - }}} + \def\@ST@arg{#1}% + \ifx\@ST@arg\@empty\gdef\@table@first@head{}\else + \gdef\@table@first@head{% + \noalign{% + \global\let\@savcr=\\ + \global\let\\=\org@tabularcr}% + #1% + \noalign{% + \global\let\\=\@savcr + \global\let\@table@first@head\undefined + }}% + \fi} % \end{macrocode} % \end{macro} % \end{macro} @@ -598,14 +645,19 @@ % to \cs{@tabularcr}} % \changes{v4.1b}{1997/10/08}{Not \cs{@tabularcr} but % \cs{org@tabularcr}} +% \changes{v4.2b}{2021-02-14}{When the argument is empty the internal +% macro \cs{@tabletail} needs to be empty as well.} % \begin{macrocode} \newcommand\tabletail[1]{% - \gdef\@tabletail{% - \noalign{% - \global\let\@savcr=\\ - \global\let\\=\org@tabularcr}% - #1% - \noalign{\global\let\\=\@savcr}}} + \def\@ST@arg{#1}% + \ifx\@ST@arg\@empty\gdef\@tabletail{}\else + \gdef\@tabletail{% + \noalign{% + \global\let\@savcr=\\ + \global\let\\=\org@tabularcr}% + #1% + \noalign{\global\let\\=\@savcr}}% + \fi} \tabletail{} % \end{macrocode} % It's possible to specify a different tabletail for the last @@ -615,17 +667,22 @@ % document. % \changes{v4.1f}{2019/01/12}{\cs{\@table@last@tail} needs the same % definition as \cs{\@tabletail}} +% \changes{v4.2b}{2021-02-14}{When the argument is empty the internal +% macro \cs{@tabletail} needs to be empty as well.} % \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 - }}} + \def\@ST@arg{#1}% + \ifx\@ST@arg\@empty\gdef\@table@last@tail{}\else + \gdef\@table@last@tail{% + \noalign{% + \global\let\@savcr=\\ + \global\let\\=\org@tabularcr}% + #1% + \noalign{% + \global\let\\=\@savcr + \global\let\@table@last@tail\undefined + }}% + \fi} % \end{macrocode} % \end{macro} % \end{macro} @@ -660,7 +717,7 @@ % % \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 +% that command is looking for an optional argument and 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 @@ -752,25 +809,22 @@ % \changes{v4.0b}{1997/02/04}{Removed the use of \cs{ST@pboxcorr}, % correction seems to be no longer necessary} % -% \begin{macro}{\ST@lineht} +% \begin{macro}{\ST@rowht} % \begin{macro}{\ST@stretchht} % \changes{v4.0g}{1997/04/12}{Dimension register added} % \begin{macro}{\ST@prevht} % \changes{v4.0g}{1997/04/12}{Dimension register added} -% The estimated height of a normal line is stored in -% |\ST@lineht|. The dimension register |\ST@stretchht| is used to -% store the difference between the `normal' line height and the -% line height when |\arraystretch| has a non-standard value. This -% is used in the case where p-box entries are added to the -% tabular. The dimension register |\ST@prevht| is use to store the -% 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 +% The estimated height of a normal row is stored in +% |\ST@rowht|. The dimension register |\ST@stretchht| was used to +% store the difference between the `normal' row height and the +% row height when |\arraystretch| has a non-standard value. This +% was used in the case where p-box entries are added to the +% tabular. The dimension register |\ST@prevht| is used to store the +% height of the previous row, to use it as an estimate for the +% height of the next row. 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@rowht \newdimen\ST@prevht % \end{macrocode} % \end{macro} @@ -907,10 +961,12 @@ % \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{macro}{\ST@compute@rowht} +% \changes{v4.1g}{2020/02/02}{New macro \cs{ST@compute@rowht} to +% replace \cs{ST@estimate@rowht}} +% \changes{v4.2a}{2020-06-27}{Make sure that \cs{ST@rowht} is large +% enough to take subscripts and superscripts into account} +% The height of a row 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), @@ -919,34 +975,60 @@ % by |\arraystretch|. % \end{itemize} % \begin{macrocode} -\def\ST@compute@lineht{% - \ST@lineht=\ht\strutbox +\def\ST@compute@rowht{% +% \end{macrocode} +% Temporarily store a formula with superscript and subscript in a +% box in order to be able to measure its height and depth. +% \begin{macrocode} + \setbox\@tempboxa=\vbox{\@arrayparboxrestore $5^5_5$} +% \end{macrocode} +% Use the largest height of either |\@tempboxa| or |\strutbox|. +% \begin{macrocode} + \ifnum\ht\@tempboxa>\ht\strutbox + \ST@rowht=\ht\@tempboxa + \else + \ST@rowht=\ht\strutbox + \fi +% \end{macrocode} +% If the \textsf{array} pacakge is used we need to add the +% value of |\extrarowheight|. +% \begin{macrocode} \ifx\extrarowheight\undefined\else - \advance \ST@lineht by \extrarowheight + \advance \ST@rowht by \extrarowheight + \fi +% \end{macrocode} +% Also use the largest depth of either |\@tempboxa| or |\strutbox|. +% \begin{macrocode} + \ifnum\dp\@tempboxa>\dp\strutbox + \advance\ST@rowht \dp\@tempboxa + \else + \advance\ST@rowht \dp\strutbox \fi - \ST@lineht = \arraystretch\ST@lineht - \advance\ST@lineht \arraystretch\dp\strutbox - \ST@trace\tw@{Normal Line height: \the\ST@lineht}% +% \end{macrocode} +% And finally multiply by |\arraystretch|. +% \begin{macrocode} + \ST@rowht = \arraystretch\ST@rowht +% \end{macrocode} +% \begin{macrocode} + \ST@trace\tw@{Normal Row height: \the\ST@rowht}% } % \end{macrocode} % \end{macro} % -% \begin{macro}{\estimate@lineht} +% \begin{macro}{\ST@estimate@rowht} % 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}} -% This macro will be removed in a future release. +% \changes{v4.2a}{2020-06-27}{removed the computation of +% \cs{ST@stretchht} as it is no longer used} % \begin{macrocode} -\def\estimate@lineht{% - \ST@lineht=\arraystretch \baslineskp - \global\advance\ST@lineht by 1\p@ - \ST@stretchht\ST@lineht\advance\ST@stretchht-\baslineskp - \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}% +\def\ST@estimate@rowht{% + \ST@rowht=\arraystretch \baslineskp + \global\advance\ST@rowht by 1\p@ + \ST@trace\tw@{Average Row height: \the\ST@rowht}% } % \end{macrocode} % \end{macro} @@ -1071,23 +1153,23 @@ \ST@tailht=\ht\@tempboxa\advance\ST@tailht\dp\@tempboxa \fi % \end{macrocode} -% We add the average height of a line to this because when we +% We add the average height of a row to this because when we % decide to continue the tabular we need to have enough space left -% for one line and the tail. +% for one row \emph{and} the tail. % \begin{macrocode} - \advance\ST@tailht by \ST@lineht + \advance\ST@tailht by \ST@rowht \ST@trace\tw@{Height of tail: \the\ST@tailht}% \ST@trace\tw@{Maximum height of tabular: \the\ST@pageleft}% \@tempdima\ST@headht % \end{macrocode} % \changes{v4.0b}{1997/02/04}{Base the decision whether to start on a -% new page on the total of headheight, tailht and lineht} +% new page on the total of headheight, tailht and rowht} % Now we decide whether we can continue on the current page or % whether we need to start on a new page. We assume that the % minimum height of a tabular is the height of the head, the tail -% and one line of data. If that doesn't fit a new page is started. +% and one row of data. If that doesn't fit a new page is started. % \begin{macrocode} - \advance\@tempdima\ST@lineht + \advance\@tempdima\ST@rowht \advance\@tempdima\ST@tailht \ST@trace\tw@{Minimum height of tabular: \the\@tempdima}% \ifnum\@tempdima>\ST@pageleft @@ -1164,7 +1246,7 @@ \global\let\@oldcr=\\ % \end{macrocode} % Save the current value of |\baselineskip|, as we need it in the -% calculation of the average height of a line. +% calculation of the average height of a row. % \begin{macrocode} \def\baslineskp{\baselineskip}% % \end{macrocode} @@ -1174,9 +1256,9 @@ \ifx\undefined\@classix % \end{macrocode} % Save old |\@tabularcr| and insert the definition of +% |\ST@tabularcr|. % \changes{v4.1c}{1997/11/07}{For standard \LaTeX\ we need to change % \cs{@@startpbox}, \emph{not} \cs{@startpbox}} -% |\ST@tabularcr|. % \begin{macrocode} \let\org@tabularcr\@tabularcr \let\@tabularcr\ST@tabularcr @@ -1210,20 +1292,20 @@ \fi % \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 +% if it doesn't fit on the current page after all. Subsequent parts % can not be moved; therefor we will have to switch the definition -% of |\ST@skippart| around. +% of |\ST@skippage| around. % \changes{v4.0e}{1997/04/09}{Make sure that only the first part of a % supertabular can be moved to the next page.} % \begin{macrocode} \let\ST@skippage\ST@skipfirstpart % \end{macrocode} -% Now we can estimate the average line height and the height of the +% Now we can estimate the average row 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}} +% \changes{v4.1g}{2020/02/02}{Now call \cs{ST@calculate@rowht}} % \begin{macrocode} - \ST@compute@lineht + \ST@calculate@rowht \@calfirstpageht \noindent } @@ -1544,20 +1626,20 @@ % \begin{macrocode} \def\ST@cr{% \noalign{% - \ifnum\ST@pboxht<\ST@lineht + \ifnum\ST@pboxht<\ST@rowht % \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. Therefor we estimate the height of the line to be -% |\ST@lineht| in this case. +% If there is a non-empty row, but an empty parbox, then +% |\ST@pboxht| might be non-zero, but too small, thereby breaking +% the algorithm. Therefor we estimate the height of the row to be +% |\ST@rowht| in this case. % \begin{macrocode} - \global\advance\ST@pageleft -\ST@lineht + \global\advance\ST@pageleft -\ST@rowht % \end{macrocode} % And we store that fact in |\ST@prevht|. -% \changes{v4.0g}{1997/04/12}{store the height of the previous line in +% \changes{v4.0g}{1997/04/12}{store the height of the previous row in % \cs{ST@prevht}} % \begin{macrocode} - \global\ST@prevht\ST@lineht + \global\ST@prevht\ST@rowht \else % \end{macrocode} % When the parbox was not empty we take into account its height @@ -1605,11 +1687,11 @@ \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 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 +% a new page. To compute the amount of space needed we use the +% height of the previous row (|\ST@prevht|) as an estimation of +% the height of the next row. If we are processing a % \Lenv{mpsupertabular} we need to take the height of the footnotes -% into account. +% into account as well. % \changes{v4.0g}{1997/04/12}{Leave room for both \cs{ST@tailht} % \emph{and} \cs{ST@prevht}} % \changes{v4.1a}{1997/09/19}{Take care of space needed for @@ -1659,10 +1741,19 @@ % \begin{macrocode} \global\advance\ST@pageleft\pagetotal % \end{macrocode} -% Then we can set |\ST@pagesofar| to $0$ and start the new page. +% Then we can set |\ST@pagesofar| to $0$... % \begin{macrocode} \global\ST@pagesofar\z@ - \newpage +% \end{macrocode} +% ... and start the new page, but in this special case we need to +% trigger the output routine directly by issuing a |\penalty| +% rather than calling |\newpage| as that macro effectively issues a +% |\vskip-\maxdepth| which makes the first two rows of the tabular +% overlap. +% \changes{v4.2b}{2021-02-14}{Issue a \cs{penalty} instead of +% \cs{newpage} to trigger the output routine.} +% \begin{macrocode} + \penalty -\@M % \end{macrocode} % % Finally we make sure that this macro can only be executed once |