path: root/Master/texmf-dist/source/latex/widetable/widetable.dtx

% \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/09 v.1.4 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 \textsf{widetable} package}
\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{178}
% \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}%
  \def\wt@starttabular{\tabular[#2]{#3}}%
  \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