Debian Codegraph @

texmf-dist/source/latex/widetable/widetable.dtx

raw
1 % \iffalse meta-comment
2 %<*internal>
3 \begingroup
4 \input docstrip.tex
5 \keepsilent
6
7
8 \preamble
9 ______________________________________________________
10 The WIDETABLE bundle
11 Copyright (C) 2009-2020 Claudio Beccari
12 All rights reserved
13
14 License information appended
15
16 \endpreamble
17 \postamble
18
19 Copyright 2009-2020 Claudio Beccari
20
21 Distributable under the LaTeX Project Public License,
22 version 1.3c or higher (your choice). The latest version of
23 this license is at: http://www.latex-project.org/lppl.txt
24
25 This work is "author-maintained"
26
27 This work consists of this file widetable.dtx, a README file
28 the manifest.txt file, and the derived files:
29 widetable.sty and widetable.pdf.
30
31
32 By running pdflatex on widetable.dtx the user gets both
33 the sty file and the English documentation PDF file.
34
35 \endpostamble
36
37 \askforoverwritefalse
38
39 \generate{\file{widetable.sty}{\from{widetable.dtx}{package}}}
40
41 \def\tmpa{plain}
42 \ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
43 \endgroup
44 %</internal>
45 % \fi
46 %
47 % \iffalse
48 %<*driver>
49 \ProvidesFile{widetable.dtx}%
50 %</driver>
51 %<package>\NeedsTeXFormat{LaTeX2e}[2018/01/01]
52 %<package>\ProvidesPackage{widetable}%
53 %<*package>
54 [2020-01-13 v.2.1 Package for typesetting specified width tables]
55 %</package>
56 %<*driver>
57 \documentclass{ltxdoc}
58 \hfuzz 10pt
59 \def\prog#1{\textsf{\slshape#1}}
60 \usepackage{multicol}
61 \usepackage[utf8]{inputenc}
62 \usepackage[T1]{fontenc}
63 \usepackage{textcomp}
64 \usepackage{lmodern}
65 \usepackage[italian,english]{babel}
66 \usepackage{widetable,tabularx,xcolor,booktabs,ragged2e}
67 % local definitions
68 \let\originalmeta\meta
69 \renewcommand\meta[1]{{\normalfont\originalmeta{#1}}}
70 \renewcommand\marg[1]{\texttt{\{\meta{#1}\}}}
71 \newcommand\Marg[1]{\texttt{\{#1\}}}
72 \newcommand\opz[1]{\texttt{[\meta{#1}]}}
73 \newcommand\Opz[1]{\texttt{[#1]}}
74 \newcommand\amb[1]{\texttt{\slshape#1}}
75 \renewcommand\cs[1]{{\normalfont\ttfamily\char92#1}}
76 \newcommand\Benv[1]{\texttt{\char92begin\{#1\}}}
77 \newcommand\Eenv[1]{\texttt{\char92end\{#1\}}}
78 \newcommand\eTeX{$\varepsilon$-\TeX}
79 \renewcommand\prog[1]{\textsf{#1}}
80 \newcommand\pack[1]{\texttt{\itshape#1}}
81 % end local definitions
82 \begin{document}
83 \makeatletter
84 \GetFileInfo{widetable.dtx}%
85 \title{The \pack{widetable} package}
86 \date{Version number \fileversion; last revised on \filedate.}
87 \author{Claudio Beccari\thanks{\texttt{claudio dot beccari at gmail dot com}}}
88 \maketitle
89 \begin{multicols}{2}
90 \tableofcontents
91 \end{multicols}
92 \DocInput{widetable.dtx}
93 \end{document}
94 %</driver>
95 % \fi
96 % \CheckSum{60}
97 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
98 % \begin{abstract}
99 % This package allows to typeset tables of specified width,
100 % provided they fit in one page. Instead of introducing an
101 % infinite stretching glue, which has an unsymmetrical effect
102 % in standard \LaTeX, here the |\tabcolsep| dimension is
103 % computed so as to have the table come out with the proper
104 % width.
105 % \end{abstract}
106 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
107 %
108 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
109 % \section{Legalese}
110 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
111 %
112 % This file is part of the |widetable| package.
113 %
114 % This work may be distributed and/or modified under the
115 % conditions of the LaTeX Project Public License, either version 1.3
116 % of this license or (at your option) any later version.
117 % The latest version of this license is in
118 % http://www.latex-project.org/lppl.txt
119 % and version 1.3 or later is part of all distributions of LaTeX
120 % version 2003/12/01 or later.
121 %
122 % This work has the LPPL maintenance status ``maintained''.
123 %
124 % The Current Maintainer of this work is Claudio Beccari
125 %
126 % The list of all files belonging to the distribution is
127 % given in the file `README.txt'.
128 %
129 % The list of derived (unpacked) files belonging to the distribution
130 % and covered by the LPPL is contained in the README.txt file.
131 %
132 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
133 %\section{Introduction}
134 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
135 % It is well known that when the standard environment
136 % |tabular*| is opened with a specified width, it is
137 % necessary to introduce in the delimiter declaration
138 % |@{...}| (possibly) of the first item of the column
139 % descriptors argument something like
140 % \begin{verbatim}
141 % \extracolsep{\fill}
142 % \end{verbatim}
143 % in addition to other possible printable delimiters, such
144 % as vertical lines, and other fixed spacing commands. The
145 % effect is that the extra stretchable glue operates only
146 % on the left of each cell \emph{after} (i.e. to the \emph{right}
147 % of) the cell that received the declaration; the first cell
148 % will never get larger in spite of the presence of this glue.
149 %
150 % Another package, \pack{tabularX}, normally distributed by the
151 % \LaTeX\,3 Team with every version of the \TeX\ system
152 % distribution, allows to create expandable cells, provided they
153 % contain only text and, possibly, in-line math. These expandable
154 % cells are identified with the column descriptor |X|; this
155 % identifier defines a paragraph-like cell, the width of
156 % which gets determined after some runs of the typesetter
157 % on the same source tabular material, so as to find out the
158 % correct width of the textual columns.
159 %
160 % Also \pack{tabu} can build tables of specified
161 % width; but it has so many functionalities that it appears
162 % to be oversized for a simple task such as the one performed
163 % by \pack{widetable} and \pack{tabularx}.
164 %
165 % The approach here is a little bit different: the cell
166 % contents need not be textual and no cell width is determined
167 % in one or more runs of the typesetting program; instead the
168 % inter column glue is determined so as to fill every cell
169 % on both sides with the proper space. The macros contained
170 % in this package are insensitive to the particular kind
171 % of cell descriptors and to the presence of multiple
172 % |\multicolumn| commands. It proved to work properly also
173 % if the |array| package extensions are used.
174 % Nevertheless if multiple |\multicolumn| commands in different
175 % rows “interlace” the columns they work on, poor results
176 % would be obtained: in this case the table is typeset the same
177 % as with the environment |tabular|.
178 %
179 % On the other hand, as well as for |tabularx|, it needs to
180 % typeset the table three times; the first two times with
181 % standard values for the inter column glue |\tabcolsep|, in
182 % order to find the exact parameters of the linear dependence
183 % of the table width from the value of that glue; then executes
184 % some computations so as to determine the final correct
185 % value of |\tabcolsep|, and on the third run it eventually
186 % typesets the table with the specified width.
187 %
188 % The typesetting time increase needed for these three tabular runs
189 % is generally negligible, nevertheless if a specific
190 % document contained many dozens of such tables, the small compilation
191 % time increase might become perceivable.
192 %
193 % It might be noticed that, in order to perform the necessary
194 % computations, a fractional division algorithm must be used;
195 % since 2009 any \TeX\ installation uses the \eTeX\ extensions;
196 % therefore fractional division is not any more an issue as
197 % it was in previous versions of this package.
198 %
199 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
200 % \section{Normal use of \pack{widetable}}
201 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
202 % With this release of the bundle, the environment to be used
203 % is named |widetabular|, although the previous name, |widetable|,
204 % remains available for backwards compatibility.
205 %
206 % This package may issue an error message when the
207 % environment includes other unhidden ones; this is
208 % explained in the Implementation section. In plain words,
209 % if a |widetabular| environment is nested into another |widetabular|
210 % one, the inner environment must be “hidden” within a group
211 % (i.e. a couple of paired braces); this might not be necessary
212 % with other tabular-like environments.
213
214 % Here it is assumed that the user first uses the standard tabular
215 % environment and typesets it to its natural width; should it appear
216 % too small, and should it be typeset at a larger width, for example
217 % by filling the total |\linewidth| available at that specific point,
218 % then and only then the user switches to |widetabular|. Should the
219 % initial table be moderately larger than |\linewidth|, then it might
220 % be shrunk to |\linewidth| by means of |widetabular|, provided there
221 % are enough columns, and therefore column delimiters, to be reduced in
222 % size. Of course it is impossible to typeset any tabular with any
223 % negative value of |\tabcolsep|; or better, the software does not care,
224 % but the result might get very messy.
225 %
226 % In other words |widetabular| should be used as a second resort,
227 % so as to correct some typesetting features of the standard environment
228 % not considered aesthetically acceptable.
229 %
230 % The syntax for using the environment |widetabular| is the
231 % same as that of the |tabular*| one; the only difference
232 % is the name. Therefore one has to specify:
233 % \begin{flushleft}\obeylines%
234 % \Benv{widetabular}\textcolor{red!90!black}{\marg{width}}\opz{alignment}\marg{column descriptors}
235 % \meta{row of cells}\cs{\textbackslash}
236 % \meta{row of cells}\cs{\textbackslash}
237 % \texttt{...}
238 % \meta{row of cells}\cs{\textbackslash}
239 % \meta{row of cells}\cs{\textbackslash}
240 % \Eenv{widetabular}
241 % \end{flushleft}
242 %
243 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
244 % \section{The method}
245 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
246 % The principle on which this little package is based is the
247 % following one: suppose a certain tabular is typeset with an inter
248 % column glue $t_0=0\mathrm{\,pt}$ and that its width turns
249 % out to be $l_0$; suppose the same tabular material is typeset
250 % again with an inter column glue $t_1 >0\mathrm{\,pt}$ so that
251 % the table gets as large as $l_1>l_0$. Then, if the table has
252 % to be as wide as $l$ the inter column glue $t$ should be
253 % \[
254 % t = \frac{l - l_0}{l_1 - l_0}\cdot t_1
255 % \]
256 %
257 % Therefore we need to run the typesetting of the same tabular
258 % material with the two values of the inter column glue set
259 % to zero and to $t_1$, respectively, so as to find the widths
260 % $l_0$ and $l_1$. Afterwards we have to determine the correct
261 % final value $t$ to get the desired value $l$, and typeset once
262 % again the same tabular material for the last time.
263 %
264 % Of course the first two runs must put their results into
265 % suitable boxes so as to avoid outputting them into the output
266 % file, while at the same time allowing to record the width
267 % of such enclosing boxes.
268 %
269 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
270 % \section{The \pack{xparse} package}
271 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
272 % The previous version of this package already used the \pack{xparse}
273 % package functionalitIes; but this latter package evolves and now
274 % it is possible to “save” the body of the table as an argument
275 % to the opening commands, therefore now it is much simpler to
276 % use the same table-body several times. Of course this body
277 % is saved in internal memory areas, but this task is
278 % implemented by the internal macros written in the L3
279 % \LaTeX\ language. The advantage of using the \pack{xparse}
280 % package consists in a much shorter code that is easier to read
281 % and maintain. The number of macros for this package is
282 % reduced by a factor of about four, compared to the previous
283 % versions~1.x of this package.
284 %
285 % \section{Using the \eTeX\ facilities}
286 % The L3 language and its libraries now offer the user some \LaTeX\
287 % interfaces to its internal macros to the point of executing also
288 % floating point operations that span a wide range; the suitable
289 % package would be \pack{xfp}. Nevertheless it appears sort of
290 % overdone for the simple computations needed here..
291 %
292 % At the same time the \eTeX\ extended functionalities are now
293 % part of all the interpreters of the \LaTeX\ language,
294 % \prog{pdftex}, \prog{luatex}, and \prog{xetex}; this renders
295 % this package usable with any typesetting programs based on \LaTeX:
296 % \prog{pdflatex}, \prog{lualatex}, and \prog{xelatex}.
297 %
298 % In facts such \eTeX\ extensions provide also a scaling operation:
299 % given the length $L_1$ and two homogeneous quantities $X_1$
300 % and $X_2$ (where such quantities may be either two integer
301 % numbers, or two dimensions), such scaling operation scales
302 % $L_1$ to $L_2$ by computing
303 %\[
304 % L_2 = \frac{L_1 X_2}{X_1}
305 %\]
306 % The intermediate results are actually done with integer
307 % arithmetics (internally lengths are coded as an integer number of
308 % scaled points) but they are done in double words so as to avoid
309 % underflows and overflows almost always. Some unusual situations
310 % might exist where underflows or overflows do occur, but
311 % they must be very unusual, and very unlikely to happen for
312 % the calculations of this package. This would happen if for any
313 % reason no inter column glue is available; we have difficulties
314 % imagining such a table and cannot make even a silly example.
315 %
316 % The use of the \eTeX\ extensions implies that this package
317 % works correctly only with modern engines and kernel formats.
318 %
319 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
320 % \section{Usage}
321 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
322 % As explained above, the normal usage of |widetabular| requires the same
323 % syntax as that of |tabular*| except that no explicit stretchable
324 % glue has to be inserted in the column separators as it is necessary
325 % to do with |tabular*|. Examine the table shown in
326 % table~\ref{tab:tab}\footnote{Notice that here the name “table” is used
327 % to refer to the \amb{table} floating environment and its caption,
328 % while “tabular” is reserved to the tabular itself and its contents.}
329 % that is typeset at its natural width.
330 % \begin{table}\centering
331 % \begin{tabular}{llr>{\raggedright}p{0.29\textwidth}}
332 % \toprule
333 % Name & role & age & activity \tabularnewline
334 % \midrule
335 % William John & father & 45 & employee \tabularnewline
336 % Mary Elisabeth & mother & 42 & elementary school
337 % teacher\tabularnewline
338 % Joan Laura & daughter & 14 & junior high school
339 % student\tabularnewline
340 % Jack Johnathan & son & 8 & elementary school pupil
341 % \tabularnewline
342 % \bottomrule
343 % \end{tabular}
344 % \caption{A regular table typeset with \texttt{tabular} and its width is its natural one}\label{tab:tab}
345 % \end{table}
346 %
347 % The same table can be built with |tabular*| as in table~\ref{tab:tab*}.
348 %\begin{table}\centering
349 %\begin{tabular*}{\textwidth}%
350 % {@{\hskip\tabcolsep\extracolsep{\fill}}llr>{\raggedright}%
351 % p{0.29\textwidth}}
352 % \toprule
353 % Name & role & age & activity \tabularnewline
354 % \midrule
355 % William John & father & 45 & employee \tabularnewline
356 % Mary Elisabeth & mother & 42 & elementary school
357 % teacher\tabularnewline
358 % Joan Laura & daughter & 14 & junior high school
359 % student\tabularnewline
360 % Jack Johnathan & son & 8 & elementary school pupil
361 % \tabularnewline
362 % \bottomrule
363 %\end{tabular*}
364 % \caption{A table typeset with \texttt{tabular*} where the total
365 % width has been set to \cs{textwidth}}\label{tab:tab*}
366 %\end{table}
367 %
368 % As it can be seen, large inter column spaces are inserted right
369 % at the left of the contents of every cell except the first one,
370 % and the table appears too much spread out.
371 %
372 % The tabular can be built also with the environment |tabularx|,
373 % defined by the |tabularX| package; see the result in
374 % table~\ref{tab:tabx}.
375 % \begin{table}\centering
376 % \begin{tabularx}{\textwidth}{llr>{\raggedright}X}
377 % \toprule
378 % Name & role & age & activity \tabularnewline
379 % \midrule
380 % William John & father & 45 & employee \tabularnewline
381 % Mary Elisabeth & mother & 42 & elementary school
382 % teacher\tabularnewline
383 % Joan Laura & daughter & 14 & junior high school
384 % student\tabularnewline
385 % Jack Johnathan & son & 8 & elementary school pupil
386 % \tabularnewline
387 % \bottomrule
388 % \end{tabularx}
389 % \caption{A table typeset with \texttt{tabularx} where the total width
390 % has been set to \cs{textwidth}}\label{tab:tabx}
391 % \end{table}
392 %
393 % As it is noticeable the whole space to enlarge the tabular has
394 % been used by the |X| column, and the table does not look right.
395 %
396 % Now we show the difference by using the |widetabular| environment
397 % in table~\ref{tab:tabwide}.
398 % \begin{table}\centering
399 % \begin{widetabular}{\textwidth}{llr>{\raggedright}p{0.29\textwidth}}
400 % \toprule
401 % Name & role & age & activity \tabularnewline
402 % \midrule
403 % William John & father & 45 & employee \tabularnewline
404 % Mary Elisabeth & mother & 42 & elementary school
405 % teacher\tabularnewline
406 % Joan Laura & daughter & 14 & junior high school
407 % student\tabularnewline
408 % Jack Johnathan & son & 8 & elementary school pupil\tabularnewline
409 %\begin{tabular}{@{}ll@{}}
410 %Goofy & Pluto\\
411 %Donald Duck & Mickey Mouse
412 %\end{tabular} & \relax & 4 & Walt Disney\tabularnewline
413 % \bottomrule
414 % \end{widetabular}
415 % \caption{A table typeset with \texttt{widetabular} where the total
416 % width has been set to \cs{textwidth}}\label{tab:tabwide}
417 % \end{table}
418 %
419 % In table~\ref{tab:tabwide} the column specifications are the same
420 % as those used in the code for table~\ref{tab:tab}, but only the
421 % spaces separating the columns have been modified, not the column
422 % types and widths. Of course one may object that the table spaces
423 % are too wide and table~\ref{tab:tab} looks better. But if, for
424 % example, in a certain document all tables are required to span
425 % the whole measure, the solution shown in table~\ref{tab:tabwide}
426 % is the only one acceptable among these four examples.
427 % It's up to the user to chose among these four solutions in terms
428 % of the actual tabular contents and the stylistic constraints the
429 % document must fulfil.
430 % If the examples were typeset with the (horizontal and
431 % vertical rules that emphasise each cell (instead of using only
432 % the |booktabs| horizontal rules) it would be more evident
433 % how the various environments shape the cells and where they
434 % insert the extra spacing so as to reach the desired width.
435 %
436 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
437 % \section{Warnings}
438 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
439 % Normally |widetabular| works well as described in the example
440 % shown in table~\ref{tab:tabwide}. Nevertheless there are some
441 % issues that may alter its smooth working.
442 %
443 % One such issue takes place when the specified table width
444 % is shorter than the natural width. In this case the table is
445 % typeset as in table~\ref{tab:tab} at its natural width, but
446 % a warning is issued that explains why: the warning looks like this
447 %\begin{verbatim}
448 %Package widetable Warning: The minimum width of the tabular material
449 %(widetable) amounts to 225.19809pt, and is larger
450 %(widetable) than the required width of 177.5pt
451 %(widetable)
452 %(widetable) The table is typeset with the default
453 %(widetable) column spacing on input line 415.
454 %\end{verbatim}
455 % As usual the warning is contained into the |.aux| file and in
456 % the console, if the shell editor displays it..
457 %
458 % When some adjacent cells are grouped with the |\multicolumn|
459 % command; the table might come out of the correct specified width
460 % even if the spanned cells (in different rows) do not belong
461 % to the same columns, but the table looks very ugly; we cannot
462 % say that |widetable| is responsible of this ugliness, or if
463 % the table is ill formed because of using such overlapping
464 % spanned cells; the best suggestion is to avoid using such
465 % “acrobatic” tabular compositions.
466 %
467 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
468 % \section{Acknowledgements}
469 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
470 % I must deeply thank Enrico Gregorio for the revision of
471 % this package macros and for his wise suggestions about
472 % the correct programming style. If some glitch still
473 % remains in the programming style, that is just my fault.
474 %
475 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
476 % \StopEventually{}
477 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
478 %
479 %\iffalse
480 %<*package>
481 %\fi
482 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
483 % \section{Implementation}
484 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
485 %
486 % This package has been already identified by the commands extracted
487 % by the |doctrip| package, during the |.dtx| file compilation.
488 %
489 % We require the |xparse| package in order to define the |widetable|
490 % environment with its extended commands. This package version should be
491 % younger the the specified date contained in the optional argument.
492 % If it is not, a warning is issued; but expect errors. It is a warning
493 % that urges the user to upgrade his/her \TeX\ system installation.
494 % \begin{macrocode}
495 \RequirePackage{xparse}[2019-05-01]
496 % \end{macrocode}
497 %
498 % We require the |xparse| package in order to define the % environment
499 % |widetable| with its extended commands. Tis package version should be
500 % younger the the specified date contained in the optional argument.
501 % If it is not, a warning is issued; but expect errors. It is a warning
502 % that should urge the user to upgrade his/her \TeX\ system installation.
503 %
504 %The special environment opening macro requires the following syntax:
505 %\begin{flushleft}\obeylines
506 %\Benv{widetable}\marg{width}\oarg{alignment}\marg{column descriptors}
507 %\meta{table body}
508 %\Eenv{widetable}
509 %\end{flushleft}
510 %
511 % We further define the |tabular| environment typesetting. Actually,
512 % with the new |xparse| faciltiies, the opening command parameters can
513 % be used also in the closing part of the environment, so that when the
514 % \meta{width} and the \meta{column descriptors} are given to the opening
515 % environment statement, they can be used again and again also by the
516 % closing commands.
517 %
518 % Actually the |widetabular| environment can contain other
519 % environments, even another |widetabular| ones, but
520 % the external one should not be upset by the internal ones.
521 % In order to achieve this result, it is necessary that
522 % embedded environments are hidden within a group delimited by
523 % a pair of matching braces; this is compulsory for an
524 % embedded |widetabular| environment, while it is not strictly
525 % required for other environments.
526 %
527 % The environment opening and closing actions
528 % are defined by means of low level commands.
529 %
530 % The opening part of the environment reduces to nothing else
531 % but the background L3 functions executed by the \cs{begin}
532 % command implementation and the correct parsing of the list
533 % of argument descriptors
534 % \begin{macrocode}
535 \DeclareDocumentEnvironment{widetabular}{m O{c} m +b}
536 {% OPENING WIDETABLE COMMANDS
537 }%
538 % \end{macrocode}
539 % These arguments have the following meanings.
540 %\begin{description}
541 %\item[Argument number one] It is mandatory and represents the desired
542 % table width.
543 %\item[Argument number two] It is optional. With a default value of
544 % \texttt{c} the table is aligned with respect to its math axis;
545 % the other possible values are \texttt{t} for top alignment, and
546 % \texttt{b} for bottom alignment; they are the same values used
547 % for the \LaTeX-kernel tabular environments.
548 %\item[Argument number three] It is mandatory; it should contain all the
549 % column descriptors and inter-column separators, possibly in
550 % the extended forms provided by the \pack{array} package.
551 %\item[Argument number four] It represents an \pack{xparse} functionality
552 % by which the whole environment body is internally saved in a sort
553 % of verbatim mode and become usable again and again as
554 % argument~\texttt{\#4}.
555 %\end{description}
556 %
557 % The closing statement will actually do the whole job. It first sets
558 % |\tabcolsep| to zero and typesets the resulting table into box zero;
559 % it uses, with parameter \texttt{\#4}, the table body collected with
560 % the argument descriptor \texttt{b} of the opening command.
561 %
562 % Then it sets |\tabcolsep| to 6\,pt (the default value) and
563 % typesets again the table into box two. The width of box zero
564 % is $l_0$ and that of box two is $l_1$; these are the lengths
565 % needed by the equation that evaluates the final typesetting
566 % inter column spacing.
567 %
568 % The arbitrary constant of 6\,pt is $t_1$, and the specified
569 % width $l$ (parameter \texttt{\#1}) are used to compute the
570 % new value of |\tabcolsep|. The subtractions are computed
571 % directly on the dimensions and passed to a |\dimexpr| expression
572 % so as to determine the new |\tabcolsep| value.
573 %
574 % The table is eventually typeset without using boxes, while the
575 % contents of box zero and box two, upon exiting the environment,
576 % are restored to any value they might have contained before
577 % entering |widetabular|.
578 % \begin{macrocode}
579 {% CLOSING WIDETABLE
580 \dimen0=#1 % required width
581 \tabcolsep=\z@
582 \setbox\z@=\hbox{\tabular{#3}#4\endtabular}%
583 \tabcolsep=6pt\relax
584 \setbox\tw@=\hbox{\tabular{#3}#4\endtabular}%
585 \ifdim\dimen0>\wd\z@
586 \tabcolsep=%
587 \dimexpr\tabcolsep*(\dimen0-\wd\z@)/(\wd\tw@-\wd\z@)\relax
588 \else
589 \ifdim\dimen0<\wd\z@
590 \PackageWarning{widetable}{%
591 The minimum width of the tabular material\MessageBreak
592 amounts to \the\wd\z@, and is larger\MessageBreak
593 than the required width of \the\dimen0\MessageBreak
594 \MessageBreak
595 The table is typeset with the default\MessageBreak
596 column spacing}%
597 \fi
598 \fi
599 \tabular[#2]{#3}#4\endtabular
600 \ignorespacesafterend
601 }
602 % \end{macrocode}
603 % For backward compatibility we let the names |\widetable| and
604 % |\endwidetable| equal respectively to |\widetabular| and
605 % |\endwidetabular|, so that the old name of the environment
606 % provided by this package is still usable; compiling old
607 % documents is till possible; nevertheless these “old” names are
608 % discouraged; in a future they might not be available any more.
609 % \begin{macrocode}
610 \let\widetable\widetabular \let\endwidetable\endwidetabular
611 % \end{macrocode}
612 % Notice the test and the warning: |widetabular| modifies the table
613 % width only if its minimum width (obtained with |\tabcolsep| equal
614 % to zero) is smaller than the requested width; otherwise it typesets
615 % the table with the default inter column glue, and outputs the warning
616 % message.
617 %
618 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
619 % \section{Conclusion}
620 %^^A%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
621 % Tables should always have their standard inter column spaces, but\dots\
622 % The default value of |\tabcolsep| is fixed by the document
623 % class, it is not prescribed by a supreme law: therefore
624 % what does it mean ``natural width''. Probably the one
625 % determined by the class default value of |\tabcolsep|,
626 % so that all tables have the same general look. But here we
627 % used the phrase “minimum width” as that of the tabulars width when the
628 % inter column glue is set to zero; we avoided speaking of the
629 % “natural width” because the phrase is not specific.
630 %
631 % Nevertheless sometimes a table is slightly wider than
632 % the current measure; why not shrink the table by shrinking
633 % |\tabcolsep| by the right amount in order to fit the
634 % measure? The result might be a table where only the
635 % inter column spaces are shrunk, not the whole table, fonts,
636 % drawings, and figures included, a result easily obtainable
637 % with a |\resizebox| command available through the
638 % \pack{graphicx.sty} package. Nobody forbids to follow
639 % this technique, of course, but the |widetable| route might
640 % yield a better result.
641 %
642 % The same is true when a natural width table is slightly
643 % shorter than the measure; enlarging it by retouching
644 % the |\tabcolsep| inter column space might be the right
645 % solution in order to avoid a multitude of slightly
646 % different indents or left margins.
647 %
648 % \begin{macrocode}
649
650 \endinput
651 % \end{macrocode}
652 %\iffalse
653 %</package>
654 %\fi
655 %
656 % \Finale
657 % ^^A\endinput