widetable (28jun19)

git-svn-id: svn://tug.org/texlive/trunk@51501 c570f23f-e606-0410-a88d-b1316a301751

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