summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/widetable
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-06-28 21:07:30 +0000
committerKarl Berry <karl@freefriends.org>2019-06-28 21:07:30 +0000
commit06d8049b6815d93618978b4b921f2dc85fb63498 (patch)
treec10c195ba515653622718295d7c281543bb700f1 /Master/texmf-dist/source/latex/widetable
parent6677e7d16babf1c0596fd30f9aeb6b13433725cd (diff)
widetable (28jun19)
git-svn-id: svn://tug.org/texlive/trunk@51501 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/widetable')
-rw-r--r--Master/texmf-dist/source/latex/widetable/widetable.dtx550
1 files changed, 213 insertions, 337 deletions
diff --git a/Master/texmf-dist/source/latex/widetable/widetable.dtx b/Master/texmf-dist/source/latex/widetable/widetable.dtx
index db9dfb15be9..d774e9a7e63 100644
--- a/Master/texmf-dist/source/latex/widetable/widetable.dtx
+++ b/Master/texmf-dist/source/latex/widetable/widetable.dtx
@@ -8,7 +8,7 @@
\preamble
______________________________________________________
The WIDETABLE bundle
- Copyright (C) 2009-2018 Claudio Beccari
+ Copyright (C) 2009-2019 Claudio Beccari
All rights reserved
License information appended
@@ -16,7 +16,7 @@
\endpreamble
\postamble
-Copyright 2009-2017 Claudio Beccari
+Copyright 2009-2019 Claudio Beccari
Distributable under the LaTeX Project Public License,
version 1.3c or higher (your choice). The latest version of
@@ -29,9 +29,8 @@ the manifest.txt file, and the derived files:
widetable.sty and widetable.pdf.
-By running pdflatex on widetable.dtx the user gets the sty
-file and the English documentation file in
-PDF format.
+By running pdflatex on widetable.dtx the user gets both
+the sty file and the English documentation PDF file.
\endpostamble
@@ -44,13 +43,13 @@ PDF format.
\endgroup
%</internal>
%
-% Copyright 2009--2018 Claudio Beccari
+% Copyright 2009--2019 Claudio Beccari
%
% This file is part of the widetable bundle
% -------------------------------------------
%
% It may be distributed and/or modified under the
-% conditions of the LaTeX Project Public License, either version 1.3c
+% 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
@@ -76,12 +75,13 @@ PDF format.
%<*driver>
\ProvidesFile{widetable.dtx}%
%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}[2016/01/01]
%<package>\ProvidesPackage{widetable}%
%<*package>
- [2018-12-14 v.1.5 Package for typesetting specified width tables]
+ [2019-06-25 v.2.0 Package for typesetting specified width tables]
%</package>
%<*driver>
-\documentclass{ltxdoc}\errorcontextlines=100
+\documentclass{ltxdoc}
\hfuzz 10pt
\def\prog#1{\textsf{\slshape#1}}
\usepackage{multicol}
@@ -101,13 +101,15 @@ PDF format.
\renewcommand\cs[1]{{\normalfont\ttfamily\char92#1}}
\newcommand\Benv[1]{\texttt{\char92begin\{#1\}}}
\newcommand\Eenv[1]{\texttt{\char92end\{#1\}}}
-\newcommand\eTeX{\raisebox{-0.5ex}{$\varepsilon$}\kern-0.1666em\TeX}
+\newcommand\eTeX{$\varepsilon$-\TeX}
+\renewcommand\prog[1]{\textsf{#1}}
+\newcommand\pack[1]{\texttt{\itshape#1}}
% end local definitions
\begin{document}
\makeatletter
\GetFileInfo{widetable.dtx}%
-\title{The \textsf{widetable} package}
-\date{Version number \fileversion; last revision \filedate.}
+\title{The \pack{widetable} package}
+\date{Version number \fileversion; last revised on \filedate.}
\author{Claudio Beccari\thanks{\texttt{claudio dot beccari at gmail dot com}}}
\maketitle
\begin{multicols}{2}
@@ -117,7 +119,7 @@ PDF format.
\end{document}
%</driver>
% \fi
-% \CheckSum{181}
+% \CheckSum{55}
% \begin{abstract}
% This package allows to typeset tables of specified width,
% provided they fit in one page. Instead of introducing an
@@ -147,48 +149,52 @@ PDF format.
% given in the file `manifest.txt'.
%
% The list of derived (unpacked) files belonging to the distribution
-% and covered by the LPPL is defined by the unpacking scripts (with
-% extension .ins) which are part of the distribution.
+% and covered by the LPPL is defined in the manifest.txt file.
%
%\section{Introduction}
% It is well known that when the standard environment
% |tabular*| is opened with a specified width, it is
% necessary to introduce in the delimiter declaration
-% |@{...}| of (possibly) the first cell of the model row
-% a declaration such as
+% |@{...}| of (possibly) as the first item of the column
+% descriptors argument something like
% \begin{verbatim}
% \extracolsep{\fill}
% \end{verbatim}
% in addition to other possible printable delimiters, such
% as vertical lines, and other fixed spacing commands. The
% effect is that the extra stretchable glue operates only
-% on the left of each cell \emph{after} (to the \emph{right}
+% on the left of each cell \emph{after} (i.e. to the \emph{right}
% of) the cell that received the declaration; the first cell
% will never get larger in spite of the presence of this glue.
%
-% Another package, |tabularX|, normally distributed by the
+% Another package, \pack{tabularX}, normally distributed by the
% \LaTeX\,3 Team with every version of the \TeX\ system
-% distribution, allows to create expandable cells,
-% provided they contain only text. These expandable cells
-% are identified with the column identifier |X|; this
+% distribution, allows to create expandable cells, provided they
+% contain only text and, possibly, in line math. These expandable
+% cells are identified with the column descriptor |X|; this
% identifier defines a paragraph-like cell, the width of
% which gets determined after some runs of the typesetter
% on the same source tabular material, so as to find out the
% correct width of the textual columns.
+%
+% Also \pack{tabu} can build tables of specified
+% width; but it has so many functionalities that it appears
+% to be oversized for a simple task such as the one performed
+% by \pack{widetable} and \pack{tabularx}.
%
% The approach here is a little bit different: the cell
% contents need not be textual and no cell width is determined
-% in one or more runs of the typesetter; instead the
+% in one or more runs of the typesetting program; instead the
% inter column glue is determined so as to fill every cell
% on both sides with the proper space. The macros contained
% in this package are insensitive to the particular kind
% of cell descriptors and to the presence of multiple
% |\multicolumn| commands. It proved to work properly also
% if the |array| package extensions are used.
-% Nevertheless if multiple |\multirow| commands in different
-% rows ``interlace'' the columns they work on, poor results
-% are obtained, and sometimes no result at all is obtained
-% except a warning message.
+% Nevertheless if multiple |\multicolumn| commands in different
+% rows “interlace” the columns they work on, poor results
+% are obtained, in the sense that the table is typeset the same
+% as with the environment |tabular|.
%
% On the other hand, as well as for |tabularX|, it needs to
% typeset the table three times; the first two times with
@@ -199,8 +205,8 @@ PDF format.
% value of |\tabcolsep|, and on the third run it eventually
% typesets the table with the specified width.
%
-% The time increase needed for these three table typesettings
-% is in general rather negligible, nevertheless if a specific
+% The typesetting time increase needed for these three table runs
+% in general is negligible, nevertheless if a specific
% document contained many dozens of such tables, the compilation
% time might become perceivable.
%
@@ -210,32 +216,33 @@ PDF format.
% therefore fractional division is not any more an issue as
% it was in previous versions of this package.
%
-% \section{Normal use of \texttt{widetable}}
-% This package issues an error message in case the
-% environment includes other unhidden environment; this is
-% explained in the Implementation section. In plain words,
-% if a |widetable| environment is nested into another one,
-% the inner environment must be “hidden” within a group
-% (a pair of braces).
-%
-% Here it is assumed that the user typesets the table to its
-% natural width with |tabular|; should it appear too small,
-% and should it be typeset at a larger width, for example for
-% filling the total |\linewidth| available at that specific point,
-% then and only then the user changes the |tabular| environment
-% to |widetable|. Should the initial table be moderately larger
-% than the |\linewidth|, then it might be shrunk to |\linewidth|
+% \section{Normal use of \pack{widetable}}
+% This package may issue an error message when the
+% environment includes other unhidden one; this is
+% explained in the Implementation section. In plain words,
+% if a |widetable| environment is nested into another |widetable|
+% one, the inner environment must be “hidden” within a group
+% (a couple of paired braces); this is not necessary with other
+% tabular-like environments.
+
+% Here it is assumed that the table is first typeset to its
+% natural width; should it appear too small, and should it be
+% typeset at a larger width, for example by filling the
+% total |\linewidth| available at that specific point, then
+% and only then the |tabular| environment is changed to
+% |widetable|. Should the initial table be moderately larger
+% than |\linewidth|, then it might be shrunk to |\linewidth|
% with |widetable|, provided there are enough columns, and
-% therefore delimiters, to be reduced in size. Of course it's
+% therefore column delimiters, to be reduced in size. Of course it's
% impossible to typeset any table with any negative value
% of |\tabcolsep|; or better, it is possible, but the result
% in general is very messy.
%
% In other words |widetable| should be used as a second resort,
-% so as to correct some typesetting features not considered
+% so as to correct some typesetting features not considered
% aesthetically acceptable.
%
-% The syntax for tusing the environment |widetable| is the
+% The syntax for using the environment |widetable| is the
% same as that of the |tabular*| environment; the only difference
% is the name. Therefore one has to specify:
% \begin{flushleft}\obeylines%
@@ -250,12 +257,12 @@ PDF format.
%
% \section{The method}
% The principle on which this little package is based is the
-% following; suppose a certain table is typeset with an inter
-% column glue $t_0=0$ and that its width turns out to be $l_0$;
+% following; suppose a certain table is typeset with an inter
+% column glue $t_0=0\mathrm{\,pt}$ and that its width turns out to be $l_0$;
% suppose the same tabular material is typeset again with an
-% inter column glue $t_1 >0$ so that the table table gets as
+% inter column glue $t_1 >0\mathrm{\,pt}$ so that the table gets as
% large as $l_1>l_0$. Then, if the table has to be as wide as
-% $l$ the inter column glue must equal the value
+% $l$ the inter column glue $t$ should be
% \[
% t = \frac{l - l_0}{l_1 - l_0}\cdot t_1
% \]
@@ -263,30 +270,43 @@ PDF format.
% Therefore we need to run the typesetting of the same tabular
% material with the two values of the inter column glue set
% to zero and to $t_1$, respectively, so as to find the widths
-% $l_0$ and $l_1$. Afterwards it has to determine the correct
-% final value $t$, and typeset once again the same tabular
+% $l_0$ and $l_1$. Afterwards we have to determine the correct
+% final value $t$, and typeset once again the same tabular
% material for the last time.
%
% Of course the first two runs must put their results into
-% suitable boxes so as to avoid shipping them to the output
-% file, while at the same time allowing to record the width
+% suitable boxes so as to avoid outputting them into the output
+% file, while at the same time allowing to record the width
% of the enclosing boxes.
%
-% \section{The long division algorithm}
-% In previous versions of this package we provided a fractional length
-% division macro to perform such computations; the subtractions
-% and multiplication could be done with regular primitive
-% commands of the \TeX\ engine; but the fractional division
-% required a special long division algorithm.
-%
-% With the \eTeX\ extensions to the typesetting engine |pdftex|
-% (native in |xetex| and |luatex|, therefore available in
-% |XeLaTeX| and |LuaLaTeX|) there is no need to create any
-% long division macro, because such computation is already
-% provided in those engines as a primitive command.
+% \section{The \pack{xparse} package}
+% The previous version of this package used the \pack{xparse}
+% package functionalitIes; but this latter package evolves and now
+% it is possible to “save” the body of the table as an argument
+% to the opening commands, therefore now is much simpler to
+% use the same table body several times. Of course this body
+% is saved in internal memory areas, but this task is
+% implemented by the internal macros written in the L3
+% \LaTeX\ language. The advantage of using the \pack{xparse}
+% package consists in a much shorter code and easier to read
+% and maintain. The number of macros for this package is
+% reduced by a factor of about four, compared to the previous
+% version of this package.
%
% \section{Using the \eTeX\ facilities}
-% In facts the \eTeX\ extension provides the scaling operation:
+% The L3 language and its libraries now offer the user some \LaTeX\
+% interfaces to its internal macros to the point of executing also
+% floating point operations that span a wide range; the suitable
+% package would be \pack{xfp}. Nevertheless it appears sort of
+% overdone for the simple computations needed here..
+%
+% At the same time the \eTeX\ extended functionalities are now
+% part of all the interpreters of the \LaTeX\ language,
+% \prog{pdftex}, \prog{luatex}, and \prog{xetex}; this renders
+% this package usable for all main typesetting programs,
+% \prog{pdflatex}, \prog{lualatex}, and \prog{xelatex}.
+%
+% In facts such \eTeX\ extensions provide also a scaling operation:
% given the length $L_1$ and two homogeneous quantities $X_1$
% and $X_2$ (where such quantities may be either two integer
% numbers, or two dimensions), such scaling operation scales
@@ -295,26 +315,24 @@ PDF format.
% L_2 = L_1\cdot \frac{X_2}{X_1}
%\]
% The intermediate results are actually done with integer
-% arithmetics (internally length are coded as integer numbers of
+% arithmetics (internally lengths are coded as an integer number of
% scaled points) but are done in double words so as to avoid
-% underflow and overflows almost always. Some unusual situations
+% underflows and overflows almost always. Some unusual situations
% might exist where underflows or overflows may occur, but
% they must be very unusual, and very unlikely to happen for
-% the calculations of this package. In case of overflow a
-% |\maxdimen| value is automatically obtained and computations
-% go on as possible, may be giving rise to other errors or
-% warnings, for example overfull lines.
+% the calculations of this package. This would happen if for any
+% reason no inter column glue is available; we have difficulties
+% imagining such a table and cannot make even a silly example.
%
% The use of the \eTeX\ extensions implies that this package
% works correctly only with modern engines and kernel formats.
-% This is why the package starts with a statement where the
-% kernel format is required to be quite recent.
%
% \section{Usage}
% As explained above, the normal usage of |widetable| requires the same
% syntax as that of |tabular*| except that no explicit stretchable
% glue has to be inserted in the column separators as it is necessary
-% to do with |tabular*|. Examine the table shown in table~\ref{tab:tab} that is typeset at its natural width.
+% to do with |tabular*|. Examine the table shown in table~\ref{tab:tab}
+% that is typeset at its natural width.
% \begin{table}\centering
% \begin{tabular}{llr>{\raggedright}p{0.29\textwidth}}
% \toprule
@@ -387,13 +405,16 @@ PDF format.
% \toprule
% Name & role & age & activity \tabularnewline
% \midrule
-% William John & father & 45 & employee \tabularnewline
-% Mary Elisabeth & mother & 42 & elementary school
+% William John & father & 45 & employee \tabularnewline
+% Mary Elisabeth & mother & 42 & elementary school
% teacher\tabularnewline
-% Joan Laura & daughter & 14 & junior high school
+% Joan Laura & daughter & 14 & junior high school
% student\tabularnewline
-% Jack Johnathan & son & 8 & elementary school pupil
-% \tabularnewline
+% Jack Johnathan & son & 8 & elementary school pupil\tabularnewline
+%\begin{tabular}{@{}ll@{}}
+%Pippo & Pluto\\
+%Paperino & Topolino
+%\end{tabular} & \relax & 4 & Walt Disney\tabularnewline
% \bottomrule
% \end{widetable}
% \caption{A table typeset with \texttt{widetable} where the total width
@@ -403,10 +424,10 @@ PDF format.
% In table~\ref{tab:tabwide} the column specifications are the same
% as those used in the code of table~\ref{tab:tab}, but only the
% spaces separating the columns have been modified, not the column
-% types and widths. Of course one my object that the table spaces
+% types and widths. Of course one may object that the table spaces
% are too wide and table~\ref{tab:tab} looks better. But if, for
-% example, in a certain document tables must span the whole width,
-% the the solution given in table~\ref{tab:tabwide} is the only one
+% example, in a certain document all tables must span the whole width,
+% the solution given in table~\ref{tab:tabwide} is the only one
% acceptable among the four shown in these examples. It's up to the
% user to chose among these four solutions in terms of the actual
% table contents and the stylistic constraints the document must
@@ -422,25 +443,19 @@ PDF format.
% issues that may alter its smooth working.
%
% One such issue takes place when the specified table width
-% is shorter the the natural width. In this case the table is
+% is shorter than the natural width. In this case the table is
% typeset as in table~\ref{tab:tab} at its natural width, but
-% a warning is issued that explains why: it looks like this
+% a warning is issued that explains why: the warning looks like this
%\begin{verbatim}
-%Package widetable Warning: The natural width 225.19809pt of the tabular
-%(widetable) material is larger than the specified width 177.5pt.
-%
+%Package widetable Warning: The minimum width of the tabular material
+%(widetable) amounts to 225.19809pt, and is larger
+%(widetable) than the required width of 177.5pt
%(widetable)
%(widetable) The table is typeset with the default
-%(widetable) column spacing on input line 392.
+%(widetable) column spacing on input line 415.
%\end{verbatim}
% As usual the warning is contained into the |.aux| file.
%
-% When a nested tabular environment is contained in |widetable|
-% is not hidden within a group of paired braces, the inner
-% environment is substituted with a framed box that contains
-% a message, and a more descriptive warning is included into
-% the |.aux| file.
-%
% When some adjacent cells are grouped with the |\multicolumn|
% command; the table might come out of the correct specified width
% even if the spanned cells (in different rows) do not belong
@@ -455,10 +470,6 @@ PDF format.
% this package macros and for his wise suggestions about
% the correct programming style. If some glitch still
% remains in the programming style, that is just my fault.
-% Deep thanks also go to Frank Mittelbach who spotted an error
-% and suggested some useful modifications; this new version
-% of the package and its documentation comes from Frank's
-% suggestions.
%
% \StopEventually{}
%
@@ -467,266 +478,136 @@ PDF format.
%\fi
% \section{Implementation}
%
-% The package is already identified by the same statement used
-% for this |.dtx| file. The necessary \LaTeX\ kernel date must
-% be specified in order to be sure that the \eTeX\ extensions
-% are available.
-% \begin{macrocode}
-\NeedsTeXFormat{LaTeX2e}[2018/01/01]
-% \end{macrocode}
-%
-% We suppose that the user might wish to use also the extensions
-% of the |array| package; in order to avoid possible option
-% clashes we defer loading this |array| package to the begin
-% document statement and we check if the user has already loaded
-% that package so as not to reload it. This task could be left
-% to the internal workings of the |\RequirePackage| macro, but
-% we prefer to do our checks with a more direct statement.
-% By so doing, this package already has available all the
-% facilities of the |array| package, in particular the
-% |\newcolumntype| command, the column types |m| and |b|,
-% and the various special codes to add commands at the beginning
-% and the end of all the cells of a given column.
-% \begin{macrocode}
-\AtBeginDocument{%
- \@ifpackageloaded{array}{}{\RequirePackage{array}}%
- }
-% \end{macrocode}
-%
-% Next we define a certain number of \TeX\ dimensions and counters;
-% these dimension and counter registers might be selected among the extra
-% registers available with the \eTeX\ extensions. In facts such extensions
-% allow to use registers identified by numbers higher than 255,
-% a limit of the good-old-\TeX; Enrico Gregorio in 2009 suggested
-% to avoid such kind of usage; heremarked that not all users
-% upgrade so often their \TeX\ system; OK, may be they have their
-% good reasons for not upgrading, and they have available the previous
-% versions of this package; may be they use a basic installation
-% of the \TeX\ system and add new packages when they need to use
-% them. Therefore we follow Enrico's suggestion and use some of the scratch registers always available to programmers.
+% We identify the package and the necessary \LaTeX\ kernel
% \begin{macrocode}
-\dimendef\wt@Numer=2
-\dimendef\wt@Denom=4
-\countdef\wt@Num=2
-\countdef\wt@Den=4
+\ProvidesPackage{widetable}[2019-06-24 v.1.5 A simpler way to produce
+ tables of specified width]
% \end{macrocode}
+%
%
-% We require the |xparse| package in order to define the
-% environment |widetable| with its extended commands.
+% We require the |xparse| package in order to define the % environment
+% |widetable| with its extended commands. Tis package version should be
+% younger the the specified date contained in the optional argument.
+% If it is not, a warning is issued; but expect errors. It is a warning
+% that should urge the user to upgrade his/her \TeX\ system installation.
% \begin{macrocode}
-\RequirePackage{xparse}
-% \end{macrocode}
-%
-% We define a local scaling macro |\WT@scale| to execute the
-% scaling operation that is of interest to the |widetable|
-% package. We provide some tests so as to set some values
-% for very unusual situations. The four arguments are as such:
-% |#1|: length to be scaled; |#2|: numerator of the scaling
-% ratio; |#3|: denominator of the scaling ratio; |#4|: scaled
-% length.
-% \begin{macrocode}
-\newcommand\WT@scale[4]{\begingroup
-\wt@Num #2\relax \wt@Den #3\relax
-\ifnum#3=\z@
- \@tempdima\ifnum#2<0-\fi\maxdimen
-\else
- \@tempdima\dimexpr#1*#2/#3\relax
-\fi
-\edef\x{\noexpand\endgroup\noexpand\setlength{#4}{\the\@tempdima}}%
-\x}
+\RequirePackage{xparse}[2019-05-01]
% \end{macrocode}
%
+%The special environment opening macro requires the following syntax:
+%\begin{flushleft}\obeylines
+%\Benv{widetable}\marg{width}\oarg{alignment}\marg{column descriptors}
+%\meta{table body}
+%\Eenv{widetable}
+%\end{flushleft}
% At this point it will be the |widetable| environment
-% responsibility to call |\WT@scale| with the proper arguments.
+% responsibility to call |\WT@scale| with the proper arguments
%
-% Now we define the dimension register that is to contain the
-% desired table width.
-% \begin{macrocode}
-\newdimen\wt@width
-% \end{macrocode}
-%
% We further define the start of the tabular typesetting
-% that will be useful in a while. Actually the table preamble
-% is being saved into a macro, so that when the \meta{width}
-% and the \meta{column descriptors} are given to the opening
-% environment statement, these saved quantities can be used
-% again and again.
+% that will be useful in a while. Actually the table parameters
+% are usable also in the closing part of the environment (thanks
+% to \pack{xparse}), so that when the \meta{width} and the
+% \meta{column descriptors} are given to the opening environment
+% statement, these parameters can be used again and again.
+%
+% Actually the |widetable| environment can contain other
+% environments, even another |widetable| environment, but
+% the external one should not be upset by the internal ones.
+% In order to achieve this result, it is necessary that
+% embedded environments are hidden within a group delimited by
+% a pair of matching braces; this is compulsory for an
+% embedded |widetable| environment, while it is not strictly
+% required for differently named environments.
%
-% A new boolean, |wt@scartare|, is defined; this boolean
-% variable will be set true in order to detect if the
-% table body is is not well formed, with |\begin| and |\end|
-% statements that don't match, and the like; actually the
-% |widetable| environment can contain other environment,
-% even another |widetable| environment, but the external
-% one should not be upset by the internal ones. In order
-% to achieve this result, it is necessary that any
-% embedded environment is hidden int a group delimited by
-% a pair of matching braces.
-% \begin{macrocode}
-\newif\ifwt@scartare\wt@scartarefalse
-
-% \end{macrocode}
-%
-% The environment opening as well as the environment closing
-% are defined by means of low level commands. Due to the syntax
-% of the opening command that requires two compulsory
-% arguments, these are saved in the recently defined
-% dimension register and to a macro respectively; another
-% macro |\wt@getTable| is used to get the body of the table;
-% the |\end{widetable}| statement represents the ending
-% delimiter of the table contents.
+% The environment opening and closing actions
+% are defined by means of low level commands.
%
+% The opening part of the environment reduces to nothing else
+% but the background L3 functions executed by the \cs{begin}
+% command implementation and the correct parsing of the list
+% of argument descriptors
% \begin{macrocode}
-\DeclareDocumentCommand\widetable{m O{c} m}
-{% OPENING WIDETABLE
- \def\@tempC{widetable}%
- \setlength{\wt@width}{#1}%
- \def\wt@preamble{#3}%
- \def\wt@starttabular{\tabular[#2]{#3}}%
- \wt@getTable}%
+\DeclareDocumentEnvironment{widetable}{m O{c} m +b}
+{% OPENING WIDETABLE COMMANDS
+}%
% \end{macrocode}
-%
-% The closing statement will actually do the greatest part of
-% the job. First of all if the above mentioned boolean variable
-% is true, it skips everything and it does not set any table;
-% but if the boolean variable is false, the table body is well
-% formed and it can do the job as described in the previous
-% sections. It first sets |\tabcolsep| to zero and sets the
-% resulting table in box zero; the lower level |tabular| with
-% the information saved into |\wt@startabular| and the body of
-% the table contained into the token register zero.
+% These arguments have the following meanings.
+%\begin{description}
+%\item[Argument number one] It is mandatory and represents the desired
+% table width.
+%\item[Argument number two] It is optional. With a default value of
+% \texttt{c} the table is aligned with respect to its math axis;
+% the other possible values are \texttt{t} for top alignment, and
+% \texttt{b} for bottom alignment; they are the same values used
+% for the \LaTeX-kernel tabular environments.
+%\item[Argument number three] It is mandatory; it should contain all the
+% column descriptors and inter-column separators, possibly in
+% the extended forms provided by the \pack{array} package.
+%\item[Argument number four] It represents an \pack{xparse} functionality
+% by which the whole environment body is usable as\texttt{\#4}.
+%\end{description}
+%
+% The closing statement will actually do the whole job. It first sets
+% |\tabcolsep| to zero and typesets the resulting table into box zero;
+% It uses, with parameter \texttt{\#4}, the table body collected with
+% the argument descriptor \texttt{b} of the opening command.
%
-% Then it sets |\tabcolsep| to 1\,cm (arbitrarily chosen) and
+% Then it sets |\tabcolsep| to 6\,pt (the default value) and
% typesets again the table into box two. The width of box zero
% is $l_0$ and that of box two is $l_1$; these are the lengths
% needed by the equation that evaluates the final typesetting
-% intercolumn spacing.
-% The arbitrary constant of 1\,cm is $t_1$, and the specified
-% width $l$ is the dimension saved into |\wt@width|. The
-% subtractions are operated directly on the dimension
-% registers |\wt@width| (the numerator), and on the auxiliary
-% register |\@tempdimenb|; the |\WT@scale| command is executed
-% in order to get the scaling ratio and the final definitive
-% value of |\tabcolsep| is eventually computed.
-% The table is finally typeset without using boxes, while the
-% contents of box zero and two are restored upon exiting the
-% environment to any value they might have contained before
+% inter column spacing.
+%
+% The arbitrary constant of 6\,pt is $t_1$, and the specified
+% width $l$ (parameter \texttt{\#1}) are used to compute the
+% new value of |\tabcolsep|. The subtractions are computed
+% directly on the dimensions and passed to a |\dimexpr| expression
+% so as to determine the new |\tabcolsep| value.
+%
+% The table is eventually typeset without using boxes, while the
+% contents of box zero and box two, upon exiting the environment,
+% are restored to any value they might have contained before
% entering |widetable|.
% \begin{macrocode}
-\def\endwidetable{% CLOSING WIDETABLE
- \ifwt@scartare
- \noindent\null
- \else
+{% CLOSING WIDETABLE
+ \dimen0=#1 % required width
\tabcolsep=\z@
- \setbox\z@=\hbox{\wt@starttabular\the\toks@\endtabular}%
+ \setbox\z@=\hbox{\tabular{#3}#4\endtabular}%
\tabcolsep=6pt\relax
- \setbox\tw@=\hbox{\wt@starttabular\the\toks@\endtabular}%
- \ifdim\wt@width<\wd\z@
- \@tempdimb=\dimexpr\wd\tw@-\wd\z@\relax
- \PackageWarning{widetable}{%
- The natural width \the\wd\z@ \space of the tabular\MessageBreak
- material is larger than the specified width
- \the\wt@width.\MessageBreak\MessageBreak
- The table is typeset with the default\MessageBreak
- column spacing}%
+ \setbox\tw@=\hbox{\tabular{#3}#4\endtabular}%
+ \ifdim\dimen0>\wd\z@
+ \tabcolsep=\dimexpr \tabcolsep*(\dimen0-\wd\z@)/(\wd\tw@-\wd\z@)\relax
\else
- \@tempdimb=\dimexpr\wt@width-\wd\z@\relax
+ \ifdim\dimen0<\wd\z@
+ \PackageWarning{widetable}{%
+ The minimum width of the tabular material\MessageBreak
+ amounts to \the\wd\z@, and is larger\MessageBreak
+ than the required width of \the\dimen0\MessageBreak
+ \MessageBreak
+ The table is typeset with the default\MessageBreak
+ column spacing}%
+ \fi
\fi
- \@tempdimc=\dimexpr\wd\tw@-\wd\z@\relax
- \WT@scale{\tabcolsep}{\@tempdimb}{\@tempdimc}{\tabcolsep}\relax
- \wt@starttabular\the\toks@\endtabular
- \fi
+ \tabular[#2]{#3}#4\endtabular
\ignorespacesafterend
}
-
-% \end{macrocode}
-%
-% Of course other actions must be performed before executing
-% the closing environment statement. We need a macro
-% |wt@finetabella| that is equivalent to the ending environment
-% statement.
-% \begin{macrocode}
-\def\wt@finetabella{\end{widetable}}%
-
% \end{macrocode}
+% Notice the test and the warning: |widetable| modifies the table
+% only if its width, typeset with |\tabcolsep| equal to zero, is
+% smaller than the requested width; otherwise it typesets the
+% table with the default inter column glue. The warning message
+% is produced only if the requested width is smaller the minimum
+% width.
%
-% We finally can define the most important macro that gets
-% the table body; it requires two delimited arguments:
-% in |#1| the table body and, after the |\end| command,
-% the closing environment name will be set in |#2|.
-% The environment name is assigned to the macro |\@tempB|,
-% which is checked against the correct name |widetable|
-% saved in macro |\@tempC| by the opening command. If the
-% names match, then the table body is assigned to the token
-% register zero, to be used later on by the typesetting macros.
-% But if the names don't match, then something went wrong
-% and a package message is issued to explain what happened
-% and how the program will manage the situation.
-%
-% Specifically the names may not match if a cell contained
-% another environment and its whole |\begin{...}...\end{...}|
-% was not closed within a pair of matched braces. If an
-% enclosed environment is hidden within a group, the delimited
-% argument macro |\wt@getTable| will ignore such embedded
-% environment, otherwise it will get a non matching name
-% and messy things might happen. Besides warning about this
-% fact, the body of the table, at least what has been read
-% by the macro, will be discarded and substituted with a box
-% containing a message; therefore a table will be typeset,
-% but not the desired one. The remaining part of the body
-% remains in the input stream and might cause, presumably,
-% strange errors, such as |&| characters used outside a
-% tabular or array environment. We must take care of this
-% so that the typesetting procedure does not crash.
-% \begin{macrocode}
-\def\wt@getTable#1\end#2{\def\@tempB{#2}%
- \ifx\@tempB\@tempC
- \toks@={#1}%
- \expandafter\wt@finetabella
- \else
- \PackageWarning{widetable}{%
- The table contains environment `\@tempB' %
- \MessageBreak
- not enclosed in braces. This is expressly forbidden!%
- \MessageBreak
- The table is not typeset and is substituted%
- \MessageBreak
- with a framed box}%
- \advance\wt@width-2\fboxsep
- \noindent\fbox{\parbox{\wt@width}{The table was not typeset
- because it contains a visible \texttt{\char`\\end} in one
- or more cells.}}\par
- \expandafter\wt@finishTable
- \fi
-}
-
-% \end{macrocode}
-%
-% In order to avoid a complete mess, we have to iteratively
-% gobble the rest of the input stream until a valid
-% |\end{widetable}| is encountered; actually the following
-% macro will do a nice job in general, but it is not
-% infallible if the input stream is really composed in a very
-% bad way. In facts it calls itself again and again, always
-% gobbling it arguments, until a valid terminating environment
-% name matches the name |widetable|.
-% \begin{macrocode}
-\def\wt@finishTable#1\end#2{%
- \def\@tempB{#2}%
- \ifx\@tempB\@tempC
- \wt@scartaretrue\expandafter\wt@finetabella
- \else
- \expandafter\wt@finishTable
- \fi
-}
-% \end{macrocode}
% \section{Conclusion}
-% Tables should always have their natural width, but\dots\
-% The default value of|\tabcolsep| is fixed by the document
+% Tables should always have their standard inter column spaces, but\dots\
+% The default value of |\tabcolsep| is fixed by the document
% class, it is not prescribed by a supreme law: therefore
% what does it mean ``natural width''. Probably the one
% determined by the class default value of |\tabcolsep|
-% so all tables have the same general look.
+% so all tables have the same general look. But here we
+% used the phrase “natural width” as the table width when the
+% inter column glue is set to zero
%
% Nevertheless sometimes a table is slightly wider than
% the current measure; why not shrink the table by shrinking
@@ -735,7 +616,7 @@ PDF format.
% inter column spaces are shrunk, not the whole table, fonts,
% drawings, and figures included, a result easily obtainable
% with a |\resizebox| command available through the
-% \textsf{graphicx.sty} package. Nobody forbids to follow
+% \pack{graphicx.sty} package. Nobody forbids to follow
% this technique, of course, but the |widetable| route might
% yield a better result.
%
@@ -745,11 +626,6 @@ PDF format.
% solution in order to avoid a multitude of slightly
% different indents or left margins.
%
-% This package might be useful also for copying some macros
-% so as to avoid some programming in other packages; this
-% use is certainly permitted by the LaTeX Project
-% Public License, which sets the observance of very light
-% obligations.
% \begin{macrocode}
\endinput
@@ -759,4 +635,4 @@ PDF format.
%\fi
%
% \Finale
-% \endinput
+% ^^A\endinput