tbl

unix v7是最后一个广泛发布的研究型UNIX版本

.if \nM=0 .RP
.TM 76-1274-5 39199 39199-11
.if \n(tm>0 .ND June 11, 1976*
.TL
Tbl \(em A Program to Format Tables
.AU "MH 2C-569" 6377
M. E. Lesk
.AI
.MH
.if \n(tm>0 .FS
.if \n(tm>0 * This printing revised through August 5, 1977
.if \n(tm>0 .FE
.AB
.I
Tbl
.R
is a document formatting preprocessor for
.I
troff
.R
or
.I
nroff
.R
which makes
even
fairly complex tables easy to specify and enter.
It is available on
the
.SM
PDP-11 UNIX*
.NL
system
.FS
* UNIX is a Trademark/Service Mark of the Bell System
.FE
and on Honeywell 6000
.SM
GCOS.
.NL
Tables are made up of columns which may be independently centered, right-adjusted,
left-adjusted, or aligned by decimal points.
Headings may be placed over single columns or groups of columns.
A table entry may contain equations, or may consist of several rows of text.
Horizontal or vertical lines may be drawn as desired
in the table,
and any table or element may be enclosed in a box.
For example:
.in 0
.ll
.sp .5
.TS
center, box;
c  s  s  s
c  s  s  s
c |c |c |c
c |c |c |c
l |n |n |n.
1970 Federal Budget Transfers
\s-2(in billions of dollars)\s0
=
State	Taxes	Money	Net
\^	collected	spent	\^
_
New York	22.91	21.35	\-1.56
New Jersey	8.33	6.96	\-1.37
Connecticut	4.12	3.10	\-1.02
Maine	0.74	0.67	\-0.07
California	22.29	22.42	+0.13
New Mexico	0.70	1.49	+0.79
Georgia	3.30	4.28	+0.98
Mississippi	1.15	2.32	+1.17
Texas	9.33	11.13	+1.80
.TE
.AE
.OK
Phototypesetting
Documentation
.CS  16 0 16 0 12 6
.tr # 
.de e1
.nr \\$1 \\$2
..
.de e2
.if !\\n(\\$1=\\n% .tm Error in example \\$1: referred to page \\n(\\$1, is on page \\n%
.rr \\$1
..
.di qq
.EQ
delim $$
.EN
.di
.rm qq
.SH
Introduction.
.PP
.I
Tbl
.R
turns a simple description
of a table into a
.I
troff
.R
or
.I
nroff
.R
[1]
program (list of commands) that prints the table.
.I
Tbl
.R
may be used on the
\s-2PDP-\s011 \s-2UNIX\s0
.NL
[2] system and on the Honeywell 6000
.SM
GCOS
.NL
system.
It
attempts to isolate a portion of a job that it can
successfully
handle and leave the remainder for other programs.
Thus
.I
tbl
.R
may be used with the equation formatting
program
.I
eqn
.R
[3]
or various
layout macro packages
[4,5,6],
but does not duplicate their functions.
.PP
This memorandum is divided into two parts.
First we give the rules for preparing
.I
tbl
.R
input; then some examples are shown.
The description of rules is precise but technical, and
the beginning user may prefer to read the examples first,
as they show some common table arrangements.
A section explaining how to invoke
.I
tbl
.R
precedes the examples.
To avoid repetition, henceforth read
.I
troff
.R
as
.I
``troff
.R
or
.I
nroff.''
.R
.ds . \^\s14.\s0
.PP
The input to
.I
tbl
.R
is text for a document, with tables preceded by a ``\*.TS''
(table start)
command and followed by a ``\*.TE''
(table end) command.
.I
Tbl
.R
processes the tables, generating
.I
troff
.R
formatting commands,
and leaves the remainder of the text unchanged.
The ``\*.TS'' and ``\*.TE''
lines are copied, too, so that
.I
troff
.R
page layout macros
(such as the memo formatting macros [4]\|) can use these lines
to delimit and place tables as they see fit.
In particular, any arguments on the ``\*.TS'' or ``\*.TE''
lines
are copied but otherwise ignored, and may be used by document layout
macro commands.
.PP
The format of the input is as follows:
.DS
\&text
\&\*.TS
\&\fItable\fR
\&\*.TE
\&text
\&\*.TS
\&\fItable\fR
\&\*.TE
\&text
\&\&\*. \*. \*.
.DE
where the format of each table is as follows:
.DS
\&\*.TS
\fIoptions \fB;\fR
\fIformat \*.
data
\&\fR\*.TE
.DE
Each table is independent, and must contain formatting
information
followed by the data to be entered in the table.
The formatting information, which describes the
individual columns and rows of the table, may be preceded
by a few options that affect the entire table.
A detailed description of tables is given in the next section.
.sp .5
.SH
Input commands.
.PP
As indicated above, a table contains, first, global options,
then a format section describing the layout of the table
entries, and then the data to be printed.  The format and data
are always required, but not the options.
The various parts of the table are entered as follows:
.sp .5v
.IP 1)
O\s-2PTIONS.\s0
There may be a single line of options
affecting the whole table.
If present, this line must follow the \*.TS line immediately
and must contain a list of option names
separated by spaces, tabs, or commas, and must be terminated by a semicolon.
The allowable options are:
.RS
.IP \fB##center\fR 13
\(em center the table (default is left-adjust);
.IP \fB##expand\fR
\(em make the table as wide as the current line length;
.IP \fB##box\fR
\(em enclose the table in a box;
.IP \fB##allbox\fR
\(em enclose each item in the table in a box;
.IP \fB##doublebox\fR
\(em enclose the table in two boxes;
.IP \fB##tab#\fR(\fIx\fR\^)
\(em use \fIx\fR instead of tab to separate data items.
.IP \fB##linesize#(\fIn\fR\^)
\(em set lines or rules (e.g. from \fBbox\fR\^) in \fIn\fR point type;
.IP \fB##delim#(\fIxy\fR\^)
\(em recognize \fIx\fR and \fIy\fR as the \fIeqn\fR delimiters.
.RE
.LP
.ns
.IP
The
.I
tbl
.R
program
tries to keep boxed tables on one page by issuing
appropriate ``need'' (\fI\*.ne\fR\|) commands.
These requests are calculated from the number of lines in the tables,
and if there are spacing commands embedded in the input, these requests may be inaccurate;
use normal
.I
troff
.R
procedures, such as keep-release macros, in that case.
The user who must have a multi-page boxed table
should use macros designed for this purpose,
as explained below under `Usage.'
.sp .5v
.IP 2) 5
F\s-2ORMAT\s0.
The format section of the table specifies the layout
of the columns.
Each line in this section corresponds to one line
of the table (except that the last line corresponds to all following
lines up to the next \*.T&, if any \(em see below),
and each line contains a key-letter for each column
of the table.
It is good practice to separate the key letters for each
column by spaces or tabs.
Each key-letter is one of the following:
.RS
.cs B 25
.IP "##\fBL\fR#or#\fBl\fR" 10
to indicate a left-adjusted column entry;
.IP "##\fBR\fR#or#\fBr\fR
to indicate a right-adjusted column entry;
.IP "##\fBC\fR#or#\fBc\fR
to indicate a centered column entry;
.IP "##\fBN\fR#or#\fBn\fR
to indicate a numerical column entry, to be aligned with other
numerical entries so that the units digits of numbers line up;
.IP "##\fBA\fR#or#\fBa\fR
to indicate an alphabetic subcolumn;
all corresponding entries are aligned on the left, and positioned
so that the widest is centered within the column (see
example on page 12);
.IP "##\fBS\fR#or#\fBs\fR
to indicate a spanned heading, i.e. to indicate that the
entry from the previous column continues across this
column
(not allowed for the first column, obviously); or
.IP ##\fB\s+4\v'6p'^\v'-6p'\s0\fR
to indicate a vertically spanned heading, i.e. to indicate that
the entry from the previous row continues down through this row.
(Not allowed for the first row of the table, obviously).
.cs B
.RE
.LP
.ns
.IP
When numerical alignment is specified, a location for the decimal
point is sought.  The rightmost dot (\*.)
adjacent to a digit is used as a decimal point; if there is no
dot adjoining a digit, the rightmost digit is used as a units digit;
if no alignment is indicated, the item is centered in the column.
However, the special non-printing character string \e& may be used
to override unconditionally dots
and digits, or to align alphabetic data;
this string lines up where a dot normally would,
and then disappears from the final output.
In the example below, the items shown at the left will be
aligned (in a numerical column) as shown on the right:
.KS
.TS
center;
l6 n.
13	13
4\*.2	4\&\*.2
26\*.4\*.12	26\*.4\&\*.12
abc	abc
abc\e&	abc\&
43\e&3\*.22	43\&3\*.22
749\*.12	749\&\*.12
.TE
.KE
.IP
\fBNote:\fR
If numerical data are used in the same column with wider
.B L
or
.B r
type table entries, the widest \fInumber\fR is centered relative
to the wider
.B L
or
.B r
items (\fBL\fR is used instead of \fBl\fR for readability;
they have the same meaning as key-letters).
Alignment within the numerical items is preserved.
This is similar to the behavior of
.B a
type data, as explained above.
However,
alphabetic subcolumns (requested by the
.B
a
.R
key-letter)
are always slightly indented relative to
.B
L
.R
items;
if necessary, the column width is increased to force this.
This is not true for \fBn\fR type entries.
.IP
.bd I 3
.ft I
Warning:
.ft 1
.bd I
the \fBn\fR and \fBa\fR items should not be used in
the same column.
.IP
For readability, the key-letters describing each column should
be separated by spaces.
The end of the format section is indicated by a period.
The layout of the key-letters in the format section resembles
the layout of the actual data in the table.
Thus a simple format might appear as:
.br
.ne 3
.in +2
.nf
c  s  s
l  n  n \*.
.fi
.in -2
which specifies a table of three columns. The first line
of the table contains a heading centered across all three
columns; each remaining line contains a left-adjusted item
in the first column followed by two columns of numerical
data.
A sample table in this format might be:
.br
.ne 6v
.br
.in +4
.TS
c s s
l n n.
Overall title
Item-a	34.22	9.1
Item-b	12.65	.02
Items: c,d,e	23	5.8
Total	69.87	14.92
.TE
.in -4
There are some additional features of the key-letter system:
.RS
.IP "\fI##Horizontal lines#\fR"
\(em A key-letter may be replaced by `\(ul'
(underscore) to indicate
a horizontal line in place of the corresponding column entry,
or by `=' to indicate a double horizontal line.
If an adjacent column contains a horizontal line, or if
there are vertical lines adjoining this column,
this horizontal line is extended to meet the nearby lines.
If any data entry is provided for this column, it is ignored and
a warning message is printed.
.QQ do the D(x) and M(x) to draw a line of 'x' characters.
.QQ D will draw divided lines, M merged lines. thus - is simplh M(\(ru)
.IP "\fI##Vertical lines#\fR"
\(em A vertical bar may be placed between column key-letters.  This will
cause 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.
.IP "\fI##Space between columns#\fR"
\(em A number may follow the key-letter.  This indicates the amount of separation
between this column and the next column.
The number normally specifies the separation in
.I
ens
.R
(one
en
.ne 3
is about the width of the letter `n').* 
.FS
* More precisely, an en is a number of points (1 point = 1/72 inch)
equal to half the current type size.
.FE
If the ``expand'' option is used, then these numbers are multiplied
by a constant such that the table is as wide as the current line length.
The default column separation number is 3.
If the separation is changed the worst case (largest space requested) governs.
.IP "\fI##Vertical spanning#\fR"
\(em Normally, vertically spanned items extending over several
rows of the table are centered in their vertical range.
If a key-letter is followed by
.B
t
.R
or
.B T ,
any corresponding vertically spanned item
will begin at the top line of its range.
.IP "\fI##Font changes#\fR"
\(em A key-letter may be followed by a string containing a font
name or number
preceded by the letter
.B f
or
.B F .
This indicates that the corresponding column should be in a different
font from the default font (usually Roman).
All font names are one or two letters; a one-letter font
name should be separated from whatever follows by a space or tab.
The single letters
\f3B\f1, \f3b\f1, \f3I\f1,
and
\f3i\f1
are shorter synonyms for
.B f\^B
and
.B f\^I .
Font change commands given with the table entries
override these specifications.
.IP "\fI##Point size changes#\fR"
\(em A key-letter may be followed by the letter
.B p
or
.B P
and a number to indicate the point size of the corresponding table entries.
The number may be a signed digit, in which case it is taken as
an increment or decrement
from the current point size.
If both a point size and a column separation value are given,
one or more blanks must separate them.
.IP "\fI##Vertical spacing changes#\fR"
\(em A key-letter may be followed by the letter
.B v
or
.B V
and a number to indicate the vertical line spacing to be used
within a multi-line corresponding table entry.
The number may be a signed digit, in which case it is taken as an increment
or decrement from the current vertical spacing.
A column separation value must be separated by blanks or some other
specification from a vertical spacing request.
This request has no effect unless the corresponding table entry
is a text block (see below).
.IP "\fI##Column width indication#\fR"
\(em A key-letter may be followed by the letter
.B w
or
.B W
and a width value in parentheses.
This width is used as a minimum column width.
If the largest element in the column is not as wide as the width value
given after the \fBw\fR, the largest element is assumed to be that wide.
If the largest element in the column is wider than the specified value,
its width is used.
The width is also used as a default line
length for included text blocks.
Normal
.I
troff
.R
units can be used to scale the width value; if none are used,
the default is
ens.
If the width specification is a unitless integer
the parentheses may be omitted.
If the width value is changed in a column, the \fIlast\fR one given controls.
.IP "\fI##Equal width columns#\fR"
\(em A key-letter may be followed by the letter
.B e
or
.B E
to indicate equal width columns.
All columns whose
key-letters are followed by \fBe\fR or \fBE\fR are made the same width.
This permits the user to get a group of regularly spaced
columns.
.IP "##\fBNote:\fR#"
The order of the above features is immaterial; they need not be separated
by spaces, except as indicated above to avoid ambiguities involving
point size and font changes.  Thus
a numerical column entry in italic font and 12 point type with a minimum
width of 2.5 inches and separated by 6 ens from the next column could
be specified as
.in +5
np12w(2\*.5i)f\|I  6
.in -5
.IP "\fI##Alternative notation#\fR"
\(em Instead of listing the format of successive lines of a table
on consecutive lines of the format section,
successive line formats may be given on the same line, separated
by commas, so that the format for the example
above might have been written:
.in +5
c s s, l n n \*.
.in -5
.IP "\fI##Default#\fR"
\(em Column descriptors missing from the end
of a format line are assumed to be \fBL\fR.
The longest line in the format section, however,
defines the number of columns
in the table;
extra columns in the data are ignored silently.
.QQ put in the diagnostics.
.RE
.sp .5v
.IP 3)
D\s-2ATA\s0.
The data for the table are typed after the format.
Normally, each table line is typed as one line of data.
Very long input lines can be broken: any line whose last character is
\e is combined with the following line (and the \e vanishes).
The data for different columns (the table entries) are separated by tabs,
or by whatever character has been specified in the option
.I tabs
option.
There are a few special cases:
.RS
.IP "\fI##Troff commands within tables\fR#"
\(em An input line
beginning with a `\*.' followed by anything
but a number is assumed to be a command to
.I
troff
.R
and is passed through unchanged, retaining its position in the table.
So, for example, space within a table may be produced by ``\*.sp''
commands
in the data.
.IP "\fI##Full width horizontal lines\fR#"
\(em An input
.I line
containing only the character $fat "\(ul" $ (underscore)
or \fB=\fR (equal sign) is taken to be a single or double
line, respectively, extending the
full width
of the
.I table.
.IP "\fI##Single column horizontal lines\fR#"
\(em An input table
.I entry
containing only the character $fat "\(ul" $ or \fB=\fR
is taken to be a single or double line extending
the full width of the
.I column.
Such lines are extended to meet horizontal or vertical
lines adjoining this column.
To obtain these characters explicitly in a column, either
precede them by \e& or
follow them by a space before the usual tab or newline.
.IP "\fI##Short horizontal lines\fR#"
\(em An input table
.I entry
containing only the string $fat "\e\(ul"$
is taken to be a single line as wide as the contents of
the column.  It is not extended to meet
adjoining lines.
.IP "\fI##Repeated characters\fR#"
\(em An input table