TBL(1)               UNIX System V (DWB 3.3)               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 .TS and a subsequent .TE
            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 .TS and
            .TE command lines are also copied through without change so
            they can be interpreted later by troff macro packages.

            The .TS command line may be followed by a line containing
            global options:
                 center    Centers the table (the default action is to
                           left-adjust the table).
                 expand    Makes the table as wide as the current line
                           length.
                 box       Encloses the table in a box.
                 doublebox Encloses the table in a double box.
                 allbox    Encloses each table entry in a box.
                 tab(x)    Uses the character x instead of a tab to sep-
                           arate entries in a line of input data.
                 linesize(n)
                           Sets lines or rules (e.g., from box) in n-
                           point type.
                 maxline(n)
                           Uses n instead of the default maximum (250)
                           for the number of data lines that are used in
                           calculating column widths, etc.
                 delim(xy) 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.




       Page 1                                         (printed 6/1/2018)






       TBL(1)               UNIX System V (DWB 3.3)               TBL(1)



            The available key-letters (lower- and upper-case) are:
                 c    Centers each entry within the column.
                 r    Right-adjusts each entry within the column.
                 l    Left-adjusts each entry within the column.
                 n    Numerically adjusts each entry in the column: the
                      units positions of numeric entries will be aligned
                      vertically.
                 a    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.
                 s    Causes the previous entry on the left to span hor-
                      izontally 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.
                 Ff   Uses font f.  B and I are synonyms for FB and FI,
                      respectively.
                 T    Begin a vertically-spanned item at the top of its
                      range.  Default is vertical centering.
                 Pn   Uses point size n; signed n means a relative size
                      change.
                 Vn   Uses n-point vertical spacing in text blocks;
                      signed n means a relative size change.
                 W(n) Sets the column width to a troff width specifica-
                      tion n; parens are optional if n is a simple inte-
                      ger.
                 E    Equalizes the widths of all columns marked with
                      the E modifier.
                 X    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 pro-
            duce a vertical line between the corresponding columns of
            the table.  A vertical bar to the left of the first key let-
            ter 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.




       Page 2                                         (printed 6/1/2018)






       TBL(1)               UNIX System V (DWB 3.3)               TBL(1)



            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 con-
            taining the data for the table entries, followed finally by
            the .TE 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 con-
                      tents of the column (does not extend into the col-
                      umn gutter to join with other lines).
                 \Rx  Repeats character x across the column.
                 \^   Spans the previous item in this column down into
                      this row.
                 T{   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 T} 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 maxline 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 maxline lines of input
            data.  The global parameter maxline 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 follow-
            ing: (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 maxline to reduce the number of input lines that
            are considered in calculating column widths, etc.




       Page 3                                         (printed 6/1/2018)






       TBL(1)               UNIX System V (DWB 3.3)               TBL(1)



            Format specifications can be interspersed with data lines by
            using the table-change request (.T&).  Lines following .T&
            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 .T& are allowed only
            within the first 250 lines of table data; this limit can be
            overridden by the maxline global option.

            Anywhere between a .TS 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.  .T& requests in
            an included file are allowed, so nested file includes are
            possible.  .TS and .TE 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 specifica-
            tions, 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.










       Page 4                                         (printed 6/1/2018)






       TBL(1)               UNIX System V (DWB 3.3)               TBL(1)



       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_____|
                         |              |   Households  |
                         |     Town     |  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 prob-
            lems 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








       Page 5                                         (printed 6/1/2018)