/
longtable.dtx
2147 lines (2146 loc) · 70.1 KB
/
longtable.dtx
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
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% \iffalse meta-comment
%
% Copyright 1993-2014
%
% The LaTeX3 Project and any individual authors listed elsewhere
% in this file.
%
% This file is part of the Standard LaTeX `Tools Bundle'.
% -------------------------------------------------------
%
% It may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% 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.3c or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% The list of all files belonging to the LaTeX `Tools Bundle' is
% given in the file `manifest.txt'.
%
% \fi
% \iffalse
%% File: longtable.dtx Copyright (C) 1990-2001 David Carlisle
%
%<*dtx>
\ProvidesFile{longtable.dtx}
%</dtx>
%<package>\NeedsTeXFormat{LaTeX2e}[1995/06/01]
%<package>\ProvidesPackage{longtable}
%<driver> \ProvidesFile{longtable.drv}
% \fi
% \ProvidesFile{longtable.dtx}
[2014/10/28 v4.11 Multi-page Table package (DPC)]
%
% \iffalse
%<*driver>
\documentclass{ltxdoc}
\usepackage{longtable}
\begin{document}
\DocInput{longtable.dtx}
\end{document}
%</driver>
% \fi
%
% \GetFileInfo{longtable.dtx}
% \title{The \textsf{longtable} package\thanks{This file
% has version number \fileversion, last
% revised \filedate.}}
% \author{David Carlisle\thanks{The new algorithm for aligning `chunks'
% of a table used in version 4 of this package was devised coded
% and documented by David Kastrup.}}
% \date{\filedate}
%
% \let\package\textsf
% \let\env\textsf
% \providecommand\finalclearpage{\clearpage}
%
% \MaintainedByLaTeXTeam{tools}
% \maketitle
%
% \begin{abstract}
% This package defines the \env{longtable} environment, a multi-page
% version of \env{tabular}.
% \end{abstract}
%
% \DeleteShortVerb{\|}
% \MakeShortVerb{\"}
%
% \changes{v0.00}{1989/11/06}
% {`Version 0' distributed as longtab.sty
% always used just one chunk for the whole table}
%
% \changes{v1.00}{1990/12/20}
% {Initial version}
%
% \changes{v2.00}{1991/06/17}
% {Support NFSS and array.sty}
%
% \changes{v3.00}{1992/03/16}
% {New implementation. tables may now start anywhere on the page.}
%
% \changes{v3.01}{1992/04/06}
% {(Michel Goossens) If a chunk ends on a line in which the first
% entry is empty, weird errors occur. Added special begin and end
% groups, (\cs{ifnum}0 ) stuff as explained in Appendix D.}
%
% \changes{v3.02}{1992/04/09}
% {(Michel Goossens) Longtable fails if the table counter is reset
% during a document. Now use an internal counter, but still
% increment table so \cs{caption} and \cs{label} work out right.}
%
% \changes{v3.03}{1992/06/25}
% {Add \cs{@ifundefined\{reset@font\}} so that the documentation may
% be processed with old versions of \LaTeX.}
% \changes{v3.03}{1992/06/25}
% {Modify the treatment of \cs{d@llar} to match the new versions of
% Mittelbach's array.sty (array.sty v2.0h)}
%
% \changes{v3.04}{1992/11/12}
% {(Jean-Pierre Drucbert) Longtable failed when used with
% \cs{includeonly}.}
% \changes{v3.04}{1992/11/12}
% {Fix bug which stopped \cs{kill} working correctly in headings.}
% \changes{v3.04}{1992/11/12}
% {(Graham Gough) Made \cs{setlongtables} issue a warning message.}
% \changes{v3.04}{1992/11/12}
% {(Sebastian Rahtz) longtable ran out of memory on really long
% tables. Another bug introduced in V3.}
%
% \changes{v3.05}{1992/11/20}
% {(Juergen Peus) Table was hard coded into the captions, Now the
% captions use \cs{fnum@table}, so \cs{tablename} will be used.}
%
% \changes{v3.06}{1993/01/21}
% {(Ingo Hoffmann) longtable fails with letter style.
% The table counter is not defined, and the .aux file is not used in
% the same way. This version will use a .lta file for letter style.}
%
% \changes{v3.07}{1993/06/09}
% {Allow the \LaTeX\ syntax \cs{setcounter}\{LTchunksize\}\{10\}}
%
% \changes{v3.08}{1993/06/09}
% {Update for \LaTeXe}
%
% \changes{v3.09}{1994/03/15}
% {New ltxdoc style}
%
% \changes{v3.11}{1994/05/22}
% {Option handling added, new style errors and warnings}
%
% \changes{v3.12}{1994/06/30}
% {Remove special letter class handling from v3.06, not needed for
% new letter class}
%
% \changes{v4.00}{1996/04/08}
% {(DK) New algorithm to align chunks devised and coded by David
% Kastrup}
%
% \changes{v4.02}{1996/04/16}
% {(DPC/DK) documentation improvements}
%
% \changes{v4.06}{1997/06/28}
% {(DK) new email address}
%
% \CheckSum{1045}
%
%
% \makeatletter
% \def\@oddfoot{\normalfont\rmfamily\dotfill Page \thepage\dotfill}
% \def\@oddhead{\dotfill{\normalfont\ttfamily longtable.sty}\dotfill}
% \def\ps@titlepage{\let\@oddhead\@empty}
% \makeatother
%
%
% \setlength\LTleft\parindent
% \setlength\LTright\fill
% \setcounter{LTchunksize}{10}
%
% \def\v{\char`}
%
% ^^A \vbox to 100pt makes the page breaks the same on the first run.
% \changes{v3.08}{1993/06/09}
% {No need to use \cs{vbox} with \LaTeXe\ minipage}
% \noindent\begin{minipage}[t][130pt]{\textwidth}
% \listoftables
% \end{minipage}
%
% \section{Introduction}
%
% The \package{longtable} package defines a new environment,
% \DescribeEnv{longtable}
% \env{longtable}, which has most of the features of the \env{tabular}
% environment, but produces tables which may be broken by \TeX's
% standard page-breaking algorithm. It also shares some features with
% the \env{table} environment. In particular it uses the same counter,
% \texttt{table}, and has a similar "\caption" command. Also, the
% standard "\listoftables" command lists tables produced by either the
% \env{table} or \env{longtable} environments.
%
% The following example uses most of the features of the \env{longtable}
% environment. An edited listing of the input for this example appears
% in Section~\ref{listing}.
%
% \textbf{Note:} Various parts of the following table will
% \textbf{not} line up correctly until this document has been run
% through \LaTeX\ several times. This is a characteristic feature of
% this package, as described below.
%
% \begin{longtable}{@{*}r||p{1in}@{*}}
% KILLED & LINE!!!! \kill
% \caption
% [An optional table caption (used in the list of tables)]
% {A long table\label{long}}\\
% \hline\hline
% \multicolumn{2}{@{*}c@{*}}%
% {This part appears at the top of the table}\\
% \textsc{First}&\textsc{Second}\\
% \hline\hline
% \endfirsthead
% \caption[]{(continued)}\\
% \hline\hline
% \multicolumn{2}{@{*}c@{*}}%
% {This part appears at the top of every other page}\\
% \textbf{First}&\textbf{Second}\\
% \hline\hline
% \endhead
% \hline
% This goes at the&bottom.\\
% \hline
% \endfoot
% \hline
% These lines will&appear\\
% in place of the & usual foot\\
% at the end& of the table\\
% \hline
% \endlastfoot
% \env{longtable} columns are specified& in the \\
% same way as in the \env{tabular}& environment.\\
% "@{*}r||p{1in}@{*}"& in this case.\\
% Each row ends with a& "\\" command.\\
% The "\\" command has an& optional\\
% argument, just as in& the\\
% \env{tabular}&environment.\\[10pt]
% See the effect of "\\[10pt]"&?\\
% Lots of lines& like this.\\
% Lots of lines& like this.\\
% Lots of lines& like this.\\
% Lots of lines& like this.\\
% Also "\hline" may be used,& as in \env{tabular}.\\
% \hline
% That was a "\hline"&.\\
% \hline\hline
% That was "\hline\hline"&.\\
% \multicolumn{2}{||c||}%
% {This is a \ttfamily\v\\multicolumn\v{2\v}\v{||c||\v}}\\
% If a page break occurs at a "\hline" then& a line is drawn\\
% at the bottom of one page and at the& top of the next.\\
% \hline
% The "[t] [b] [c]" argument of \env{tabular}& can not be used.\\
% The optional argument may be one of& "[l] [r] [c]"\\
% to specify whether the table should be& adjusted\\
% to the left, right& or centrally.\\
% \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.\\
% 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.\\
% Some lines may take up a lot of space, like this: &
% \raggedleft 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 "\hline" commands.
% \tabularnewline
% 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
% Lots\footnote{This is a footnote.} of lines& like this.\\
% Lots of lines& like this\footnote{\env{longtable} takes special
% precautions, so that footnotes may also be used in `p' columns.}\\
% \hline
% Lots of lines& like this.\\
% Lots of lines& like this.
% \end{longtable}
%
% \section{Chunk Size}
%
% \DescribeMacro{LTchunksize}
% In order to \TeX\ multi-page tables, it is necessary to break up the
% table into smaller chunks, so that \TeX\ does not have to keep
% everything in memory at one time. By default \env{longtable} uses 20
% rows per chunk, but this can be set by the user, with e.g.,
% "\setcounter{LTchunksize}{10}".\footnote
% {You can also use the plain \TeX\ syntax
% {\ttfamily\v\\LTchunksize=10.}}
% These chunks do not affect page breaking,
% thus if you are using a \TeX\ with a lot of memory, you can set
% "LTchunksize" to be several pages of the table. \TeX\ will run
% faster with a large "LTchunksize". However, if necessary,
% \env{longtable} can work with "LTchunksize" set to 1, in which case
% the memory taken up is negligible.
% Note that if you use the commands for setting the table head or foot
% (see below), the "LTchunksize" must be at least as large as the
% number of rows in each of the head or foot sections.
%
% This document specifies "\setcounter{LTchunksize}{10}". If you look
% at the previous table, after the \emph{first} run of \LaTeX\ you will
% see that various parts of the table do not line up.
% \LaTeX\ will also have printed a warning that the column
% widths had changed. \env{longtable} writes information onto the
% ".aux" file, so that it can line up the different chunks.
% Prior to version~4 of this package, this information was not used
% unless a "\setlongtables" command was issued, however, now the
% information is always used, using a new algorithm\footnote{Due to
% David Kastrup.} and so "\setlongtables" is no longer needed. It is
% defined (but does nothing) for the benefit of old documents that
% use it.
%
% \begin{table}
% \centering
% \begin{tabular}{||l|l|l||}
% \hline\hline
% A&\env{tabular}& environment\\
% \hline
% within&a floating&\env{table}\\
% \hline\hline
% \end{tabular}
% \caption{A floating table}
% \end{table}
%
% \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).
% \DescribeMacro{\endhead}
% The lines are entered as normal, but the last "\\" command is
% replaced by a "\endhead" command.
% \DescribeMacro{\endfirsthead}
% If the first page should have a different heading, then this should be
% entered in the same way, and terminated with the "\endfirsthead"
% command. The "LTchunksize" should be at least as large as the
% number of rows in the heading.
% \DescribeMacro{\endfoot}
% There are also "\endfoot" and "\endlastfoot"
%\DescribeMacro{\endlastfoot}
% commands which are used in the same way (at the \emph{start} of the
% table) to specify rows (or an "\hline") to appear at the bottom of
% each page. In certain situations, you may want to place lines which
% logically belong in the table body at the end of the \env{firsthead},
% or the beginning of the \env{lastfoot}. This helps to control which
% lines appear on the first and last page of the table.
%
% \DescribeMacro{\caption}%
% The "\caption{...}" command is essentially equivalent to\\
% "\multicolumn{n}{c}{\parbox{\LTcapwidth}{...}}"\\
% where \texttt{n} is the number of columns of the table. You may set
% the width of the caption with a command such as
% "\setlength{\LTcapwidth}{2in}"
% in the preamble of your document. The default is 4in. "\caption" also
% writes the information to produce an entry in the list of tables. As
% with the "\caption" command in the \env{figure} and \env{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
% {\ttfamily
% "\caption"[An optional table caption
% (used in the list of tables)]\v{A long
% table"\label{long}"\v}}.
%
% You may wish the caption on later pages to be different to that on the
% first page. In this case put the "\caption" command in the first
% heading, and put a subsidiary caption in a "\caption[]" command in
% the main heading. If the optional argument to "\caption" is empty,
% no entry is made in the list of tables. Alternatively, if you do not
% want the table number to be printed each time, use the "\caption*"
% command.
%
% The captions are set based on the code for the \package{article}
% class.
% If you have redefined the standard "\@makecaption" command to produce
% a different format for the captions, you may
% need to make similar changes to the \package{longtable} version,
% "\LT@makecaption". See the code section for more details.
%
% A more convenient method of customising captions is given by the
% \package{caption(2)} package, which provides commands for customising
% captions, and arranges that the captions in standard environments, and
% many environments provided by packages (including \package{longtable})
% are modified in a compatible manner.
%
% You may use the "\label" command so that you can cross reference
% \env{longtable}s with "\ref". Note however, that the "\label" command
% should not be used in a heading that may appear more than once. Place
% it either in the \env{firsthead}, or in the body of the table. It
% should not be the \emph{first} command in any entry.
%
% \section{Multicolumn entries}
%
% The "\multicolumn" command may be used in \env{longtable} in exactly
% the same way as for \env{tabular}. So you may want to skip this
% section, which is rather technical, however coping with "\multicolumn"
% is one of the main problems for an environment such as
% \env{longtable}. The main effect that a user will see is that
% certain combinations of "\multicolumn" entries will result in a
% document needing more runs of \LaTeX\ before the various `chunks' of
% a table align.
%
% The examples in this section are set with "LTchunksize" set to the
% minimum value of one, to demonstrate the effects when "\multicolumn"
% entries occur in different chunks.
%
% \begin{table}[!htp]
% \begin{center}
% \LTchunksize=1
% \makeatletter
%
% \global\let\LT@save@row\relax
% \let\LT@warn\@gobble
% \let\LT@final@warn\relax
%
% \newcommand\ltexample[1]{
% \stepcounter{LT@tables}
% \expandafter\let\csname LT@\romannumeral\c@LT@tables\endcsname
% \LT@save@row
% \addtocounter{LT@tables}{-1}
% \begin{longtable}{|c|c|c|}
% \caption{A difficult {\cs{multicolumn}} combination:
% pass #1\label{pass#1}}\\
% \hline
% 1&2&3\\
% \multicolumn{3}{|c|}{wide multicolumn spanning 1--3}\\
% \multicolumn{2}{|c|}{multicolumn 1--2}&3\\
% wide 1&2&3\\
% \hline
% \end{longtable}
% }
%
% \ltexample{1}
%
% \ltexample{2}
%
% \ltexample{3}
%
% \ltexample{4}
%
% \end{center}
% \end{table}
%
% Consider Table~\ref{pass1}.
% In the second chunk, \env{longtable} sees the wide
% multicolumn entry. At this point it thinks that the first two
% columns are very narrow. All
% the width of the multicolumn entry is assumed to be in the
% third column. (This is a `feature' of \TeX's primitive "\halign"
% command.) \env{longtable} then passes the information that there
% is a wide third column to the later chunks, with the result that the
% first pass over the table is too wide.
%
% If the `saved row' from this first pass was re-inserted into the
% table on the next pass, the table would line up in two passes, but
% would be much two wide.
%
% \DescribeMacro{\kill}%
% The solution to this problem used in Versions 1~and~2, was to use a
% "\kill" line. If a line is "\kill"ed, by using "\kill" rather than
% "\\" at the end of the line, it is used in calculating
% column widths, but removed from the final table. Thus entering
% "\kill"ed copies of the last two rows before the wide multicolumn
% entry would mean that "\halign" `saw' the wide entries in the first
% two columns, and so would not widen the third column by so much to
% make room for the multicolumn entry.
%
% In Version~3, a new solution was introduced. If the saved row in
% the ".aux" file was not being used, \env{longtable} used a special
% `draft' form of "\multicolumn", this modified the definition, so the
% spanning entry was never considered to be wider than the columns it
% spanned. So after the first pass, the ".aux" file stored the
% widest normal entry for each column, no column was widened due to
% "\span"ned columns. By default \env{longtable} ignored the ".aux"
% file, and so each run of \LaTeX\ was considered a first pass. Once the
% "\setlongtables" declaration was given, the saved row in the ".aux"
% file, and the proper definition of "\multicolumn" were used. If any
% "\multicolumn" entry caused one of the columns to be widened, this
% information could not be passed back to earlier chunks, and so the
% table would not correctly line up until the third pass. This algorithm
% always converged in three passes as described above, but in examples
% such as the ones in Tables \ref{pass1}--\ref{pass4}, the final
% widths were not optimal as the width of column~2, which is
% determined by a "\multicolumn" entry was not known when the final
% width for column~3 was fixed, due to the fact that \emph{both}
% "\multicolumn" commands were switched from `draft' mode to `normal'
% mode at the same time.
%
% Version~4 alleviates the problem considerably.
% The first pass of the table will
% indeed have the third column much too wide. However, on the next pass
% \env{longtable} will notice the error and reduce the column width
% accordingly. If this has to propagate to chunks before the
% "\multicolumn" one, an additional pass will, of course, be
% needed. It is possible to construct tables where this rippling up of
% the correct widths takes several passes to `converge' and produce a
% table with all chunks aligned. However in
% order to need many passes one needs to construct a table with
% many overlapping "\multicolumn" entries, all being wider than the
% natural widths of the columns they span, and all occurring in
% different chunks. In the typical case the algorithm will converge
% after three or four passes, and, the benefits of not needing to edit
% the document before the final run to add "\setlongtables", and the
% better choice of final column widths in the case of multiple
% "\multicolumn" entries will hopefully more than pay for the extra
% passes that may possibly be needed.
%
% So Table~\ref{pass1} converges after 4~passes, as seen in
% Table~\ref{pass4}.
%
% You can still speed the convergence by introducing judicious "\kill"
% lines, if you happen to have constellations like the above.
%
% If you object even to \LaTeX-ing a file twice, you should
% make the first line of
% every \env{longtable} a "\kill" line that contains the widest entry
% to be used in each column. All chunks will then line up on the first
% pass.
%
% \section{Adjustment}
%
% The optional argument of \env{longtable} controls the
% horizontal alignment of the table. The possible options are "[c]",
% "[r]" and "[l]", for centring,
% right and left adjustment, respectively.
% \DescribeMacro{\LTleft}
% Normally centring is the default, but this document specifies
% \DescribeMacro{\LTright}
%\begin{verbatim}
% \setlength\LTleft\parindent
% \setlength\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
% "\extracolsep" command.
% For instance
%\begin{verbatim}
% \begin{tabular*}{\textwidth}{@{\extracolsep{...}}...}
%\end{verbatim}
% produces a full width table, to get a similar effect with
% \env{longtable} specify
%\begin{verbatim}
% \setlength\LTleft{0pt}
% \setlength\LTright{0pt}
% \begin{longtable}{@{\extracolsep{...}}...}
%\end{verbatim}
%
% \section{Changes}
%
% This section highlights the major changes since version~2. A more
% detailed change log may be produced at the end of the code listing
% if the "ltxdoc.cfg" file specifies
%\begin{verbatim}
% \AtBeginDocument{\RecordChanges}
% \AtEndDocument{\PrintChanges}
%\end{verbatim}
%
% Changes made between versions 2 and 3.
% \begin{itemize}
% \item The mechanism for adding the head and foot of the table has been
% completely rewritten. With this new mechanism, \env{longtable} does
% not need to issue a "\clearpage" at the start of the table, and so the
% table may start half way down a page. Also the "\endlastfoot" command
% which could not safely be implemented under the old scheme, has been
% added.
% \item \env{longtable} now issues an error if started in the scope of
% "\twocolumn", or the \env{multicols} environment.
% \item The separate documentation file "longtable.tex" has been
% merged with the package file, "longtable.dtx" using Mittelbach's
% \package{doc} package.
% \item Support for footnotes has been added. Note however that
% "\footnote" will not work in the `head' or `foot' sections of the
% table. In order to put a footnote in those sections (e.g., inside a
% caption), use "\footnotemark" at that point, and "\footnotetext"
% anywhere in the table \emph{body} that will fall on the same page.
% \item The treatment of "\multicolumn" has changed, making
% "\kill" lines unnecessary, at the price of sometimes requiring a
% third pass through \LaTeX.
% \item The "\newpage" command now works inside a \env{longtable}.
% \end{itemize}
%
% Changes made between versions 3 and 4.
% \begin{itemize}
% \item A new algorithm is used for aligning chunks. As well as the
% widest width in each column, \package{longtable} remembers which
% chunk produced this maximum. This allows it to check that the
% maximum is still achieved in later runs. As \package{longtable} can
% now deal with columns shrinking as the file is edited, the
% "\setlongtables" system is no longer needed and is disabled.
%
% \item An extra benefit of the new algorithm's ability to deal with
% `shrinking' columns is that it can give better (narrower) column
% widths in the case of overlapping "\multicolumn" entries in
% different chunks than the previous algorithm produced.
%
% \item The `draft' multicolumn system has been removed, along with
% related commands such as "\LTmulticolumn".
%
% \item The disadvantage of the new algorithm is that it can take more
% passes. The theoretical maximum is approximately twice the length
% of a `chain' of columns with overlapping "\multicolumn" entries,
% although in practice it usually converges as fast as the old
% version. (Which always converged in three passes once
% "\setlongtables" was activated.)
%
% \item "\\*" and "\nopagebreak" commands may be used to control page
% breaking.
%
% \end{itemize}
%
%
% \section{Summary}
%
% ^^A Allow the table to stick into the left margin.
% \setlength{\LTleft}{0pt plus 1fill minus 1fill}
% \setlength{\LTright}{0pt}
%
% \begin{longtable}{@{}l@{\hspace{10pt}}p{.8\linewidth}@{}}
% \caption[A summary of \env{longtable} commands]%
% {\normalsize A summary of \env{longtable} commands}\\
% \multicolumn{2}{c}{\textbf{Parameters}}\\*
% \hline
% "\LTleft"&
% Glue to the left of the table. \hfill("\fill")\\
% "\LTright"&
% Glue to the right of the table. \hfill("\fill")\\
% "\LTpre"&
% Glue before the the table. \hfill("\bigskipamount")\\
% "\LTpost"&
% Glue after the the table. \hfill("\bigskipamount")\\
% "\LTcapwidth"&
% The width of a parbox containing the caption.\hfill(4in)\\
% "LTchunksize"&
% The number of rows per chunk. \hfill(20)\\[5pt]
% \multicolumn{2}{c}{\textbf{Optional
% arguments to} \ttfamily\v\\begin\v{longtable\v}}\\*
% \hline
% \it none& Position as specified by "\LTleft" and "\LTright".\\
% "[c]"& Centre the table.\\
% "[l]"& Place the table flush left.\\
% "[r]"& Place the table flush right.\\[5pt]
% \pagebreak[2]
% \multicolumn{2}{c}{\textbf{Commands
% to end table rows}}\\*
% \hline
% "\\"&
% Specifies the end of a row\\
% "\\"\oarg{dim}& Ends row, then adds vertical space
% (as in the \env{tabular} environment).\\
% "\\*"&
% The same as "\\" but disallows a page break after the row.\\
% "\tabularnewline"&
% Alternative to "\\" for use in the scope of "\raggedright" and
% similar commands that redefine "\\".\\
% "\kill"&
% Row is `killed', but is used in calculating widths.\\
% "\endhead"&
% Specifies rows to appear at the top of every page.\\
% "\endfirsthead"&
% Specifies rows to appear at the top the first page.\\
% "\endfoot"&
% Specifies rows to appear at the bottom of every page.\\
% "\endlastfoot"&
% Specifies rows to appear at the bottom of the last page.\\[5pt]
% \multicolumn{2}{c}{\textbf{\env{longtable} caption commands}}\\*
% \hline
% "\caption"\marg{caption}&
% Caption `Table ?: \meta{caption}', and a `\meta{caption}'
% entry in the list of tables.\\
% "\caption"\oarg{lot}\marg{caption}&
% Caption `Table ?: \meta{caption}', and a `\meta{lot}'
% entry in the list of tables.\\
% "\caption[]"\marg{caption}&
% Caption `Table ?: \meta{caption}',
% but no entry in the list of tables.\\
% "\caption*"\marg{caption}&
% Caption `\meta{caption}', but no entry in the list of tables.\\[5pt]
% \multicolumn{2}{c}{%^^A
% \textbf{Commands available at the start of a row}}\\*
% \hline
% "\pagebreak"&
% Force a page break.\\*
% "\pagebreak"\oarg{val}& A `hint' between 0 and 4
% of the desirability of a break.\\
% "\nopagebreak"& Prohibit a page break.\\*
% "\nopagebreak"\oarg{val}& A `hint' between 0 and 4 of the undesirability
% of a break.\\
% "\newpage"&
% Force a page break.\\[5pt]
% \multicolumn{2}{c}{\textbf{Footnote commands
% available inside \env{longtable}}}\\*
% \hline
% "\footnote"&
% Footnotes, but may not be used in the table head \& foot.\\*
% "\footnotemark"&
% Footnotemark, may be used in the table head \& foot.\\*
% "\footnotetext"&
% Footnote text, use in the table body.\\[5pt]
% \multicolumn{2}{c}{\textbf{Setlongtables}}\\
% \hline
% "\setlongtables"& Obsolete command. Does nothing now.
% \end{longtable}
%
%
% \finalclearpage
% \section{Verbatim highlights from Table \protect\ref{long}}
% \label{listing}
% \begingroup\catcode`\/=0
% \begin{verbatim}
% \begin{longtable}{@{*}r||p{1in}@{*}}
% KILLED & LINE!!!! \kill
% \caption[An optional table caption /ldots]{A long table\label{long}}\\
% \hline\hline
% \multicolumn{2}{@{*}c@{*}}%
% {This part appears at the top of the table}\\
% \textsc{First}&\textsc{Second}\\
% \hline\hline
% \endfirsthead
% \caption[]{(continued)}\\
% \hline\hline
% \multicolumn{2}{@{*}c@{*}}%
% {This part appears at the top of every other page}\\
% \textbf{First}&\textbf{Second}\\
% \hline\hline
% \endhead
% \hline
% This goes at the&bottom.\\
% \hline
% \endfoot
% \hline
% These lines will&appear\\
% in place of the & usual foot\\
% at the end& of the table\\
% \hline
% \endlastfoot
% \env{longtable} columns are specified& in the \\
% same way as in the \env{tabular}& environment.\\
% /ldots
% \multicolumn{2}{||c||}{This is a /ldots}\\
% /ldots
% Some lines may take/ldots&
% \raggedleft This last column is a ``p'' column/ldots
% \tabularnewline
% /ldots
% Lots of lines& like this.\\
% /ldots
% \hline
% Lots\footnote{/ldots} of lines& like this.\\
% Lots of lines& like this\footnote{/ldots}\\
% \hline
% Lots of lines& like this.\\
% /ldots
% \end{longtable}
% \end{verbatim}
% \endgroup
%
% \StopEventually{}
%
% \finalclearpage
% \section{The Macros}
%
% \begin{macrocode}
%<*package>
% \end{macrocode}
%
% \subsection{Initial code}
%
% Before declaring the package options, we must define some defaults
% here.
%
% \begin{macro}{\LT@err}
% The error generating command
% \begin{macrocode}
\def\LT@err{\PackageError{longtable}}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\LT@warn}
% The warning generating command
% \begin{macrocode}
\def\LT@warn{\PackageWarning{longtable}}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\LT@final@warn}
% \changes{v4.04}{1996/05/24}
% {Macro added}
% If any \env{longtable}s have not aligned, generate a warning at the
% end of the run at "\AtEndDocument".
% \begin{macrocode}
\def\LT@final@warn{%
\AtEndDocument{%
\LT@warn{Table \@width s have changed. Rerun LaTeX.\@gobbletwo}}%
\global\let\LT@final@warn\relax}
% \end{macrocode}
% \end{macro}
%
% \subsection{Options}
%
% The first two options deal with error handling. They are compatible
% with the options used by the \texttt{tracefnt} package.
%
% \begin{macro}{errorshow}
% \emph{Only} show errors on the terminal. `warnings' are just sent to
% the log file.
% \changes{v3.14}{1995/04/25}
% {Change string from LT to longtable}
% \begin{macrocode}
\DeclareOption{errorshow}{%
\def\LT@warn{\PackageInfo{longtable}}}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{pausing}
% \changes{v3.14}{1995/04/25}
% {Change string from LT to longtable}
% \changes{v3.15}{1995/06/15}
% {Use single hash for latex/1557}
% Make every warning message into an error so \TeX\ stops.
% May be useful for debugging.
% \begin{macrocode}
\DeclareOption{pausing}{%
\def\LT@warn#1{%
\LT@err{#1}{This is not really an error}}}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{set}
% \begin{macro}{final}
% \changes{v4.01}{1996/04/11}
% {(DPC) make set and final options no op}
% The next options are just alternative syntax for the
% "\setlongtables" declaration.
% \begin{macrocode}
\DeclareOption{set}{}
\DeclareOption{final}{}
% \end{macrocode}
% \end{macro}
% \end{macro}
%
%
% \begin{macrocode}
\ProcessOptions
% \end{macrocode}
%
% \subsection{User Settable Parameters}
%
% \begin{macro}{\LTleft}
% \begin{macro}{\LTright}
% Glue to the left and right of the table, default "\fill" (ie
% centred).
% \begin{macrocode}
\newskip\LTleft \LTleft=\fill
\newskip\LTright \LTright=\fill
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\LTpre}
% \begin{macro}{\LTpost}
% Glue before and after the \env{longtable}. "\bigskip" by default.
% \begin{macrocode}
\newskip\LTpre \LTpre=\bigskipamount
\newskip\LTpost \LTpost=\bigskipamount
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\LTchunksize}
% Chunk size (The number of rows taken per "\halign"). Default 20.
% \begin{macrocode}
\newcount\LTchunksize \LTchunksize=20
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\c@LTchunksize}
% Added in V3.07 to allow the \LaTeX\ syntax
% "\setcounter{LTchunksize}{10}".
% \begin{macrocode}
\let\c@LTchunksize\LTchunksize
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\LTcapwidth}
% Width of the "\parbox" containing the caption. Default 4in.
% \begin{macrocode}
\newdimen\LTcapwidth \LTcapwidth=4in
% \end{macrocode}
% \end{macro}
%
% \subsection{Internal Parameters}
%
% \begin{macro}{\LT@head}
% \begin{macro}{\LT@firsthead}
% \begin{macro}{\LT@foot}
% \begin{macro}{\LT@lastfoot}
% Boxes for the table head and foot.
% \begin{macrocode}
\newbox\LT@head
\newbox\LT@firsthead
\newbox\LT@foot
\newbox\LT@lastfoot
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\LT@cols}
% Counter for number of columns.
% \begin{macrocode}
\newcount\LT@cols
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\LT@rows}
% Counter for rows up to chunksize.
% \begin{macrocode}
\newcount\LT@rows
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\c@LT@tables}
% Counter for the tables, added in V3.02. Previous versions just used
% the \LaTeX\ counter "table", but this fails if "table" is
% reset during a document, eg \package{report} class resets it every
% chapter.
%
% This was changed from "\newcount\LT@tables" in V3.04. \LaTeX\ counters
% are preserved correctly when "\includeonly" is used. In the rest of
% the file "\LT@tables" has been replaced by "\c@LT@tables" without
% further comment.
% \begin{macrocode}
\newcounter{LT@tables}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\c@LT@chunks}
% \changes{v4.00}{1996/04/08}
% {(DK) Chunk counter added}
% We need to count through the chunks of our tables from Version~4 on.
% \begin{macrocode}
\newcounter{LT@chunks}[LT@tables]
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\c@table}
% \begin{macro}{\fnum@table}
% \begin{macro}{\tablename}
% If the "table" counter is not defined (eg in "letter" style), define
% it. (Added in V3.06.)
% \begin{macrocode}
\ifx\c@table\undefined
\newcounter{table}
\def\fnum@table{\tablename~\thetable}
\fi
\ifx\tablename\undefined
\def\tablename{Table}
\fi
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\LT@out}
% In a normal style, "longtable" uses the ".aux" file to record the
% column widths. With "letter.sty", use a separate ".lta" file.
% (Added in V3.06.)
%
% Not needed for new letter class.
%\begin{verbatim}
%\ifx\startlabels\undefined
% \let\@auxout\@auxout
%\else
% {\@input{\jobname.lta}}%
% \newwrite\@auxout
% \immediate\openout\@auxout=\jobname.lta
%\fi
%\end{verbatim}
% \end{macro}
%
% \begin{macro}{\LT@p@ftn}
% Temporary storage for footnote text in a `p' column.
% \begin{macrocode}
\newtoks\LT@p@ftn
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\LT@end@pen}