% ruleddoc.tex                    TeXsis                  version 2.14
% :: $Header$
%======================================================================*
% This is the section of the manual on ruled table macros.
% I'm still working on describing all the features.  Read the code
% in ruled.tex to learn everything.     -EAM

\book                           % ``book'' document style
\input TXSdocM.doc              % special macros for this manual

\input ruled
\ATunlock                       % so we can use @ things 

\singlespaced                   % single spaced
\parskip=\baselineskip
\TeXquoteon                     % | is a TeX quote (printed  in \tt)
\singlelinetrue                 % for \description
\def\VT{\char'174}

%======================================================================*
\subsection{Ruled Tables                \label{sect.ruled}}

   While |\halign| in Plain \TeX\ is convenient for making simple
tables, it is still difficult to make tables with horizontal and
vertical rules.  Indeed, typesetting ruled tables in \TeX\ has often
been likened to programming a computer in assembler language.  Even
\TeXbook\ acknowledges that ``people who know how to make ruled tables
are generally known as \TeX\ Masters.''\reference{Masters} Knuth, {\it
op.\ cit.}, page 245
\endreference\relax
\TeXsis\ now includes a set of macros that take a great deal
of the difficulty out of making ruled tables, so that anybody can be a
\TeX\ Master.

   The basic idea behind making a ruled table is similar to
|\halign|, and the syntax is the same as the Princeton table
macros known as |TABLES.TEX| by Ray Cowan,\reference{Cowan} Ray
F.~Cowan, {\sl Making Tables with Macros} (unpublished)
\endreference 
although the \TeXsis\ macros are quite different internally and
run about 5 times faster.  You begin the table material with |\ruledtable|
and end it with |\endruledtable|.  The table material is a list
of items to appear in the rows and columns of the tables.  Just
as with |\halign| you can separate items in different columns
with |&| and end a row with |\cr|.  The |&| alignment character
separates columns without putting a vertical rule between the
columns, while |\cr| ends a line and puts a thin horizontal rule
under it.  To get a vertical rule between columns replace the |&|
with a `{\tt\VT}' (the vertical line), and to end a line without
a horizontal rule under it replace the |\cr| with |\crnorule|.
One important thing to remember is to end the last line in the
table with |\endruledtable| instead of |\cr|!

   As an example here is a simple ruled table:
{\singlespaced
\bigskip
\ruledtable
Year      |    World Population \cr
8000 B.C. |   ~~~5000000        \crnorule
~~50 B.C. |   ~200000000        \crnorule
1650 A.D. |   ~500000000        \crnorule
1850 A.D. |   1000000000        \crnorule
1945 A.D. |   2300000000        \crnorule
1980 A.D. |   4400000000        
\endruledtable
\smallskip}
\noindent And here are the instructions that created it:
\TeXexample
\ruledtable
Year      |VT    World Population \cr
8000 B.C. |VT   ~~~5000000        \crnorule
~~50 B.C. |VT   ~200000000        \crnorule
1650 A.D. |VT   ~500000000        \crnorule
1850 A.D. |VT   1000000000        \crnorule
1945 A.D. |VT   2300000000        \crnorule
1980 A.D. |VT   4400000000        
\endruledtable
|endTeXexample
This example also appears in \TeXbook, where it is typeset using
|\halign|.  Compare how the two are constructed
and see which way you think is easier.

   By default each item in the table is centered in its column.
Inside a table the tie character ``|~|'' takes up the
space of exactly one digit (it is the same as saying |\phantom{0}|),
and this has been used to line up the digits of the entries in
both columns.  It is also possible to change the definition of
the |\TableItem| macro so that each entry in each column is left
or right justified.  This is described a little bit later.

   Something to note about this example table is that the outer
rules are thicker than the others.  You can also get a thick
vertical rule between columns by using ``{\tt\bs\VT}'' in place of
``{\tt\VT}'', and you can get a thick horizontal rule below a row by
replacing the |\cr| with |\crthick|.  The widths of thick and
thin rules are controlled by the dimensions |\thicksize| and
|\thinsize|.  If you don't want thick rules at all simply say
|\thicksize=\thinsize|, which makes the thick rules as thin
as the thin rules.

   Some synonyms:  |\CR| is the same as |\crthick|, |\nr| is the
same as |\crnorule|, and |\crrule| is the same as |\cr| (actually
it's the other way around!).  |\tab| is the same as |&| --- it
separates columns without a vertical rule.  |\vb| is the same as
{\tt\VT}, it separates columns with a thin vertical bar, while
|\Vb| is the same as {\tt\bs\VT} and separates the columns with a
thick vertical bar.  You can also use |\dbl| to separate columns
with a double vertical rule.

   As in Plain \TeX\ you can use |\span| in place of |&| (or the
other column separators) to join two columns together into one,
and you can use |\omit| as the very first token in a column to
tell it to omit the fancy column layout (the centering or other
spacing).  You can also use |\multispan| to |\span| and |\omit|
several columns, just as in an |\halign|.  The only difference is
that the number of columns you tell it to |\multispan| is the
number of columns of the table it spans --- with an |\halign| you
have to count the columns {\it and} any vertical rules.

\table{table-example-II}
\singlespaced
\ruledtable
\multispan3\hfil AT\&T Common Stock \hfil\CR
 Year \dbl Price | Dividend \cr
 1971 \dbl 41-54 | \$2.60   \cr
 ~~~2 \dbl 41-54 | \$2.70   \cr
 ~~~3 \dbl 46-55 | \$2.87   \cr
 ~~~4 \dbl 40-53 | \$3.24   \cr
 ~~~5 \dbl 45-52 | \$3.40   \cr
 ~~~6 \dbl 51-59 |  ~~.95
\endruledtable
\caption{Another example of a ruled table.}
\endtable

  \Tbl{table-example-II} is another sample table, again taken
{from} \TeXbook.  Something important to notice is that the last
ruled table example didn't have a table number or a caption,
while this one does.  That's because the last example was created
using just |\ruledtable|, while this example is inside of
|\table|.  The point is that |\table| and |\ruledtable| do
separate things and can be used either separately or together:
|\table| creates the space for the table and gives it a caption
and a number, while |\ruledtable| actually constructs the body of
the ruled table.  The instructions that created \Tbl{table-example-II}
are:
\TeXexample
\table{table-example-II}
\singlespaced
\ruledtable
\multispan3\hfil AT\&T Common Stock \hfil\CR
Year \dbl Price | Dividend \cr
1971 \dbl 41-54 | \$2.60   \cr
~~~2 \dbl 41-54 | \$2.70   \cr
~~~3 \dbl 46-55 | \$2.87   \cr
~~~4 \dbl 40-53 | \$3.24   \cr
~~~5 \dbl 45-52 | \$3.40   \cr
~~~6 \dbl 51-59 |  ~~.95
\endruledtable
\caption{Another example of a ruled table.}
\endtable
|endTeXexample
\medskip

      Ruled tables are normally centered on the page, but you can turn
off the centering with |\noncenteredtables|. Then the table becomes just
another piece to add to a horizontal list. One thing this lets you do is
have two tables side by side on the page, like so:
\noncenteredtables
\medskip
\line{
\ruledtable
Item ABC | Item DEF \cr
Item GHI | Item JKL \endruledtable
\hfil
\ruledtable
Data 111 | Data 222 \cr
Data 333 | Data 444 \cr
Data 555 | Data 666 \endruledtable}
\smallskip
\noindent This pair of tables was produced by saying:
\TeXexample
\noncenteredtables
\medskip
\line{
\ruledtable
Item ABC | Item DEF \cr
Item GHI | Item JKL \endruledtable
\hfil
\ruledtable
Data 111 | Data 222 \cr
Data 333 | Data 444 \cr
Data 555 | Data 666 \endruledtable}
\smallskip
|endTeXexample
\noindent Saying |\centeredtables| turns table centering back on.
Tables are then centered across the page, and a table is then 
added to a {\it vertical} list.
\bigskip
\goodbreak

   Usually |\ruledtable| makes tables as wide as their
natural width, but it is possible to make them wider by
setting the dimension |\tablewidth| to the width desired.  We
can make the same table in 
\Tbl{table-example-II} but with the width set to 10cm:
%
\bigskip
\noncenteredtables
\tablewidth=10cm
\line{\hfil\vbox{\singlespaced
\ruledtable
\multispan3\hfil AT\&T Common Stock \hfil\CR
Year \dbl Price | Dividend \cr
1971 \dbl 41-54 | \$2.60   \cr
~~~2 \dbl 41-54 | \$2.70   \cr
~~~3 \dbl 46-55 | \$2.87   \cr
~~~4 \dbl 40-53 | \$3.24   \cr
~~~5 \dbl 45-52 | \$3.40   \cr
~~~6 \dbl 51-59 |  ~~.95\rlap* 
\endruledtable
\hbox{* (first quarter only)}
\vss}\hfil}
\smallskip
\noindent  
The careful reader will notice that the version of
\Tbl{table-example-II} in \TeXbook\ had a footnote to the last
entry, and we have added that here.  To do so we had to put the footnote
in an |\hbox| and stack it under the table, so we had to turn off
table centering.  The table is therefore a bit more complicated
to make, but not much:
\TeXexample
\noncenteredtables
\tablewidth=10cm
\line{\hfil\vbox{\singlespaced
\ruledtable
\multispan3\hfil AT\&T Common Stock \hfil\CR
Year \dbl Price | Dividend \cr
1971 \dbl 41-54 | \$2.60   \cr
~~~2 \dbl 41-54 | \$2.70   \cr
~~~3 \dbl 46-55 | \$2.87   \cr
~~~4 \dbl 40-53 | \$3.24   \cr
~~~5 \dbl 45-52 | \$3.40   \cr
~~~6 \dbl 51-59 |  ~~.95\rlap* 
\endruledtable
\hbox{* (first quarter only)}
\vss}\hfil}
|endTeXexample
\centeredtables         % turn back on!

   Important note:  |\tablewidth| is turned ``off'' after the
table is made, so  the next table will have its natural width
unless you explicitly set |\tablewidth| again!
\bigskip\goodbreak

The careful reader may also have noticed that in making the
example in \Tbl{table-example-II} we said |\singlespaced|.
That's because the spacing of the rows of a table can be
controlled just like the spacing of the of the text with
|\singlespaced|, |\doublespaced|, etc.  The space between the
rows of a table is set by a strut called |\tstrut|, which
holds the rows apart.  You can change the spacing between rows by
changing the definition of this strut.  One of the things
|\singlespaced| does is define the |\tstrut| to be 0.4ex
higher and deeper than a parenthesis:
\TeXexample
\def\tstrut{\vrule height 2.24ex depth 1.08ex width 0pt}
|endTeXexample
\noindent 
|\doublespaced| increases the height of the strut by one ``ex,''
while |\triplesaced| increases it by yet another ``ex.''  You can
re-define |\tstrut| to be whatever you want to suit your
tastes.  If you have something to put in a table which is larger
than the strut then it will spill out into the rows above or
below.  To prevent this you could put the item in an |\hbox|, but
this is not quite satisfactory, since there won't be any space
above or below the item.  Instead you can say
|\bigitem{|\meta{stuff }|}| and ``stuff'' will be positioned
correctly with a nice amount of space above and below.
\medskip

  You can also decide whether or not you want diagnostic messages
printed when a table is created.  |\tableinfotrue| causes a
message to be printed on your terminal every time a ruled table
is created.  The message tells you how many rows and columns were
in the table.  This is useful information, because it can tell
you immediately if you made a mistake in the table or left out a
row or column.  |\tableinfotrue| is the default, but you can turn
off these messages by saying |\tableinfofalse|.
\medskip

  The tables we have demonstrated so far all contain numbers, but
sometimes it is desirable to have an entry in a table which is a
paragraph of text.  For that purpose, you can use |\para{|\meta{text}|}|.
The width of the paragraph is determined by the dimension |\parasize|,
which defaults to 4 inches.
\medskip

\table{tablemac;a}
\caption{Basic table macros for use with {\tt\bs ruledtable}.}
\intablelist{Basic macros for {\tt\bs ruledtable}}
\tablewidth=\hsize
\LeftJustifyTables
\ruledtable
\sl Macro name\relax         
        | \sl Description \relax \crthick
\tt\bs ruledtable\relax      
        | \para{Starts a ruled table.}\cr
\tt\bs endruledtable\relax        
        | \para{Ends the ruled table.}\cr
\tt\bs cr\relax              
        | \para{Ends the current row, and starts the next
        one.  The completed row will be separated from
        the next with a thin horizontal rule.}\cr
\vtop{\noindent\hsize=1.4in\baselineskip=15pt
\tt\bs crthick \hfil\break \rm or \tt\bs CR\hfil }\relax         
        | \para{Similar to {\tt\bs cr}, but the rows will
        be separated with a thick horizontal rule.}\cr
\vtop{\noindent\hsize=1.4in\baselineskip=15pt
\tt\bs crnorule \hfil\break \rm or \tt\bs nr\hfil }\relax         
        | \para{Similar to {\tt\bs cr}, but the rows will
        not be separated by a rule.}\cr
\vtop{\noindent\hsize=1.4in\baselineskip=15pt
\tt\char124\quad \rm (vertical bar)\hfil\break
or \tt\bs vb\hfil} \relax
        | \para{Separates one column from the next, and
        puts a vertical rule between them.}  \cr
\tt\&\ \rm or\tt\ \bs tab \relax
        | \para{Same as {\tt\char124}, but does not put
        in the vertical rule between the columns.}\cr
\tt\bs\char124 \relax        
        | \para{Same as {\tt\char124}, but puts in a
        thick vertical rule.}
\endruledtable
\line{\hfil {\sl Continued...}}
\endtable

\fulltable{tablemac;b}
\caption{Additional macros for use with {\tt\bs ruledtable}.}
\intablelist{Additional macros for {\tt\bs ruledtable}}
\tablewidth=\hsize
\LeftJustifyTables
\line{{\sl Continued...}\hfil}
\smallskip
\ruledtable
\sl Macro name\relax         
        | \sl Description \relax \crthick
\tt\bs multispan\lb{\it n}\rb\relax 
        | \para{Makes the next entry span the next $n$
        columns, where $n$ is an integer, $n>0$.
        See other notes on {\tt\bs multispan} below.} \cr
\tt\bs omit \relax           
        | \para{This \TeX\ primitive causes the normal
        template for its entry to be omitted, allowing
        the user to do something else with this entry.} \cr
\tt\bs para\lb{\it text}\rb \relax
        | \para{Formats {\it text} into a neat little
        paragraph like this one.  The width of the
        paragraph produced is determined by the dimension 
        {\tt\bs parasize}.  The default is 4 inches.  } \cr
\tt\bs parasize=\meta{dimen} \relax
        | \para{Sets the width of paragraphs produced
        with the {\tt\bs para} macro. } \cr
\tt\bs TableItem\lb\#\rb\relax     
        | \para{Used in the standard template, this
        macro centers its argument in the column.  The
        user can redefine it for special effects.} \cr
\tt\bs bigitem\lb\#\rb\relax     
        | \para{Use this for something that would normally
        not fit in one line of a table to make the spacing
        between rows large enough for this item.} \cr
\tt\bs vctr\lb\#\rb\relax     
        | \para{Centers the item {\it vertically} so that
        it can appear between two rows.}\cr
\tt\bs centeredtables\relax  
        | \para{Turns table centering on.  Each table
        will be centered left-to-right on the page.
        This is the default.} \cr
\tt\bs noncenteredtables\relax
        | \para{Turns table centering off.  Each table
        is returned as an {\tt\bs hbox}, and it is up
        to the user to place it as desired.} \cr
\vtop{\noindent\hsize=1.4in\baselineskip=15pt
\tt\bs tableinfotrue \hfil\break
\tt\bs tableinfofalse\hfil}\relax
        | \para{Turns on or off the diagnostic message telling
        you how many rows and columns were found in the
        table. }\cr
\tt\bs thicksize=\meta{dimen} \relax
        | \para{This dimension specifies the thickness
        of the thick rules in the table.  The default
        size is 1.5 points.} \cr
\tt\bs thinsize=\meta{dimen} \relax
        | \para{This dimension specifies the thickness
        of thin rules in the table.  The default
        size is 0.8 points.} \cr
\tt\bs tablewidth=\meta{dimen} \relax
        | \para{Specifies how wide to make the next
        table.  If not specified, the table is made to
        its natural width.  This value is reset
        following the construction of each table.} 
\endruledtable
\vskip 0pt plus 1fil\relax
\endtable

Tables \use{Tb.tablemac;a} and \use{Tb.tablemac;b} summarize the
most important commands for making ruled tables.
\medskip

  Finally we can discuss how you can change how each column of
a table is constructed.  The macros which build the table take
each entry and pass it to a macro called |\TableItem|.  The
default definition of |\TableItem| is:
\TeXexample
\def\TableItem#1{%  
   \hfil\tablespace % left glue
   #1\relax         % the item
   \tablespace\hfil}% right glue
|endTeXexample
\noindent
The |\hfil| glue on both sides of the argument causes the item to be
centered in the column, while |\tablespace| (which defaults to |\quad|)
insures that there will be at least some amount of space between the
item and the vertical rules on each side.  You can change the definition
of |\TableItem| to suit your own purpose.  The simplest modification is
to omit the |\hfil| on the left or right so that each entry is right or
left justified.  This is so commonly used that saying
|\RightJustifyTables| or |\LeftJustifyTables| makes the appropriate
change for you.  Saying |\NoJustifyTables| restores |\TableItem| to its
original centering function.

  Since |\TableItem| is used to create every column of the table you
can't use it to modify a single column.  To justify just one column you
can simply put |\hfill| to the left or right of each item in the column,
since 
|\hfill| is infinitely more stretchy
than |\hfil|.
With a little more work it is possible to design special or unusual
tables by redefining the ``preamble'' of the table.  This is possible
because |\ruledtable| uses |\halign| with a preamble
called |\TablePreamble|.  The default
definition of |\TablePreable| is:
\TeXexample
\def\TablePreamble{%                    % \ruledtable preamble
   \linecount                           % count this line
   \TableItem{####}%                    % the first item
   \plaintab\plaintab                   % && means repeat this
   \TableItem{####}%                    % the subsequent items
   \plaincr}%                           % end of preamble
|endTeXexample
\noindent
The syntax for |\TablePreamble| is like an
|\halign| preamble in Plain \TeX\, but with |&| replaced by |\plaintab|,
|\cr| replaced by |\plaincr|, and |#| replaced by |####|.  If you have
read this far and want to try changing |\TablePreable| then you should
read the source code and the comments that go with it in the file
|ruled.tex.|

As a final note we point out that it is also possible for you to create
your own column separators with the macro |\nextcolumn|.  This macro
takes
a single argument which is used to separate one column of the table from
another. Thus for example, the |\dbl| macro for creating a double
vertical rule between columns is defined as:
\TeXexample
\def\dbl{%                               
   \nextcolumn{\vrule width\thinsize     
   \hskip\thinsize\vrule width\thinsize}}
|endTeXexample