TBL(1)

NAME
tbl - prepare tables for nroff or troff

SYNOPSIS
tbl [-c []] [-TX []] [- []] [ files []]

DESCRIPTION
tbl is a table preprocessor for nroff(1) or troff(1). tbl assumes that lines between a and a subsequent describe a table; these lines are replaced by troff requests and data to produce the table. Lines outside these areas are copied to the standard output unaltered. The and command lines are also copied through without change so they can be interpreted later by troff macro packages.

The command line may be followed by a line containing global options:

    Centers the table (the default action is to left-adjust the table).
    Makes the table as wide as the current line length.
    Encloses the table in a box.
    Encloses the table in a double box.
    Encloses each table entry in a box.
    Uses the character
        x instead of a tab to separate entries in a line of input data.
    Sets lines or rules (e.g., from
        box()) in n-point type.
    Uses
        n instead of the default maximum (250) for the number of data lines that are used in calculating column widths, etc.
    Recognizes
        x and y as eqn(1) delimiters.

End the global options, if any, with a semi-colon Use white space and/or commas to separate multiple global options. All of the global options must appear on a single line.

The line of global options is followed by one or more lines describing the format of the table. Each format line describes one row of the table, except that the last format line (which must end with a period) describes the remaining rows of the table. Each format line contains a key letter to describe each column of the table. A key letter may be followed by modifiers to specify the font and point size of the corresponding table entries, to indicate where vertical bars are to appear between columns, and to override the default calculations for column width, spacing between columns, etc.

The available key-letters (lower- and upper-case) are:

    Centers each entry within the column.
    Right-adjusts each entry within the column.
    Left-adjusts each entry within the column.
    Numerically adjusts each entry in the column:
        the units positions of numeric entries will be aligned vertically.
    Centers the widest entry in this column
        and then causes all other entries in this column to be left-adjusted with respect to the widest entry.
    Causes the previous entry on the left to span horizontally into this column.
    Causes the previous entry in this column
        to span vertically into this entry.
    Replaces this entry with a horizontal line
        is a synonym).
    Replaces this entry with a double horizontal line.

Each key letter may be followed by one or more modifiers (lower- or upper-case):

    n   Sets the gap between the current and next column to be n ens wide. Default is 3.
    Uses font
        f. and are synonyms for and FI(,) respectively.
    Begin a vertically-spanned item at the top of its range.
        Default is vertical centering.
    Uses point size
        n; signed n means a relative size change.
    Uses
        n-point vertical spacing in text blocks; signed n means a relative size change.
    Sets the column width to a
        troff width specification n; parens are optional if n is a simple integer.
    Equalizes the widths of all columns marked with the
        modifier.
    Increase the normal width of this column
        to use the remainder of the page width (between margins) after the widths of the other columns have been subtracted. This modifier is useful for a column containing text blocks, where it is desired to make the column as wide as possible without exceeding the page width. At most one column can have this modifier.

A vertical bar may be placed between key letters to produce a vertical line between the corresponding columns of the table. A vertical bar to the left of the first key letter or to the right of the last one produces a line at the edge of the table. If two vertical bars appear between key letters, a double vertical line is drawn between the corresponding columns of the table.

The maximum number of columns for a given table is set by the first format line for that table. Subsequent format lines may specify fewer columns, if desired.

The last format line is followed by one or more lines containing the data for the table entries, followed finally by the command line. Within each data line, the data items for the table entries are separated from each other by the specified separator character (default tab).

Except as specified below, each line of data corresponds to one row of the table. Lines beginning with are taken to be troff requests and are copied through unchanged. Certain special data items are recognized:

    Draws a horizontal line in this column
        is a synonym). A data line consisting of a single or draws a line across the whole table.
    Draws a double horizontal line in this column.
        A data line consisting of a single draws the line across the whole table.
    Draws a horizontal line only as wide as the contents of the column
        (does not extend into the column gutter to join with other lines).
    Repeats character
        x across the column.
    Spans the previous item in this column down into this row.
    The following data is a text block to be formatted separately by
        troff and then placed in the table entry. The block continues to the next line beginning with alone in a data field. The remainder of the data line follows at that point.

Long data lines can be broken: any data line ending with a backslash is combined with the following line (and the vanishes).

There is a limit of 62 on the number of text blocks in the first lines of input data; this reflects a limit in the size of the troff name space. There is no limit on the number of text blocks after the first lines of input data. The global parameter determines the number of lines of input data that are used to calculate column widths, etc. A line in this context is one of the following: (1) the input data for one row of the table, including text blocks, if any, (2) a troff request or macro call, or (3) an explicit request for a full-width horizontal line. If you get a message indicating that the limit on the number of text blocks has been exceeded, try using the global parameter to reduce the number of input lines that are considered in calculating column widths, etc.

Format specifications can be interspersed with data lines by using the table-change request Lines following are taken to be new format specifications; the last such line must end with a period. Subsequent lines are treated as input data to be processed in accordance with the new format specifications. It is not possible to change the maximum number of columns, the space between columns, the global options, or the selections of equal-width columns. Changes to the table format using are allowed only within the first 250 lines of table data; this limit can be overridden by the global option.

Anywhere between a and the next .TE(,) an input line of the form
    .T& <filename
inserts the contents of filename at that point in the input. The included file may contain format specifications, global options, or data in any valid combination. requests in an included file are allowed, so nested file includes are possible. and requests in an included file are ignored.

The normal operation of tbl is to terminate processing when the first input error is encountered. If the [-c] command-line option is used, tbl will continue processing even if there are errors in the input. If this option is used and there is an error in the global options section for a given table, the remaining global options for that table are not processed. If there is an error in the format specifications, the data section of the table is skipped. If the [-c] option is not used, processing terminates with the first error.

The [-TX] option forces tbl to use only full vertical line motions, making the output more suitable for devices that cannot generate partial vertical line motions (for example, line printers).

If you do not give any file names as arguments, or if you specify [-] as a file name argument, tbl reads the standard input, so it may be used as a filter. When you use tbl with eqn(1) or neqn(1), put tbl first to minimize the volume of data passed through pipes.

EXAMPLE
If we let → represent the tab character (which should be typed as a genuine tab), then the following input:
    .TS
    center box ;
    cB   s  s
    cI | cI s
    ^  | c  c
    l  | n  n .
    Household Population
    _
    Town→Households
    →Number→Size
    =
    Bedminster→789→3.26
    Bernards Twp.→3087→3.74
    Bernardsville→2018→3.30
    Bound Brook→3425→3.04
    Bridgewater→7897→3.81
    Far Hills→240→3.19
    .TE
yields a table which looks as follows:
Household Population
Town | Households
 | Number | Size
Bedminster | 789 | 3.26
Bernards Twp. | 3087 | 3.74
Bernardsville | 2018 | 3.30
Bound Brook | 3425 | 3.04
Bridgewater | 7897 | 3.81
Far Hills | 240 | 3.19

BUGS
This release of tbl attempts to fix all of the serious problems with multiple-page boxed tables. There are still a few unresolved appearance problems that do not seriously affect readability.

SEE ALSO
nroff(1), troff(1), mm(5)

REFERENCE
M. E. Lesk, TBL — A Program To Format Tables