% Save file as: LONGTABLE.TEX          Source: FILESERV@SHSU.BITNET  
% Document Type: LaTeX
% Master File: longtable.tex

\documentstyle[longtable]{article}
\title{Some notes on the longtable environment}
\author{David Carlisle}
\date{17/6/1991}

%\setlongtables

\LTleft=\parindent
\LTright=\fill
\LTchunksize=10

\begin{document}

\maketitle

\listoftables


\section{Introduction}
{\tt longtable.sty} defines a new environment, {\tt longtable}, which has
most of the features of the {\tt tabular} environment, but produces tables
which may be broken by \TeX's standard page-breaking algorithm. It also
shares some features with the {\tt table} environment. In particular it
uses the same counter, {\tt table}, and has a similar \verb|\caption| command.
The \verb|\listoftables| command lists tables produced by either the {\tt
table} or {\tt longtable} environments.


\begin{table}
\centering
\begin{tabular}{||l|l|l||}
\hline\hline
A&tabular&environment\\
\hline
within&a&table\\
\hline\hline
\end{tabular}
\caption{A floating table}
\end{table}



\begin{longtable}{|r|l|}
\caption[An optional caption (for the list of tables)]{A long table\label{long}}
\endhead
\hline
Tables produced by {\tt longtable}&always\\
start on a new page. Columns are& specified\\
in the same way as in the {\tt tabular}&environment\\
\verb"{|r|l|}" in this&case.\\
The \verb|\\| command may take an optional&argument.\\[10pt]
See the effect of \verb|\\[10pt]| &?\\
Also \verb|\hline| may be used,  as in &{\tt tabular}.\\
\hline\hline
If a page break occurs &at a \verb|\hline|\\
then a line is drawn& at the\\
bottom of  one page and at the top of&the next.\\
As {\tt longtable} always starts at&the top of a new page,\\
the argument&\verb|[t] [b] [c]| of {\tt tabular}\\
can not be used.&The optional argument\\
may be one of \verb|[l] [r] [c]|& to specify\\
whether the  table should be&adjusted\\
to the left, right &or centrally.\\
\hline
\end{longtable}

\section{Chunk Size}
In order to \TeX\ multi-page tables, it is necessary to break up the
table in to smaller chunks, so that \TeX\ does not have to keep everything
in memory at one time. By default {\tt longtable} uses 20 rows per chunk,
but this can be set by the user, with eg, \verb|\LTchunksize=10|. These
chunks do not affect page breaking, thus if you are using a \TeX\ with a
lot of memory, you can set \verb|\LTchunksize| to be several pages of the
table. \TeX\ will run faster with a large \verb|\LTchunksize|, and it may
be able to calculate slightly better widths for the columns, however If
necessary {\tt longtable} can work with \verb|\LTchunksize=1|, in which
case the memory taken up is negligable. Note that if you use the commands for
putting a heading at the top of the page (see below), the \verb|\LTchunksize|
must be at least as large as the number of rows in the heading.

This document specifies \verb|\LTchunksize=10|. If you look at the previous
table, you will see that the two halves of the table do not line up.
Also \LaTeX\ will have printed a warning that the column widths had changed.
 {\tt longtable} writes information on to the {\tt .aux} file, so that it can
line up the different chunks, however it does not use this information
unless a \verb|\setlongtables| command is given before the table starts. It
is best not to use this command until the document is nearly complete, as
otherwise {\tt longtable} will leave enough room in each column for the
widest entry {\it in all previous versions\/}. (At least since the {\tt
.aux} file was last removed).
If you look at the preamble to this document you will see a line
\verb|%\setlongtables|. Delete the \verb|%|, and re-\LaTeX\ the document.
All the tables should now line up perfectly. (You may need to \LaTeX\ the
document twice if the {\tt .aux} file has been destroyed).
%\def\arraystretch{1.1}


\begin{longtable}{||l|l|l||p{1in}@{*}}
\caption{A longer table}\\
\hline\hline
\multicolumn{3}{||c||}{This part appears at the top of the first page}& (see)\\
\sc First&\sc Second&\sc Third&\sc Fourth\\
\hline\hline
\endfirsthead
\caption[]{(continued)}\\
\hline\hline
\multicolumn{3}{||c||}{This part appears at the top every other page}& (see)\\
\bf First&\bf Second&\bf Third&\bf Fourth\\
\hline\hline
\endhead
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
a &line & like: &
    \begin{flushright} This last column is a ``p'' column so this
    ``row'' of the table can take up several lines. Note however that \TeX\
    will  never break a page within such a row. Page breaks only occur
    between rows of the table or at \verb|\hline| commands.
    \end{flushright}\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\[20pt]
The line& above &ended with \verb|\\[20pt]|\\
\hline
That& was a &\verb|\hline|&.\\
\hline\hline
That& was a &\verb|\hline\hline|&.\\
\multicolumn{4}{||c||}%
{This is a \tt \char`\\multicolumn\char`{4\char`}\char`{||c||\char`}}\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
\bf A&\bf New&\bf Page&\bf ( It works! )\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
\hline\hline
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
\hline\hline
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
lots & of & lines & like this\\
\hline\hline
\end{longtable}

\section{Captions and Headings}
At the start of the table one may specify lines which are to appear at the
top of every page (under the headline,
but before the other lines of the table).
The lines are entered as normal, but the last \verb|\\| command is replaced
by a \verb|\endhead| command. If the first page should have a different
heading, then this should be entered first, and terminated with the
\verb|\endfirsthead| command. In this case the two headings should be of
roughly equal height, as {\tt longtable} leaves the same amount of room on
each page for the heading. The \verb|\LTchunksize| should be at least as
large as the number of rows in the heading. There is also an \verb|\endfoot|
command which is used in the same way to specify rows (or an \verb|\hline|)
to appear at the bottom of each page.

The \verb|\caption{...}| command is essentially equivalent to\\
\verb|\multicolumn{n}{c}{\parbox{\LTcapwidth}{...}}|\\
where {\tt n} is the number of columns of the table. You may set the
width of the caption with a command such as \verb|\LTcapwidth=3in| in the
preamble of your document.
The default is 4in. \verb|\caption| also
writes the information to produce an entry in the list of tables. As with
the \verb|\caption| command in the {\tt figure} and {\tt table}
environments, an optional argument specifies the text to appear in the list
of tables if this is different from the text to appear in the caption.
Thus the caption for table \ref{long} was specified as
\verb|\caption[An optional caption (for the list of tables)]{A long
 table\label{long}}|.

You may wish the caption on later pages to be different to that on the
first page. In this case put the \verb|\caption| command in the first heading,
 and
 put a subsidiary caption in a \verb|\caption[]| command in the main heading.
If the optional argument to caption is empty, no entry is made in the list of
 figures. Alternatively, if you do not want the table number to be printed
each time, use the \verb|\caption*| command.

You may use the \verb|\label| command so that you can cross reference longtables
with \verb|\ref|. The exact rules on where one may place the \verb|\label| are a
bit \TeX nical, but it is always safe to put it {\it inside\/} the argument of a
\verb|\caption| command.

\section{Kill lines}
Tables \ref{bad} and \ref{good} are set with \verb|\LTchunksize=1| to
 demonstrate a
problem which can arise if multicolumn entries are used. In the first
example, when  {\tt longtable} is determining the widths of the colums
after the first chunk, it has only seen the wide multicolumn entry. This means
that it thinks that the first column is very narow (just containing the
rules and glue specified by \verb"|l|"). All the width of the multicolumn
entry is assumed to be in the second column. (This is a feature of \TeX's
primitive \verb|\halign| command.) {\tt longtable} then passes the
information that there is a wide second column to the second chunk, with
the result that the final table is much to wide.

There are two solutions to this problem, firstly one could increase the
chunk size, so that {\tt longtable} saw the wide entry in the first column in the
same chunk as the \verb|\multicolumn| command. The second solution is to
use a \verb|\kill| row. If a row ends
in \verb|\kill| rather than \verb|\\|, then it is used in determining the
column widths, but it does not appear in the final table. Thus we just need
to put a row with a wide first column before the \verb|\multicolumn| row,
and then \verb|\kill| it. This is demonstrated in the final table.

\verb|\kill| ends the current chunk, and so any \verb|\kill|
lines that occur in a heading must be {\it before\/} all other lines, as
the headings must be typeset in one chunk.

\bigskip

\vbox{
\LTchunksize=1
\begin{longtable}[c]{|l|l|}
\caption{A bad example\label{bad}}\\
\hline
\multicolumn{2}{|c|}{A wide multicolumn entry}\\
A wide column in a different chunk&narrow\\
\hline
\end{longtable}

\bigskip

Note that it is not normally possible to have two {\tt longtable}s
on the same page. Unless you are trying to demonstrate some features of the
{\tt longtable} environment without wasting too much paper, this should not
be necessary. You can always use \LaTeX's {\tt tabular} environment for small
tables.

\bigskip

\begin{longtable}[c]{|l|l|}
A wide column in a different chunk&narrow\kill
\caption{A good example\label{good}}\\
\hline
\multicolumn{2}{|c|}{A wide multicolumn entry}\\
A wide column in a different chunk&narrow\\
\hline
\end{longtable}
}

\section{Adjustment}
The last two tables also show the use of the optional argument. They are
set with \verb|\begin{longtable}[c] ...| specifying that the table should
be centred. The other options are \verb|[r]| \verb|[l]|, for right and left
adjustment, respectively. Normally centering is the default, but this
document specifies
\begin{verbatim}
\LTleft=\parindent
\LTright=\fill
\end{verbatim}
in the preamble, which means that the tables are set flush left, but
indented by the usual paragraph indentation. Any lengths can be specified
for these two parameters, but at least one of them should be a rubber
length so that it fills up the width of the page, unless rubber lengths are
added between the columns using the \verb|\extracolumnsep| command.

\section{Compatibility with other options}
{\tt longtable} should work with the twoside and twocolumn options of the
standard styles, although it always switches to one column mode when seting
the tables. It should also work with many style files which add extra
options to \LaTeX's column specifiers. In particular this version does
work with F. Mittelbach's array.sty.

\section{Summary}
\small
\begin{tabular}{@{}l@{\hspace{4pt}}l@{}}
\multicolumn{2}{c}{\bf Parameters}\\
\hline
\tt\char`\\LTleft&Glue to the left of the table. Default {\tt\char`\\fill}.\\
\tt\char`\\LTright&Glue to the right of the table. Default {\tt\char`\\fill}.\\
\tt\char`\\LTchunksize&The number of rows per chunk. Default 20.\\
\tt\char`\\LTcapwidth&The width of a parbox containing the caption. Default 4in.\\[5pt]
\multicolumn{2}{c}{\bf Setlongtables}\\
\hline
\tt\char`\\setlongtables&Use column widths from the previous run.\\[5pt]
\multicolumn{2}{c}{\bf Optional arguments to \tt\char`\\begin\char`\{longtable\char`\}}\\
\hline
\it none&Position as specified by {\tt\char`\\LTleft} and {\tt\char`\\LTright}, usually centre.\\
\tt[c]& Centre the table.\\
\tt[l]& Place the table flush left.\\
\tt[r]
& Place the table flush right.\\[5pt]
\multicolumn{2}{c}{\bf Commands available inside \tt longtable}\\
\hline
\tt\char`\\endhead&Specifies rows to appear at the top of every page.\\
\tt\char`\\endfirsthead&Specifies rows to appear at the top the first page.\\
\tt\char`\\endfoot&Specifies rows to appear at the bottom of every page.\\
\tt\char`\\kill&Row is `killed', but is used in calculating widths.\\
\tt\char`\\caption\char`\{foo\char`\}&Caption ``Table ?: foo'', and a ``foo'' entry in the list of tables.\\
\tt\char`\\caption[bar]\char`\{foo\char`\}&Caption ``Table ?: foo'', and a ``bar'' entry in the list of tables.\\
\tt\char`\\caption[]\char`\{foo\char`\}&Caption ``Table ?: foo'', but no entry in the list of tables.\\
\tt\char`\\caption*\char`\{foo\char`\}&Caption ``foo'', but no entry in the list of tables.
\end{tabular}


\end{document}
