summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/widetable
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/widetable
Initial commit
Diffstat (limited to 'macros/latex/contrib/widetable')
-rw-r--r--macros/latex/contrib/widetable/README17
-rw-r--r--macros/latex/contrib/widetable/manifest.txt36
-rw-r--r--macros/latex/contrib/widetable/widetable.dtx638
-rw-r--r--macros/latex/contrib/widetable/widetable.pdfbin0 -> 413519 bytes
4 files changed, 691 insertions, 0 deletions
diff --git a/macros/latex/contrib/widetable/README b/macros/latex/contrib/widetable/README
new file mode 100644
index 0000000000..7c998b914e
--- /dev/null
+++ b/macros/latex/contrib/widetable/README
@@ -0,0 +1,17 @@
+Package widetable version 2.x dated 2019
+
+This small package is intended to be a second resource when typesetting
+tables that would look a little better if they were set with a specified width.
+It differs from tabularX since here all cells are widened by working on the
+inter column glue, not on the measure of certain specified textual cells as
+it is done with tabularX.
+
+
+ This work may be distributed and/or modified under the
+ 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
+ and version 1.3 or later is part of all distributions of LaTeX
+ version 2003/12/01 or later.
+
diff --git a/macros/latex/contrib/widetable/manifest.txt b/macros/latex/contrib/widetable/manifest.txt
new file mode 100644
index 0000000000..a31d8794ee
--- /dev/null
+++ b/macros/latex/contrib/widetable/manifest.txt
@@ -0,0 +1,36 @@
+Package widetable, version 2.x dated 2019
+
+This small package is intended to be a second resource when typesetting
+tables that would look a little better if they were set with a specified width.
+It differs from tabularX since here all cells are widened by working on the
+inter column glue, not on the measure of certain specified textual cells as
+it is done with tabularX. Computations may be executed by means of the e-TeX
+extensions if they are available.
+
+
+ This work may be distributed and/or modified under the
+ 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
+ and version 1.3 or later is part of all distributions of LaTeX
+ version 2003/12/01 or later.
+
+ This work has the LPPL maintenance status "maintained".
+
+ The Current Maintainer of this work is Claudio Beccari
+
+ The list of all files belonging to the distribution is
+ given in this file `manifest.txt'.
+
+ The list of derived (unpacked) files belonging to the distribution
+ and covered by LPPL is defined by the unpacking scripts (with
+ extension .ins) which are part of the distribution.
+
+The main file of this work is
+ widteable.dtx (autoextracting .dtx file)
+The derived files are
+ widetable.pdf (obtained by pdflatexing widetale.dtx)
+ widetable.sty (osame as above)
+
+Claudio Beccari \ No newline at end of file
diff --git a/macros/latex/contrib/widetable/widetable.dtx b/macros/latex/contrib/widetable/widetable.dtx
new file mode 100644
index 0000000000..d774e9a7e6
--- /dev/null
+++ b/macros/latex/contrib/widetable/widetable.dtx
@@ -0,0 +1,638 @@
+% \iffalse meta-comment
+%<*internal>
+\begingroup
+\input docstrip.tex
+\keepsilent
+
+
+\preamble
+ ______________________________________________________
+ The WIDETABLE bundle
+ Copyright (C) 2009-2019 Claudio Beccari
+ All rights reserved
+
+ License information appended
+
+\endpreamble
+\postamble
+
+Copyright 2009-2019 Claudio Beccari
+
+Distributable under the LaTeX Project Public License,
+version 1.3c or higher (your choice). The latest version of
+this license is at: http://www.latex-project.org/lppl.txt
+
+This work is "author-maintained"
+
+This work consists of this file widetable.dtx, a README file
+the manifest.txt file, and the derived files:
+ widetable.sty and widetable.pdf.
+
+
+By running pdflatex on widetable.dtx the user gets both
+the sty file and the English documentation PDF file.
+
+\endpostamble
+
+\askforoverwritefalse
+
+\generate{\file{widetable.sty}{\from{widetable.dtx}{package}}}
+
+\def\tmpa{plain}
+\ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
+\endgroup
+%</internal>
+%
+% 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.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
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% This file has the LPPL maintenance status "author-maintained".
+%
+% The list of all files belonging to the widetable bundle is
+% given in the file `manifest.txt'.
+%
+% The set of derived (unpacked) files belonging to the
+% distribution and covered by LPPL is created by the self
+% unpacking file widetable.dtx
+% which is the principal part of the distribution.
+%
+% \fi
+
+
+
+
+% \iffalse
+%<*driver>
+\ProvidesFile{widetable.dtx}%
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}[2016/01/01]
+%<package>\ProvidesPackage{widetable}%
+%<*package>
+ [2019-06-25 v.2.0 Package for typesetting specified width tables]
+%</package>
+%<*driver>
+\documentclass{ltxdoc}
+\hfuzz 10pt
+\def\prog#1{\textsf{\slshape#1}}
+\usepackage{multicol}
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{textcomp}
+\usepackage{lmodern}
+\usepackage[italian,english]{babel}
+\usepackage{widetable,tabularx, booktabs,ragged2e}
+% local definitions
+\let\originalmeta\meta
+\renewcommand\meta[1]{{\normalfont\originalmeta{#1}}}
+\renewcommand\marg[1]{\texttt{\{\meta{#1}\}}}
+\newcommand\Marg[1]{\texttt{\{#1\}}}
+\newcommand\opz[1]{\texttt{[\meta{#1}]}}
+\newcommand\Opz[1]{\texttt{[#1]}}
+\renewcommand\cs[1]{{\normalfont\ttfamily\char92#1}}
+\newcommand\Benv[1]{\texttt{\char92begin\{#1\}}}
+\newcommand\Eenv[1]{\texttt{\char92end\{#1\}}}
+\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 \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}
+ \tableofcontents
+ \end{multicols}
+ \DocInput{widetable.dtx}
+\end{document}
+%</driver>
+% \fi
+% \CheckSum{55}
+% \begin{abstract}
+% This package allows to typeset tables of specified width,
+% provided they fit in one page. Instead of introducing an
+% infinite stretching glue, which has an unsymmetrical effect
+% in standard \LaTeX, here the |\tabcolsep| dimension is
+% computed so as to have the table come out with the proper
+% width.
+% \end{abstract}
+%
+% \section{Legalese}
+%
+% This file is part of the |widetable| package.
+%
+% This work may be distributed and/or modified under the
+% 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
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2003/12/01 or later.
+%
+% This work has the LPPL maintenance status ``maintained''.
+%
+% The Current Maintainer of this work is Claudio Beccari
+%
+% The list of all files belonging to the distribution is
+% given in the file `manifest.txt'.
+%
+% The list of derived (unpacked) files belonging to 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) 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} (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, \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 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 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 |\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
+% standard values for the inter column glue |\tabcolsep|, in
+% order to find the exact parameters of the linear dependence
+% of the table width from the value of that glue; then executes
+% some computations so as to extrapolate the final correct
+% value of |\tabcolsep|, and on the third run it eventually
+% typesets the table with the specified width.
+%
+% 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.
+%
+% It might be noticed that in order to perform the necessary
+% computations a fractional division algorithm must be used;
+% since 2009 any \TeX\ installation uses the \eTeX\ extensions;
+% therefore fractional division is not any more an issue as
+% it was in previous versions of this package.
+%
+% \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 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
+% aesthetically acceptable.
+%
+% 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%
+% \Benv{widetable}\marg{width}\opz{alignment}\marg{column descriptors}
+% \meta{row of cells}\cs{\textbackslash}
+% \meta{row of cells}\cs{\textbackslash}
+% \texttt{...}
+% \meta{row of cells}\cs{\textbackslash}
+% \meta{row of cells}\cs{\textbackslash}
+% \Eenv{widetable}
+% \end{flushleft}
+%
+% \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\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\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 $t$ should be
+% \[
+% t = \frac{l - l_0}{l_1 - l_0}\cdot t_1
+% \]
+%
+% 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 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 outputting them into the output
+% file, while at the same time allowing to record the width
+% of the enclosing boxes.
+%
+% \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}
+% 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
+% $L_1$ to $L_2$ by computing
+%\[
+% L_2 = L_1\cdot \frac{X_2}{X_1}
+%\]
+% The intermediate results are actually done with integer
+% arithmetics (internally lengths are coded as an integer number of
+% scaled points) but are done in double words so as to avoid
+% 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. 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.
+%
+% \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.
+% \begin{table}\centering
+% \begin{tabular}{llr>{\raggedright}p{0.29\textwidth}}
+% \toprule
+% Name & role & age & activity \tabularnewline
+% \midrule
+% William John & father & 45 & employee \tabularnewline
+% Mary Elisabeth & mother & 42 & elementary school
+% teacher\tabularnewline
+% Joan Laura & daughter & 14 & junior high school
+% student\tabularnewline
+% Jack Johnathan & son & 8 & elementary school pupil
+% \tabularnewline
+% \bottomrule
+% \end{tabular}
+% \caption{A regular table typeset with \texttt{tabular} and its width is its natural one}\label{tab:tab}
+% \end{table}
+%
+% The same table can be built with |tabular*| as in table~\ref{tab:tab*}.
+% \begin{table}\centering
+% \begin{tabular*}{\textwidth}%
+% {@{\hskip\tabcolsep\extracolsep{\fill}}llr>{\raggedright}p{0.29\textwidth}}
+% \toprule
+% Name & role & age & activity \tabularnewline
+% \midrule
+% William John & father & 45 & employee \tabularnewline
+% Mary Elisabeth & mother & 42 & elementary school
+% teacher\tabularnewline
+% Joan Laura & daughter & 14 & junior high school
+% student\tabularnewline
+% Jack Johnathan & son & 8 & elementary school pupil
+% \tabularnewline
+% \bottomrule
+% \end{tabular*}
+% \caption{A table typeset with \texttt{tabular*} where the total
+% width has been set to \cs{textwidth}}\label{tab:tab*}
+% \end{table}
+%
+% As it can be seen, large inter column spaces are inserted right
+% at the left of the contents of every cell except the first one,
+% and the table appears too much spread out.
+%
+% The table can be built also with the environment |tabularx|,
+% defined by the |tabularx| package; see the result in
+% table~\ref{tab:tabx}.
+% \begin{table}\centering
+% \begin{tabularx}{\textwidth}{llr>{\raggedright}X}
+% \toprule
+% Name & role & age & activity \tabularnewline
+% \midrule
+% William John & father & 45 & employee \tabularnewline
+% Mary Elisabeth & mother & 42 & elementary school
+% teacher\tabularnewline
+% Joan Laura & daughter & 14 & junior high school
+% student\tabularnewline
+% Jack Johnathan & son & 8 & elementary school pupil
+% \tabularnewline
+% \bottomrule
+% \end{tabularx}
+% \caption{A table typeset with \texttt{tabularx} where the total width
+% has been set to \cs{textwidth}}\label{tab:tabx}
+% \end{table}
+%
+% As it is noticeable the whole space to enlarge the table has
+% been taken from the |X| column, and the table does not look right.
+%
+% Now we show the difference by using the |widetable| environment
+% in table~\ref{tab:tabwide}.
+% \begin{table}\centering
+% \begin{widetable}{\textwidth}{llr>{\raggedright}p{0.29\textwidth}}
+% \toprule
+% Name & role & age & activity \tabularnewline
+% \midrule
+% William John & father & 45 & employee \tabularnewline
+% Mary Elisabeth & mother & 42 & elementary school
+% teacher\tabularnewline
+% Joan Laura & daughter & 14 & junior high school
+% student\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
+% has been set to \cs{textwidth}}\label{tab:tabwide}
+% \end{table}
+%
+% 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 may object that the table spaces
+% are too wide and table~\ref{tab:tab} looks better. But if, for
+% 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
+% fulfil. If the examples were typeset with the horizontal and
+% vertical rules that emphasise each cell (instead of using only
+% the |booktabs| horizontal rules) it would be more evident
+% how the various environments shape the cells and where they
+% insert the extra spacing so as to reach the desired width.
+%
+% \section{Warnings}
+% Normally |widetable| works well as described in the example
+% shown in table~\ref{tab:tabwide}. Nevertheless there are some
+% issues that may alter its smooth working.
+%
+% One such issue takes place when the specified table width
+% 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: the warning looks like this
+%\begin{verbatim}
+%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 415.
+%\end{verbatim}
+% As usual the warning is contained 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
+% to the same columns, but the table looks very ugly; we cannot
+% say that |widetable| is responsible of this ugliness, or if
+% the table is ill formed because of using such overlapping
+% spanned cells; the best suggestion is to never use such
+% “acrobatic” table compositions.
+%
+% \section{Acknowledgements}
+% I must deeply thank Enrico Gregorio for the revision of
+% 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.
+%
+% \StopEventually{}
+%
+%\iffalse
+%<*package>
+%\fi
+% \section{Implementation}
+%
+% We identify the package and the necessary \LaTeX\ kernel
+% \begin{macrocode}
+\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. 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}[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
+%
+% We further define the start of the tabular typesetting
+% 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.
+%
+% 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}
+\DeclareDocumentEnvironment{widetable}{m O{c} m +b}
+{% OPENING WIDETABLE COMMANDS
+}%
+% \end{macrocode}
+% 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 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
+% 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}
+{% CLOSING WIDETABLE
+ \dimen0=#1 % required width
+ \tabcolsep=\z@
+ \setbox\z@=\hbox{\tabular{#3}#4\endtabular}%
+ \tabcolsep=6pt\relax
+ \setbox\tw@=\hbox{\tabular{#3}#4\endtabular}%
+ \ifdim\dimen0>\wd\z@
+ \tabcolsep=\dimexpr \tabcolsep*(\dimen0-\wd\z@)/(\wd\tw@-\wd\z@)\relax
+ \else
+ \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
+ \tabular[#2]{#3}#4\endtabular
+ \ignorespacesafterend
+}
+% \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.
+%
+% \section{Conclusion}
+% 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. 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
+% |\tabcolsep| by the right amount in order to fit the
+% measure? The result might be a table where only the
+% 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
+% \pack{graphicx.sty} package. Nobody forbids to follow
+% this technique, of course, but the |widetable| route might
+% yield a better result.
+%
+% The same is true when a natural width table is slightly
+% shorter than the measure; enlarging it by retouching
+% the |\tabcolsep| inter column space might be the right
+% solution in order to avoid a multitude of slightly
+% different indents or left margins.
+%
+% \begin{macrocode}
+
+\endinput
+% \end{macrocode}
+%\iffalse
+%</package>
+%\fi
+%
+% \Finale
+% ^^A\endinput
diff --git a/macros/latex/contrib/widetable/widetable.pdf b/macros/latex/contrib/widetable/widetable.pdf
new file mode 100644
index 0000000000..f2a2f1d191
--- /dev/null
+++ b/macros/latex/contrib/widetable/widetable.pdf
Binary files differ