summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/widetable/widetable.dtx
blob: 2396a7a79eb38b3db7beab173836e7ce70465675 (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
% \iffalse meta-comment
%<*internal>
\begingroup
\input docstrip.tex
\keepsilent


\preamble
  ______________________________________________________
  The WIDETABLE bundle 
  Copyright (C) 2009-2017 Claudio Beccari 
  All rights reserved

  License information appended

\endpreamble
\postamble

Copyright 2009-2017 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 the sty 
file and the English documentation file in
PDF format.

\endpostamble

\askforoverwritefalse

\generate{\file{widetable.sty}{\from{widetable.dtx}{package}}}

\def\tmpa{plain}
\ifx\tmpa\fmtname\endgroup\expandafter\bye\fi
\endgroup
%</internal>
%
% Copyright 2009--2017 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>
   [2017/09/05 v.1.2 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}
% 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{\raisebox{-0.5ex}{$\varepsilon$}\kern-0.1666em\TeX}
% end local definitions
\begin{document}
\makeatletter
\GetFileInfo{widetable.dtx}% 
\title{The Package \textsf{widetable}}
\date{Version number \fileversion; last revision \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{180}
% \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 by the unpacking scripts (with 
% extension .ins) which are part of the distribution.
%
%\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
% \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}
% 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
% \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
% 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.
%  
% 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
% 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 thei work on, poor results
% are obtained, and sometimes no result at all  is obtained
% except a warning message.
%
% 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 time increase needed for these three table typesettings
% is in general rather 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{Usage}
% This package  issues an error message only in case the
% environment includes other unhidden environment; this is
% explained in the Implementation section.
% 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 the |\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
% 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 the use of 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$ 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
% 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
% \[
%  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 it has 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 long division algorithm}
% In previous versions 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 (already
% provided in |xetex| and |latex|, therefore available in
% |XeLaTeX| and |LuaLaTeX|) there is no need to create any
% long division macro, because such computation is already
% provided as a primitive command.
%
% \section{Using the \eTeX\ facilies}
% In facts the \eTeX\ extension provides the 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 length are an integer number of
% scaled points) but are done in double words so as to avoid
% underflow 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 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{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}[2017/09/05 v.1.2 A simpler way to produce
     tables of specified width]
%    \end{macrocode}
% The first thing to do is to globally define a certain
% number of \TeX\ dimensions and counters; these dimension
% and counter registers are 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, stating that not all users
% upgrade so often their \TeX\ system; OK, if they don't upgrade,
% they have available the previous versions of this package;
% now I assume that after so many years from when the engines
% were extended with the \eTeX\ facilities, I can't see why
% this package should resort to old approaches.
%   
%   
%    \begin{macrocode}
\dimendef\wt@Numer=2
\dimendef\wt@Denom=4
\countdef\wt@Num=2
\countdef\wt@Den=4
%    \end{macrocode}
%
% We require the |xparse| package in order to define the
% environment |widetable| with its extended commands.
%    \begin{macrocode}
\usepackage{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}
%    \end{macrocode}
%
% At this point it will be the |widetable| environment
% responsibility to call |\WT@scale| with the proper arguments
%    
% Now we define the dimension register that is to contain the
% desired table width. 
% 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. 
%    \begin{macrocode}
\newdimen\wt@width
%    \end{macrocode}
%    
% 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.
%    
%    \begin{macrocode}
\DeclareDocumentCommand\widetable{m O{c} m}
{% OPENING WIDETABLE
  \def\@tempC{widetable}
  \setlength{\wt@width}{#1}%
  \def\wt@preamble{#3}
  \edef\wt@starttabular{\noexpand\tabular[#2]{\wt@preamble}}
  \wt@getTable}%
%    \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.
% 
% Then it sets |\tabcolsep| to 1\,cm (arbitrarily chosen) 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
% entering |widetable|.
%    \begin{macrocode}
\def\endwidetable{% CLOSING WIDETABLE
  \ifwt@scartare
    \noindent\null
  \else
    \tabcolsep=\z@
    \setbox\z@=\hbox{\wt@starttabular\the\toks@\endtabular}%
    \tabcolsep=6pt\relax
    \setbox\tw@=\hbox{\wt@starttabular\the\toks@\endtabular}%
    \ifdim\wt@width<\wd\z@
       \@tempdimb=\dimexpr\wd\tw@-\wd\z@\relax
       \PackageWorning{widetable}{%
       The natural width `\the\wd\z@' of the tabular 
       material\MessageBreak
       is larger than the specified width 
       `\the\wt@width'\MessageBreak\null\space \MessageBreak
       The table is typeset with the default column spacing}
    \else
       \@tempdimb=\dimexpr\wt@width-\wd\z@\relax
    \fi
    \@tempdimc=\dimexpr\wd\tw@-\wd\z@\relax
      \WT@scale{\tabcolsep}{\@tempdimb}{\@tempdimc}{\tabcolsep}\relax
    \wt@starttabular\the\toks@\endtabular
  \fi
  \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}
%
% We finally can define the all 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
% 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.
%
% 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
% intercolumn 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
% 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| intercolumn space might be the right
% 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
%    \end{macrocode}
%\iffalse
%</package>
%\fi
%
% \Finale
% \endinput