summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/widetable/widetable.dtx
blob: d774e9a7e63f75ee45bd2cd58930d5ee4b6b6d9c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
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