Chapter 5. Tabular Material

Data is often most efficiently presented in tabular form. TeX uses powerful primitives for arranging material in rows and columns. Because they implement only a low-level, formatting-oriented functionality, several macro packages have been developed that build on those primitives to provide a higher-level command language and a more user-friendly interface.

In LaTeX, two types of environments for constructing tables are provided. Most commonly the tabular environment or its math-mode equivalent, the array environment, is used. However, in some circumstances the tabbing environment might prove useful.

Tables contained within floating environments

Tables typically form large units of the document that must be allowed to “float” so that the document may be paginated correctly. The environments described in this chapter are principally concerned with the table layout. To achieve correct pagination they will often be used within the table environment described in Chapter 6. An exception is the environments for multipage tables described in Section 5.4, which should never be used in conjunction with the LaTeX float mechanism. Be careful, however, not to confuse the tabular environment with the table environment. The former allows material to be aligned in columns, while the latter is a logical document element identifying its contents as belonging together and allowing the material to be floated jointly. In particular, one table environment can contain several tabular environments.

After taking a quick look at the tabbing environment, this chapter describes the extensions to LaTeX’s basic tabular and array environments provided by the array package. This package offers increased functionality, especially in terms of a more flexible positioning of paragraph material, a better control of inter-column and inter-row spacing, and the possibility of defining new preamble specifiers. Several packages build on the primitives provided by the array package to provide specific extra functionality. By combining the features in these packages, you will be able to construct complex tables in a simple way. For example, the tabularx and tabulary packages provide extra column types that allow table column widths to be calculated automatically.

Standard LaTeX tabular environments do not produce tables that may be broken over a page. We give several examples of multipage tables using the supertabular and longtable environments provided by the similarly named packages.

We then briefly look at the use of color in tables and at several packages that give finer control over rules, and the spacing around rules, in tables. Next, we discuss table entries spanning multiple rows, created via the multirow package, and the dcolumn package, which provides a mechanism for aligning columns of figures on a decimal point.

We also discuss the use of footnotes in tables. The threeparttable package provides a convenient mechanism to have table notes and captions combined with a tabular layout.

The final section gives some practical advice on handling nested tables and large entries spanning multiple columns.

Mathematically oriented readers should consult the chapter on advanced mathematics, especially Section 8.2 on page 468, which discusses the alignment structures for equations. Further examples of table layouts may be found in the section on the graphics package, Section 10.3 on page 628.

• The tabbing environment is not as general as the tabular environment. It can be typeset only as a separate paragraph, whereas a tabular environment can be placed anywhere in the text or inside mathematics.

• The tabbing environment can be broken between pages, whereas the standard tabular environment cannot.

• With the tabbing environment the user must specify the position of each tab stop explicitly. With the tabular environment LaTeX can automatically determine the width of the columns.

• Multiple tabbing environments cannot be nested, whereas tabular environments can, thus allowing complex alignments to be realized.

Alternative names for accent commands

Be aware that the usual LaTeX commands for making accents, ', ', and =, are redefined inside the tabbing environment. The accents are available by typing a', a', and a= instead. The - command, which normally signals a possible hyphenation point, is also redefined, but this consideration is not so important because the lines in a tabbing environment are never broken.

A style parameter abbingsep, used together with the ' command, allows text to be typeset at a given distance flush right from the following tab stop. Its default value is set equal to labelsep, which in turn is usually 5pt.

There exist a few common ways to define tab stops—that is, using a line to be typeset, or explicitly specifying a skip to the next tab stop. The kill command may be used to terminate a line that is only used to set tab stops: the line itself is not typeset. The following example demonstrates this, and demonstrates the redefinition of tab stops on the third line.

If you use accents within the definition of a command that may be used inside a tabbing environment you must use the a... forms because the standard accent commands such as ' will be interpreted as tabbing commands, as shown below. You may find it more convenient to use the inputenc package and enter the accented letters directly.

An alternative is provided by the Tabbing package (by Jean-Pierre Drucbert), which provides a Tabbing environment in which the accent commands are not redefined. Instead, the tabbing commands are named TAB'....

The tabbing environment is most useful for aligning information into columns whose widths are constant and known. The following is from Table A.1 on page 855.

The array environment is essentially the math mode equivalent of the tabular environment. The entries of the table are set in math mode, and the default inter-column space is different (as described below), but otherwise the functionality of the two environments is identical.

The tabular* environment has an additional width argument that specifies the required total width of the table. It needs stretchable spaces between columns, that have to be added using extracolsep (see page 246).

Table 5.1 shows the various options available in the cols preamble declaration of the environments in the standard LaTeX tabular family. The array package introduced in the next section extends the list of preamble options.

Style parameters

The visual appearance of the tabular-like environments can be controlled by various style parameters. These parameters can be changed by using the setlength or addtolength commands anywhere in the document. Their scope can be general or local. In the latter case the scope should be explicitly delimited by braces or another environment.

arraycolsep  Half the width of the horizontal space between columns in an array environment (default value 5pt).

abcolsep  Half the width of the horizontal space between columns in a tabular environment (default value 6pt).

arrayrulewidth  The width of the vertical rule that separates columns (if a | is specified in the environment preamble) and the rules created by hline, cline, or vline (default value 0.4pt).

When using the array  package, this width is taken into account when calculating the width of the table (standard LaTeX sets the rules in such a way that they do not affect the final width of the table).

doublerulesep  The width of the space between lines created by two successive || characters in the environment preamble, or by two successive hline commands (default value 2pt).

arraystretch  Fraction with which the inter-row space between normal-sized rows is multiplied. For example, a value of 1.5 would move the rows 50% farther apart. This value is set with enewcommand (default value 1.0).

Table 5.2 shows the new options available in the cols preamble declaration of the environments in the tabular family.

Extra space between rows

Notice the use of the extrarowheight declaration in the second example below. It adds a vertical space of 4pt above each row. In fact, the effect of extrarowheight will be visible only if arraystretch × (extrarowheight + 0.7aselineskip) is larger than the actual height of the cell or, more precisely, in the case of p, m, or b, the height of the first row of the cell.

This consideration is important for tables with horizontal lines because it is often necessary to fine-tune the distance between those lines and the contents of the table. The default value of extrarowheight is 0pt.

Font encoding changes not supported in a >{...} argument

There are few restrictions on the declarations that may be used with the > preamble option. Nevertheless, for technical reasons beyond the scope of this book, it is not possible to change the font encoding for the table column. For example, if the current encoding is not T1, then >{fontencoding{T1}selectfont} does not work. No error message is generated but incorrect characters may be produced at the start of each cell in the column. If a column of text requires a special encoding then the encoding command should be placed explictly at the start of each cell in the column.

The differences between the three paragraph-building options p (the paragraph box is aligned at the top), m (the paragraph box is aligned in the center), and b (the paragraph box is aligned at the bottom) are shown schematically in the following examples.

In columns that have been generated with p, m, or b, the default value of parindent is 0pt. It can be changed with the setlength command as shown in the next example where we indent the first column by 5mm.

The < preamble option was originally developed for the following application: >{$}c<{$} generates a column in math mode in a tabular environment. The use of this type of preamble in an array environment results in a column in LR mode because the additional $s cancel the existing $s.

Making tabular* stretch to the required width

A major use of the ! and @ options is to add rubber length with the extracolsep command so that TeX can stretch the table to the desired width in the tabular* environment. The use of extracolsep in the array package environments is subject to two restrictions: there can be at most one extracolsep command per @ or ! expression, and the command must be directly entered into the @ expression, not as part of a macro definition. Thus, ewcommandef{extracolsep{fill}}, and then later @{ef} in a tabular preamble, does not work, but ewcolumntype{e}{@{extracolsep{fill}}} could be used instead.

When you have a narrow column, you must not only make sure that the first word can be hyphenated, but also consider that short texts are easier to typeset in ragged-right mode (without being aligned at the right margin). This result is obtained by preceding the material with a aggedright command (see Section 3.1.11). This command redefines the line-breaking command \, so we must use the command abularnewline, which is defined in the array package, as in standard LaTeX, to be the original definition of the row-ending \ command of the tabular or array environment. Alternatively, we could have used the arraybackslash command after the aggedright in the third column. This locally redefines \ to end the table row, as shown in Example 5-2-12 on page 249.

As shown in the example below, we can now typeset material inside a tabular environment ragged right, ragged left, or centered and still have control of the line breaks. The first word is now hyphenated correctly, although in the case of the Dutch text, we helped TeX a little by choosing the possible hyphenation points ourselves.

In the example above, @{} has been used to remove the inter-column space between columns 1 and 2. An empty !{} has no effect, as demonstrated between columns 2 and 3. Note that a dash appears in place of the default inter-column space when specified using @{--} between columns 3 and 4, but is placed in the center of the default inter-column space when specified using !{--} between columns 4 and 5.

Using @{} to remove space at the side of the table

A common use of @{} is to remove the space equal to the value of abcolsep (for tabular) that, by default, appears on each side of the table, except when the column specification starts or ends in a |.

This code, however, becomes rather verbose if you often use columns of this form. Therefore, for repetitive use of a given type of column specifier, the following command has been defined:

Here, col is a one-letter specifier to identify the new type of column inside a preamble; narg is an optional parameter, giving the number of arguments this specifier takes; and decl are legal declarations. For example:

The newly defined x column specifier can then be used in the preamble arguments of all array and tabular environments in which one needs columns of this form.

Quite often you may need math mode and LR mode columns inside a tabular or array environment. Thus, you can define the following column specifiers:

From now on you can use C to get centered LR mode in an array environment, or centered math mode in a tabular environment.

The ewcolumntype command takes the same first optional argument as ewcommand, which declares the number of arguments of the column specifier being defined. However, ewcolumntype does not take the additional optional argument forms of ewcommand; in the current implementation column specifiers may have only mandatory arguments.

A rather different use of the ewcolumntype command takes advantage of the fact that the replacement text in ewcolumntype may refer to more than one column. The following example shows the definition of a preamble option Z. Modifying the definition in the document preamble would change the layout of all tables in the document using this preamble option in a consistent manner.

The replacement text in a ewcolumntype command can be any of the primitives of array, or any new letter defined in another ewcolumntype command.

Any column specification in a tabular environment that uses one of these newly defined column types is “expanded” to its primitive form during the first stage of table processing. This means that in some circumstances error messages generated when parsing the column specification refer to the preamble argument after it has been rewritten by the ewcolumntype system, not to the preamble entered by the user.

Debugging column type declarations

To display a list of all currently active ewcolumntype definitions on the terminal, use the showcols command in the preamble.

The need to specify the width of paragraph mode entries in advance sometimes causes difficulties when setting tables. We will describe several approaches that calculate the required column widths based on the required total width of the table and/or the table contents.

Calculating column widths in this way gives you full control over the amount of space allocated to each column. Unfortunately, it is difficult to incorporate information depending on the contents of the table into the calculation. For example, if some columns in the table use the c column type and so are set to their natural width, you may wish to allocate the remaining space among the columns using paragraph mode. As this width is not known until after the table has been typeset, it is not possible to calculate all widths in advance. Two packages implement different algorithms that set the table multiple times so as to allocate widths to certain columns. The first, tabularx, essentially tries to allocate space equally between specified paragraph mode columns. The second, tabulary, tries to allocate more space to columns that contain “more data”.

Changing the width argument to specify a width of linewidth will produce the following table layout:

Commands used to typeset the X columns

By default, the X specification is turned into p{some value}. Such narrow columns often require a special format, which may be achieved using the > syntax. Thus, you may give a specification like >{small}X.

Another format that is useful in narrow columns is ragged right. As noted earlier, one must use the command abularnewline to end the table row if the last entry in a row is being set ragged right. This specification may be saved with ewcolumntype{Y}{>{small aggedright}X} (perhaps additionally adding arraybackslash to make \ denote the end of a row again). You may then use Y as a tabularx preamble argument.

The X columns are set using a p column, which corresponds to parbox[t]. You may want to set the columns with, for example, an m column corresponding to parbox[c]. It is impossible to change the column type using the > syntax, so another system is provided. The command abularxcolumn can be defined as a macro, with one argument, which expands to the tabular preamble specification to be used for X henceforth. When the command is executed, the supplied argument determines the actual column width.

The default definition is ewcommand abularxcolumn[1]{p{#1}}. A possible alternative definition is

Column widths

Normally, all X columns in a single table are set to the same width. It is nevertheless possible to make tabularx set them to different widths. A preamble like the following

specifies two columns; the second column will be three times as wide as the first. However, when using this method two rules should be obeyed:

• The sum of the widths of all X columns should remain unchanged. In the above example, the new widths should add up to the width of two standard X columns.

• Any multicolumn entries that cross any X column should not be used.

Tracing tabularx calculations

If a racingtabularx declaration is made, say, in the document preamble, then all following tabularx environments will print information to the terminal and the log file about column widths as they repeatedly reset the tables to find the correct widths. For instance, the last example produced the following log:

The tabulary package provides the column types shown in Table 5.3 on the next page plus those provided by the array package in Table 5.2 on page 244, and any other preamble options defined via ewcolumntype.

The main feature of this package is its provision of versions of the p column specifier in which the width of the column is determined automatically depending on the table contents. The following example is rather artificial as the table only has one row. Nevertheless, it demonstrates that the aim of the column width allocation made by tabulary is to achieve equal row height. Normally, of course, the same row will not hold the largest entry of each column but in many cases of tabular material, the material in each cell of a given column has similar characteristics. In those situations the width allocation appears to provide reasonable results.

Controlling the column width allocation

The tabulary package has two length parameters, ymin and ymax, which control the allocation of widths. By default, widths are allocated to each L, C, R, or J column in proportion to the natural width of the longest entry in each column. To determine this width tabulary always sets the table twice. In the first pass the data in L, C, R, and J columns is set in LR mode (similar to data in columns specified by the standard preamble options such as c). Typically, the paragraphs that are contained in these columns are set on a single line, and the length of this line is measured. The table is then typeset a second time to produce the final result, with the widths of the columns being set as if with a p preamble option and a width proportional to the natural lengths recorded on the first pass.

To stop very narrow columns from being too “squeezed” by this process, any columns that are narrower than ymin are set to their natural widths. This length may be set with setlength and is arbitrarily initialized to 10pt. If you know that a column will be narrow, it may be preferable to use, say, c rather than C so that the tabulary mechanism is never invoked on that column, and the column is set to its natural width.

Similarly, one very large entry can force its column to be too wide. To prevent this problem, all columns with natural length greater than ymax (as measured when the entries are set in LR mode) are set to the same width (with the proportion being taken as if the natural length was equal to ymax). This width is initially set to twice the text width.

The table in the above example is dominated by the large entry in the fourth column. By setting ymin to 30pt we can prevent the first two columns from becoming too narrow, and by setting ymax to 200pt we can limit the width of the fourth column and produce a more even spread of column widths.

Narrow p columns are sometimes quite challenging to set, and so you may redefine the command yformat to be any declarations made just after the centering or agged... declaration. By default, it redefines everypar to insert a zero space at the start of every paragraph, so the first word may be hyphenated. (See Section 5.2.1 on page 246.)

Like tabularx, tabulary supports the optional alignment argument of tabular. Also because the whole environment is saved and evaluated twice, care should be taken with any LaTeX constructs that may have side effects such as writing to files.

• tabularx and tabulary modify the widths of the columns, whereas tabular* modifies the widths of the inter-column spaces.

• The tabular and tabular* environments may be nested with no restrictions. However, if one tabularx or tabulary environment occurs inside another, then the inner one must be enclosed within { }.

verb only partially supported

• The bodies of tabularx and tabulary environments are, in fact, the arguments to commands, so certain restrictions apply. The commands verb and verb* may be used, but they may treat spaces incorrectly, and their arguments cannot contain a % or an unmatched { or }.

• tabular* uses a primitive capability of TeX to modify the inter-column space of an alignment. tabularx has to set the table several times as it searches for the best column widths, and is therefore much slower. tabulary always sets the table twice. For the latter two environments the fact that the body is expanded several times may break certain TeX constructs. Be especially wary of commands that write to external files, as the data may be written several times when the table is reset.

• tabularx attempts to distribute space equally among the X columns to achieve the desired width, whereas tabulary attempts to allocate greater widths to columns with larger entries.

Multipage tables in multicolumn typesetting

Two package files are available to construct tables longer than one page, supertabular and longtable. They share a similar functionality, but use rather different syntax. The longtable package uses a more complicated mechanism, working with TeX’s output routine to obtain optimal page breaks and to preserve the width of columns across all pages of a table. However, this mechanism may require the document to be processed several times before the correct table widths are calculated. The supertabular package essentially breaks the table into a sequence of page-sized tabular environments, and each page is then typeset separately. This approach does not require multiple passes and works in a larger range of circumstances. In particular, the longtable package does not support two-column or multicolumn mode.

The package supertabular (originally created by Theo Jurriens, and revised by Johannes Braams) defines the environment supertabular. It uses the tabular environment internally, but it evaluates the amount of used space every time it encounters a \ command. When this amount reaches the value of extheight, the package automatically inserts an end{tabular} command, starts a new page, and inserts the table head on the new page, continuing the tabular environment. This means that the widths of the columns, and hence the width of the complete table, can vary across pages.

Three variant environments are also defined. The supertabular* environment uses tabular* internally, and takes a mandatory width argument to specify the width of the table. The mpsupertabular and mpsupertabular* environments have the same syntax as supertabular and supertabular*, respectively, but wrap the table portion on each page in a minipage environment. This allows the use of the footnote command inside the tables, with the footnote text being printed at the end of the relevant page.

Inside a supertabular environment new lines are defined as usual by \ commands. All column definition commands can be used, including @{...} and p{...}. If the array package is loaded along with supertabular, the additional tabular preamble options may be used. You cannot, however, use the optional positioning arguments, like t and b, that can be specified with egin{tabular} and egin{tabular*}.

Several new commands are available for use with supertabular as described below. Each of these commands should be used before the supertabular environment, as they affect all following supertabular environments.

The argument to ablehead contains the rows of the table to be repeated at the top of every page. If ablefirsthead is also included, the first heading will use these rows in preference to the rows specified by ablehead. The argument may contain full rows (ended by \) as well as inter-row material like hline.

These commands specify material to be inserted at the end of each page of the table. If ablelasttail is used, these rows will appear at the end of the table in preference to the rows specified by abletail.

These commands specify a caption for the supertabular, either at the top or at the bottom of the table. The optional argument has the same use as the optional argument in the standard caption command—namely, it specifies the form of the caption to appear in the list of tables. When ablecaption is used the caption will be placed at the default location, which is at the top. This default may be changed within a package or class file by using the declaration @topcaptionfalse.

The format of the caption may be customized using the caption package, as shown in Example 5-4-4 on page 262.

The supertabular environment maintains an estimate of the amount of space left on the current page. The shrinkheight command, which must appear at the start of a table row, may be used to reduce this estimate. In this way it may be used to control the page-breaking decisions made by supertabular.

Use of the .aux file

The main difference between the supertabular and longtable environments is that the latter saves the information about the width of each longtable environment in the auxiliary .aux file. It then uses this information on a subsequent run to identify the widest column widths needed for the table in question. The use of the .aux file means that care should be taken when using the longtable in conjunction with the ofiles command. One effect of ofiles is to suppress the writing of the .aux file, so this command should not be used until after the final edits of that table have been made and the package has recorded the optimal column widths in the auxiliary file.

To compare the two packages, Example 5-4-1 on page 257 is repeated here, but now uses longtable rather than supertabular. You can see that the width of the table is identical on both pages (the left and right parts of the picture). Note that in longtable, most of the table specification is within the longtable environment; in supertabular the specification of the table headings occurs via commands executed before the supertabular environment.

The syntax of the longtable environment is modeled on that of the tabular environment. The main difference is that the optional align argument specifies horizontal alignment rather than vertical alignment as is the case with tabular.

Horizontal alignment

The align argument may have the value [c], [l], or [r], to specify centering, left, or right alignment of the table, respectively. If this optional argument is omitted then the alignment of the table is controlled by the two length parameters, LTleft and LTright. They have default values of fill, so by default tables will be centered.

Any length 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, a table can be set flush left using the definitions

or just by specifying egin{longtable}[l].

Using parameters to control table width

You can, for example, use the LTleft and LTright parameters to typeset a multipage table filling the full width of the page. Example 5-4-2 on page 258, which used supertabular*, may be typeset using the packages array and longtable and the declarations shown below:

In general, if LTleft and LTright are fixed lengths, the table will be set to the width of extwidth - LTleft - LTright.

Vertical space around table

Before and after the table, longtable inserts vertical space controlled by the length parameters LTpre and LTpost. Both default to the length igskipamount, but may be changed using setlength.

Table row commands

Each row in the table is ended with the \ command. As in the standard tabular environment, the command abularnewline is also available; it is useful if \ has been redefined by a command such as aggedright. The star form \* may also be used which inhibits a page break at this linebreak. In a tabular environment, this star form is accepted but has the same effect as \. Conversely, a \ command may be immediately followed by a ewpage command, which forces a page break at that point.

If a table row is terminated with kill rather than \, then the row will not be typeset. Instead, the entries will be used when determining the widths of the table columns. This action is similar to that of the kill command in the tabbing environment.

Rows used as the table head and foot

The main syntactic difference between the longtable package and the supertabular package is that in longtable, rows to be repeated on each page as the table head or foot are declared within the environment body, rather than before the environment as in supertabular. As shown in Example 5-4-3 on the preceding page, the table head and foot are specified by replacing the final \ command by one of the commands listed below. Note that all of these commands, including those specifying the foot of the table, must come at the start of the environment. The command endhead finishes the rows that will appear at the top of every page. The command endfirsthead ends the declaration of rows for the start of the table. If this command is not used then the rows specified by endhead will be used at the start of the table. Similarly, endfoot finishes the rows that will appear at the bottom of every page, and endlastfoot—if used—ends the rows to be displayed at the end of the table.

The caption command and its variant caption* are essentially equivalent to writing a special multicolumn entry

where n is the number of columns of the table. The width of the caption can be controlled by redefining the parameter LTcapwidth. That is, you can write setlengthLTcapwidth{width} in the document preamble. The default value is 4in. As with the caption command in the figure and table environments, the optional argument specifies the text to appear in the list of tables if it is different from the text to appear in the caption.

When captions on later pages should differ from those on the first page, you should place the caption command with the full text in the first heading, and put a subsidiary caption using caption[ ] in the main heading, since (in this case) no entry is made in the list of tables. Alternatively, if the table number should not be repeated each time, you can use the caption* command. As with the table environment, cross-referencing the table in the text is possible with the label command.

By default, the caption is set in a style based on the caption style of the tables in standard LaTeX’s article class. If the caption package (described in Section 6.5.1) is used, then it is easy to customize longtable and table captions, keeping the style of captions consistent between these two environments.

Footnotes in longtable

You can use footnote commands inside the longtable environment. The footnote text appears at the bottom of each page. The footnote counter is not reset at the beginning of the table, but uses the standard footnote numbering employed in the rest of the document. If this result is not desired then you can set the footnote counter to zero before the start of each table, and then reset it at the end of the table if following footnotes must be numbered in the original sequence.

Increase LTchunksize to reduce number of LaTeX runs required

To enable TeX to set very long multipage tables, it is necessary to break them up into smaller chunks so that TeX does not have to keep everything in memory at one time. By default, longtable uses a value of 20 rows per chunk, which can be changed with a command such as setcounter{LTchunksize}{100}. These chunks do not affect page breaking. When TeX has a lot of memory available LTchunksize can be set to a big number, which usually means that longtable will be able to determine the final widths in fewer TeX runs. On most modern TeX installations LTchunksize can safely be increased to accommodate several pages of table in one chunk. Note that LTchunksize must be at least as large as the number of rows in each of the head or foot sections.

When a float occurs on the same page as the start of a multipage table, unexpected results can occur. Both packages have code that attempts to deal with this situation, but in some circumstances tables can float out of sequence. Placing a clearpage command before the table, thereby forcing a page break and flushing out any floats, will usually correct the problem.

p column entries do not break

Neither the supertabular nor the longtable environment will make a page break after a line of text within a cell. Pages will be broken only between table rows (or at hline commands). If your table consists of large multiple line cells set with the p preamble option, then LaTeX may not be able to find a good page break and may leave unwanted white space at the bottom of the page.

The example below has room for six lines of text on each page but LaTeX breaks the page between the two table rows, leaving page 1 short.

For some tables, the table rows form an important logical unit and the default behavior of not breaking within a row is desired. In other cases, it may be preferable to break the table manually to achieve a more pleasing page break. In the above example, we want to move the first two lines of page 2 to the bottom of page 1. Noting that TeX broke the third column entry after the word “several”, we could end the table row at that point by using \, insert blank entries in the first two columns of a new row, and place the remaining portion of the p entry in the final cell of this row. The first part of the split paragraph should be set with parfillskip set to 0pt so that the final line appears full width, just as it would be if it were set as the first two lines of a larger paragraph.

It is perhaps more common to use color as a background to highlight certain rows or columns. In this case using the fcolorbox command from the color package does not give the desired result, as typically the background should cover the full extent of the table cell. The colortbl package (by David Carlisle) provides several commands to provide colored backgrounds and rules in tables.

Normally, these declarations would be used before a table, or in the document preamble, to set the color for all rules in a table. However, the rule color may be varied for individual rules using constructs very similar to the previous example.

In the example below, a new preamble option I is defined that produces a wide vertical rule. Similarly, a whline command is defined that produces a wide horizontal rule.

The declaration decl consists of a list of tokens with the following meanings:

= A double hline the width of a column.

- A single hline the width of a column.

~ A column without hline; a space the width of a column.

| A vline that “cuts” through a double (or single) hline.

: A vline that is broken by a double hline.

# A double hline segment between two vlines.

t The top rule of a double hline segment.

b The bottom rule of a double hline segment.

* *{3}{==#} expands to ==#==#==#, as in the * form for the preamble.

If a double vline is specified (|| or ::), then the hlines produced by hhline are broken. To obtain the effect of an hline “cutting through” the double vline, use a #.

The tokens t and b can be used between two vertical rules. For instance, |tb| produces the same lines as #, but is much less efficient. The main uses for these are to make constructions like |t: (top left corner) and :b| (bottom right corner).

If hhline is used to make a single hline, then the argument should only contain the tokens “-”, “~”, and “|” (and * expressions).

An example using most of these features follows.

The lines produced by hline consist of a single (TeX primitive) hrule. The lines produced by hhline are made up of lots of small line segments. TeX will place these very accurately in the .dvi file, but the dvi driver used to view or print the output might not line up the segments exactly. If this effect causes a problem, you can try increasing arrayrulewidth to reduce the effect.

The basic use of the package is very simple. A new preamble option “:” is introduced, together with two new commands hdashline and cdashline. These features may be used in the same way as the standard LaTeX “|” preamble option and hline and cline commands, except that dashed rather than solid lines are produced. If the array package is also loaded, then the commands firsthdashline and lasthdashline are defined. They are dashed analogues of the firsthline and lasthline commands defined in that package.

Each of the commands takes an optional argument that may be used to specify the style of rule to be constructed. For example, an optional argument of [2pt/1pt] would specify that the rule should use 2pt dashes separated by 1pt spaces. The tabular preamble syntax does not allow for optional arguments on preamble options, so the “:” option does not have an optional argument in which to specify the dash style. Instead, an additional preamble option “;” is defined that takes a mandatory argument of the form dash/gap, as demonstrated in the example below.

The default size of the dashes and gaps is 4pt, which may be changed by setting the style parameters dashlinedash and dashlinegap via setlength. This ability is shown in the example below.

Avoiding unsightly gaps

The package may use any one of three methods for aligning the dashes within a table cell. The package may sometimes produce an overlarge gap at the edge of a table entry because there is not enough room to fit in the next “dash”. If this happens you might try specifying an alternative placement algorithm using the command ADLdrawingmode{m}, where m may be 1 (the default), 2, or 3.

The package documentation contains details of the placement algorithms used in each of these cases, but in practice you can just experiment with your particular table and dash styles to see which setting of ADLdrawingmode gives the most pleasing result.

ablinesep The minimum space between text on successive lines of a table. Negative values are treated as zero. The default is 1pt. If this parameter is set to 0pt, the code will not check the height of table entries to avoid touching text (which will emulate the default behavior of tabular).

arraylinesep The equivalent to ablinesep for the array environment.

extrarulesep Extra space added above and below each hline and cline. There will be space of at least extrarulesep + 0.5 ablinesep between an hline and text in the following table row. Negative values will reduce the space below the line, until the line is touching the text. Larger negative values will not cause the line to overprint the text. The default value is 3pt.

In addition, the hline command is extended with an optional argument like that of \. This argument specifies additional space to insert below the rule.

Do not use double rules

The vertical rules in a tabular environment are made up of a series of rule segments, one in each row of the table. Commands designed to improve vertical spacing between rows or around horizontal rules need to be carefully designed not to “break” any vertical rules by adding space between these rule segments. An alternative approach is taken by the booktabs package (by Simon Fear). It is designed to produce more formal tables according to a more traditional typographic style that uses horizontal rules of varying widths to separate table headings, but does not use any vertical rules. The | preamble option is not disabled when using this package, but its use is not supported and the extra commands for horizontal rules described below are not designed to work well in conjunction with vertical rules. Similarly, booktabs commands are not designed to support double rules as produced by the || or hlinehline.

The booktabs commands may be used with the standard tabular environments, the extended versions provided by the array package, and in the longtable environment provided by the longtable package.

An example showing the most commonly used commands provided by the package is shown below.

The booktabs package provides the oprule, midrule, and ottomrule commands. They are used in the same way as the standard hline but have better vertical spacing, and widths specified by the length parameters heavyrulewidth (for top and bottom rules) and lightrulewidth (for mid-table rules). These parameters default to 0.08 em and 0.05 em, respectively (where the em is determined by the default document font at the point the package is loaded).

The spacing above and below the rules is determined by the length parameters: abovetopsep (default 0pt) is the space above top rules, aboverulesep (default 0.4 ex) is the space above mid-table and bottom rules, elowrulesep (default 0.65 ex) is the space below top and mid rules, and elowbottomsep (default 0pt) is the space below bottom rules.

If you need to control the widths of individual rules, all of these commands take an optional width argument. For example, midrule[0.5pt] would produce a rule of width 0.5pt.

When these commands are used inside a longtable environment, they may take an optional (trim) argument as described below for cmidrule. This argument may be used to make the rules slightly less than the full width of the table.

The cmidrule command produces rules similar to those created with the standard LaTeX cline command. The col1-col2 argument specifies the columns over which the rule should be drawn. Unlike the rules created by cline, these rules do not, by default, extend all the way to the edges of the column. Thus, one may use cmidrule to produce rules on adjacent columns without them touching, as shown in the example above.

If the optional width argument is not specified, the rule will be of the width specified by the cmidrulewidth length parameter (default 0.03 em).

By default, the rule extends all the way to the left, but is “trimmed” from the rightmost column by the length specified in the length parameter cmidrulekern. The optional (trim) argument may contain the characters l and r, indicating that the rule is to be trimmed from the left or right, respectively. Each l and r may optionally be followed by a width argument specified using {widths}, in which case the rule is trimmed by this amount rather than by the default cmidrulekern.

Normally, if one cmidrule command immediately follows another, then the rules will be drawn across the specified columns on the same horizontal line. A command morecmidrules is provided that may be used to terminate a row of mid-table rules. Following mid-table rules will then appear on a new line separated by the length cmidrulesep, which by default is equal to doublerulesep.

Each group of rules produced by cmidrule is preceded and followed by a space of width midrulesep, so this command generates the same spacing as midrule. By default, however, the cmidrule rules are lighter (thinner) than the rules produced by midrule.

Extra space may be inserted between rows using addlinespace. This command differs from using the optional argument to \, as the former may also be used immediately before or after the rule commands.

If used in this position the command replaces the default spacing that would normally be produced by the rule. If the optional width argument is omitted it defaults to the length parameter defaultaddspace (which defaults to 0.5 em).

Finally, if none of the other commands produces a suitable rule then the command specialrule may be used. It takes three mandatory arguments that specify the width of the rule, and the space above and below the rule.

As the intention of the package is to produce “formal” tables with well-spaced lines of consistent thickness, the package author warns against overuse of the optional arguments and special commands to produce lines with individual characteristics. Nevertheless, these features may be useful in special circumstances.

The example on the following page shows the effect of many of these options as well as demonstrating that overuse of the commands will produce a very unpleasing layout.

You can simulate a cell spanning a few rows vertically by putting the material in a zero-height box and raising it.

Similarly, you can use a standard tabular preamble of the form r@{.}l to create two table columns and produce the effect of a column aligned on a decimal point, but then the input looks rather strange. For an alternative solution, see Section 5.7.2 on page 274.

This strategy is not always convenient, because you have to be aware that the “column” is really two columns of the table. This consideration becomes important when counting columns for the multicolumn or cline commands. Also, you need to locally set extracolsep to 0pt if you use this construct in a tabular* environment, otherwise TeX may insert space after the decimal point to spread the table to the specified width.

Inside an array, this command is somewhat less useful because the lines have an extra jot of space (a length, by default equal to 3pt, that is used for opening up displays), which is not accounted for by multirow. Fixing this problem (in general) is almost impossible. Nevertheless, a semiautomatic fix is to set the length parameter igstrutjot to jot, and then use the second argument njot of multirow with a value equal to half the number of rows spanned.

You have some ability to control the formatting within cells. Just before the text to be typeset is expanded, the multirowsetup macro is automatically executed to set up any special environment. Initially, multirowsetup contains just aggedright, but it can be redefined with enewcommand.

The multirow command works in one or more columns, as shown in the example below.

You are now in a position to typeset the small example shown at the beginning of this section without having to use the aisebox command. First, you must change the alignment inside the multirow paragraph to centering. Next, you calculate the width of the text in the column, which is required by the multirow command. If the column with the spanned rows has a fixed width, as in our other examples, this step is unnecessary.

The effect of the optional vertical positioning parameter vmove can be seen below. Note the effect of the upward move by 3 mm of the lower third of the table.

The package defines a “Decimal” tabular preamble option, D, that takes three arguments.

inputsep A single character, used as separator (or “decimal point”) in the source file (for example, “.” or “,”).

outputsep The separator to be used in the output. It can be the same as the first argument, but may also be any math mode expression, such as cdot.

decimal places The maximum number of decimal places in the column. If this value is negative, any number of decimal places is allowed in the column, and all entries will be centered on the separator. Note that this choice can cause a column to be too wide (see the first two columns in the example below). Another possibility is to specify the number of digits both to the left and to the right of the decimal place, using an argument of the form {left.right} as described below.

If you do not want to use all three entries in the preamble, you can customize the preamble specifiers by using ewcolumntype as demonstrated below.

The newly defined “d” specifier takes a single argument specifying the number of decimal places. The decimal separator in the source file is the normal dot “.”, while the output uses the math mode “·”.

In this case the “.” specifier has no arguments: the normal dot is used in both input and output. The typeset entries should be centered on the dot.

The “,” specifier defined here uses the comma “,” as a decimal separator in both input and output, and the typeset column should have (at most) two decimal places after the comma.

These definitions are used in the following example, in which the first column, with its negative value for decimal places (signaling that the decimal point should be in the center of the column), is wider than the second column, even though they both contain the same input material.

If the table entries include only numerical data that must be aligned, the alignment forms shown in the above example should be sufficient. However, if the columns contain headings or other entries that will affect the width of the column, the positioning of the numbers within the column might not be as desired. In the example below, in the first column the numbers appear to be displaced toward the left of the column, although the decimal point is centered. In the second column the numbers are flush right under a centered heading, which is sometimes the desired effect but (especially if there are no table rules) can make the heading appear dissociated from the data. The final column shows the numbers aligned on the decimal point and centered as a block under the heading. This effect is achieved by using a third argument to the D preamble option of 4.2 specifying that at most four digits can appear to the left of the point, and two digits to the right of it.

The following is a variant of an example in the LaTeX Manual showing that D column alignments may be used for purposes other than aligning numerical data on a decimal point.

As you generally want your “table notes” to appear just below the table, you will have to tackle the problem yourself by managing the note marks and, for instance, by using multicolumn commands at the bottom of your tabular environment to contain your table notes.

In the example below note the redefinition of hefootnote that allows us to make use of the footnotemark command inside the minipage environment. Without this redefinition footnotemark would have generated a footnote mark in the style of the footnotes for the main page, as explained in Section 3.2.2.

Of course, this approach does not automatically limit the width of the footnotes to the width of the table, so a little iteration with the minipage width argument might be necessary to achieve the desired effect.

Table notes set to the width of the table

Normally, the threeparttable environment would be contained within a table environment so that the table would float. However, threeparttable may also be used directly, in which case it constructs a nonfloating table similar to the nonfloating table environment set-up described in Example 6-3-4 on page 295.

As its name suggests, the threeparttable environment consists of three parts. The caption consists of the usual caption command (which may come before or after the table). The table may use one of the standard tabular or tabular* environments, the extended variants defined in the array package, or the tabularx environment defined in tabularx. Support for other tabular environments may be added in later releases, the package documentation lists the currently supported environments. The third part of a threeparttable is the text of the table notes, which consists of one or more tablenotes environments.

The threeparttable package offers several options to control the typesetting of the table notes:

para Notes are set within a paragraph, without forced line breaks.

flushleft No hanging indentation is applied to notes.

online Note labels are printed normal size, not as superscripts.

normal Normal default formatting is restored.

Each of these options may be used as a package option to set the default style for all such tables within the document. Alternatively, they may be used as shown in the example, on individual tablenotes environments.

In addition to these options the package has several commands that may be redefined to control the formatting in more specific ways than those provided by the package options. See the package documentation for details.

You can put some rubber length in front of each column with the help of the extracolsep command. The actual value of the rubber length is not important, as long as it can shrink enough to just fill the needed space. In this case you must, of course, specify a total width for the table. We could use linewidth and make the table full width, but here we can obtain a better result by precalculating the width of the wide entry and specifying it as the total width of the tabular*.

To achieve correct alignment, we needed to take into account the column separation ( abcolsep) on both sides of an entry. Alternatively, we could have suppressed the inter-column spaces at the left and right of the tabular* by using @{} expressions.

The family of tabular environments allows vertical positioning with respect to the baseline of the text in which the environment appears. By default, the environment appears centered. This preference can be changed to align with the first or last line in the environment by supplying a t or b value to the optional position argument. Note that this approach does not work when the first or last element in the environment is an hline command—in that case, the environment is aligned at the horizontal rule.

To achieve proper alignments you can use the two commands firsthline and lasthline, which are special versions of hline defined in the array package. These commands enable you to align the information in the tables properly as long as their first or last lines do not contain extremely large objects.

The implementation of the two commands contains an extra dimension, extratabsurround, to add space at the top and the bottom of such an environment. It is helpful for properly aligning nested tabular material, as shown in the next example.

A final example

The LaTeX code below shows how you can combine the various techniques and packages described earlier in this chapter. We used the package tabularx to generate a 12 column table in which columns 3 to 12 are of equal width. We used the package multirow to generate the stub head, “Prefix”, which spans two rows in column 1. To position the stub head properly, we calculated the width of the title beforehand.