1284 lines
26 KiB
HTML
1284 lines
26 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of TBL</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>TBL</H1>
|
|
Section: User Commands (1)<BR>Updated: 21 March 2020<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
tbl - format tables for troff
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
[ <B>-Cv</B> ]
|
|
|
|
[<I>file</I>
|
|
|
|
...]
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
This manual page describes the GNU version of
|
|
<B>tbl</B>,
|
|
|
|
which is part of the groff document formatting system.
|
|
<B>tbl</B>
|
|
|
|
compiles descriptions of tables embedded within
|
|
<B>troff</B>
|
|
|
|
input files into commands that are understood by
|
|
<B>troff</B>.
|
|
|
|
Normally, it should be invoked using the
|
|
<B>-t</B>
|
|
|
|
option of
|
|
<B>groff.</B>
|
|
|
|
It is highly compatible with Unix
|
|
<B>tbl</B>.
|
|
|
|
The output generated by GNU
|
|
<B>tbl</B>
|
|
|
|
cannot be processed with Unix
|
|
<B>troff</B>;
|
|
|
|
it must be processed with GNU
|
|
<B>troff</B>.
|
|
|
|
If no files are given on the command line or a filename of
|
|
<B>-</B>
|
|
|
|
is given, the standard input is read.
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>-C</B>
|
|
|
|
<DD>
|
|
Enable compatibility mode to
|
|
recognize
|
|
<B>.TS</B>
|
|
|
|
and
|
|
<B>.TE</B>
|
|
|
|
even when followed by a character other than space or newline.
|
|
Leader characters (\a) are handled as interpreted.
|
|
<DT id="2"><B>-v</B>
|
|
|
|
<DD>
|
|
Print the version number.
|
|
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>LANGUAGE OVERVIEW</H2>
|
|
|
|
|
|
<B>tbl</B>
|
|
|
|
expects to find table descriptions wrapped in the
|
|
<B>.TS</B>
|
|
|
|
(table start) and
|
|
<B>.TE</B>
|
|
|
|
(table end) macros.
|
|
Within each such table sections, another table can be defined by
|
|
using the request
|
|
<B>.T&</B>
|
|
|
|
before the final command
|
|
<B>.TE</B>.
|
|
|
|
Each table definition has the following structure:
|
|
<DL COMPACT>
|
|
<DT id="3"><I>Global options</I>
|
|
|
|
<DD>
|
|
This is optional.
|
|
This table part can use several of these options distributed in 1 or
|
|
more lines.
|
|
The
|
|
<I>global option part</I>
|
|
|
|
must always be finished by a
|
|
<B>semi-colon ; .</B>
|
|
|
|
<DT id="4"><I>Table format specification</I>
|
|
|
|
<DD>
|
|
This part must be given, it is not optional.
|
|
It determines the number of columns (cells) of the table.
|
|
Moreover each cell is classified by being central, left adjusted, or
|
|
numerical, etc.
|
|
This specification can have several lines, but must be finished by a
|
|
<B>dot .</B>
|
|
|
|
at the end of the last line.
|
|
After each cell definition,
|
|
<I>column specifiers</I>
|
|
|
|
can be appended, but that's optional.
|
|
</DL>
|
|
<P>
|
|
|
|
Cells are separated by a tab character by default.
|
|
That can be changed by the
|
|
<I>global option</I>
|
|
|
|
<B>tab(</B><I>c</I><B>)</B>,
|
|
where
|
|
<I>c</I>
|
|
|
|
is an arbitrary character.
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H2>SIMPLE EXAMPLES</H2>
|
|
|
|
|
|
The easiest table definition is.
|
|
<DL COMPACT><DT id="5"><DD>
|
|
|
|
.TS
|
|
c c c .
|
|
This<TT> </TT>is<TT> </TT>centered<BR>
|
|
Well,<TT> </TT>this<TT> </TT>also<BR>
|
|
.TE
|
|
|
|
</DL>
|
|
|
|
By using
|
|
<B>c c</B>
|
|
|
|
<B>c</B>,
|
|
|
|
each cell in the whole table will be centered.
|
|
The separating character is here the default
|
|
<I>tab</I>.
|
|
|
|
<P>
|
|
|
|
The result is
|
|
<DL COMPACT><DT id="6"><DD>
|
|
<TABLE>
|
|
<TR VALIGN=top><TD ALIGN=center>This</TD><TD ALIGN=center>is</TD><TD ALIGN=center>centered<BR></TD></TR>
|
|
<TR VALIGN=top><TD ALIGN=center>Well,</TD><TD ALIGN=center>this</TD><TD ALIGN=center>also<BR></TD></TR>
|
|
</TABLE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
This definition is identical to
|
|
<DL COMPACT><DT id="7"><DD>
|
|
|
|
.TS
|
|
tab(@);
|
|
ccc.
|
|
This@<A HREF="mailto:is@centered">is@centered</A>
|
|
Well,@<A HREF="mailto:this@also">this@also</A>
|
|
.TE
|
|
|
|
</DL>
|
|
|
|
Here, the separating tab character is changed to the letter
|
|
<B>@</B>.
|
|
|
|
<P>
|
|
|
|
Moreover a title can be added and the centering directions can be
|
|
changed to many other formats:
|
|
<DL COMPACT><DT id="8"><DD>
|
|
|
|
.TS
|
|
tab(@);
|
|
c s s
|
|
l c n .
|
|
Title
|
|
<A HREF="mailto:left@centers">left@centers</A>@123
|
|
<A HREF="mailto:another@number">another@number</A>@75
|
|
.TE
|
|
|
|
</DL>
|
|
|
|
The result is
|
|
<DL COMPACT><DT id="9"><DD>
|
|
<TABLE>
|
|
<TR VALIGN=top><TD ALIGN=center COLSPAN=3>Title<BR></TD></TR>
|
|
<TR VALIGN=top><TD>left</TD><TD ALIGN=center>centers</TD><TD ALIGN=right>123 <BR></TD></TR>
|
|
<TR VALIGN=top><TD>another</TD><TD ALIGN=center>number</TD><TD ALIGN=right>75 <BR></TD></TR>
|
|
</TABLE>
|
|
|
|
</DL>
|
|
|
|
Here
|
|
<B>l</B>
|
|
|
|
means
|
|
<I>left-justified</I>,
|
|
|
|
and
|
|
<B>n</B>
|
|
|
|
means
|
|
<I>numerical</I>,
|
|
|
|
which is here
|
|
<I>right-justified</I>.
|
|
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H2>USAGE</H2>
|
|
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Global options</H3>
|
|
|
|
|
|
The line immediately following the
|
|
<B>.TS</B>
|
|
|
|
macro may contain any of the following global options (ignoring the
|
|
case of characters - Unix tbl only accepts options with all
|
|
characters lowercase or all characters uppercase), separated by
|
|
spaces, tabs, or commas:
|
|
<DL COMPACT>
|
|
<DT id="10"><B>allbox</B>
|
|
|
|
<DD>
|
|
Enclose each item of the table in a box.
|
|
<DT id="11"><B>box</B>
|
|
|
|
<DD>
|
|
Enclose the table in a box.
|
|
<DT id="12"><B>center</B>
|
|
|
|
<DD>
|
|
Center the table (default is left-justified).
|
|
The alternative keyword name
|
|
<B>centre</B>
|
|
|
|
is also recognized (this is a GNU tbl extension).
|
|
<DT id="13"><B>decimalpoint(</B><I>c</I><B>)</B>
|
|
|
|
<DD>
|
|
Set the character to be recognized as the decimal point in numeric
|
|
columns (GNU tbl only).
|
|
<DT id="14"><B>delim(</B><I>xy</I><B>)</B>
|
|
|
|
<DD>
|
|
Use
|
|
<I>x</I>
|
|
|
|
and~<I>y</I>
|
|
|
|
as start and end delimiters for
|
|
<B><A HREF="/cgi-bin/man/man2html?1+eqn">eqn</A></B>(1).
|
|
|
|
<DT id="15"><B>doublebox</B>
|
|
|
|
<DD>
|
|
Enclose the table in a double box.
|
|
<DT id="16"><B>doubleframe</B>
|
|
|
|
<DD>
|
|
Same as doublebox (GNU tbl only).
|
|
<DT id="17"><B>expand</B>
|
|
|
|
<DD>
|
|
Make the table as wide as the current line length (providing a column
|
|
separation factor).
|
|
Ignored if one or more 'x' column specifiers are used (see
|
|
below).
|
|
<DT id="18"><DD>
|
|
In case the sum of the column widths is larger than the current line length,
|
|
the column separation factor is set to zero; such tables extend into the
|
|
right margin, and there is no column separation at all.
|
|
<DT id="19"><B>frame</B>
|
|
|
|
<DD>
|
|
Same as box (GNU tbl only).
|
|
<DT id="20"><B>linesize(</B><I>n</I><B>)</B>
|
|
|
|
<DD>
|
|
Set lines or rules (e.g. from
|
|
<B>box</B>)
|
|
|
|
in
|
|
<I>n</I>-point
|
|
|
|
type.
|
|
<DT id="21"><B>nokeep</B>
|
|
|
|
<DD>
|
|
Don't use diversions to prevent page breaks (GNU tbl only).
|
|
Normally
|
|
<B>tbl</B>
|
|
|
|
attempts to prevent undesirable breaks in boxed tables by using diversions.
|
|
This can sometimes interact badly with macro packages' own use of
|
|
diversions---when footnotes, for example, are used.
|
|
<DT id="22"><B>nospaces</B>
|
|
|
|
<DD>
|
|
Ignore leading and trailing spaces in data items (GNU tbl only).
|
|
<DT id="23"><B>nowarn</B>
|
|
|
|
<DD>
|
|
Turn off warnings related to tables exceeding the current line width
|
|
(GNU tbl only).
|
|
<DT id="24"><B>tab(</B><I>x</I><B>)</B>
|
|
|
|
<DD>
|
|
Use the character
|
|
<I>x</I>
|
|
|
|
instead of a tab to separate items in a line of input data.
|
|
</DL>
|
|
<P>
|
|
|
|
The global options must end with a semicolon.
|
|
There might be whitespace between an option and its argument in
|
|
parentheses.
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Table format specification</H3>
|
|
|
|
|
|
After global options come lines describing the format of each line of
|
|
the table.
|
|
Each such format line describes one line of the table itself, except
|
|
that the last format line (which you must end with a period) describes
|
|
all remaining lines of the table.
|
|
A single-key character describes each column of each line of the table.
|
|
Key characters can be separated by spaces or tabs.
|
|
You may run format specifications for multiple lines together on the
|
|
same line by separating them with commas.
|
|
<P>
|
|
|
|
You may follow each key character with specifiers that determine the
|
|
font and point size of the corresponding item, that determine column
|
|
width, inter-column spacing, etc.
|
|
<P>
|
|
|
|
The longest format line defines the number of columns in the table;
|
|
missing format descriptors at the end of format lines are assumed to
|
|
be~<B>L</B>.
|
|
|
|
Extra columns in the data (which have no corresponding format entry)
|
|
are ignored.
|
|
<P>
|
|
|
|
The available key characters are:
|
|
<DL COMPACT>
|
|
<DT id="25"><B>a</B>,<B>A</B>
|
|
|
|
<DD>
|
|
Center longest line in this column and then left-justifies all other
|
|
lines in this column with respect to that centered line.
|
|
The idea is to use such alphabetic subcolumns (hence the name of the
|
|
key character) in combination with~
|
|
<B>L</B>;
|
|
|
|
they are called subcolumns because
|
|
<B>A</B>~items
|
|
|
|
are indented by~1n relative to
|
|
<B>L</B>~entries.
|
|
|
|
Example:
|
|
<DL COMPACT><DT id="26"><DD>
|
|
<DL COMPACT>
|
|
<DT id="27"><DD>
|
|
|
|
.TS
|
|
tab(;);
|
|
ln,an.
|
|
item one;1
|
|
subitem two;2
|
|
subitem three;3
|
|
.T&
|
|
ln,an.
|
|
item eleven;11
|
|
subitem twentytwo;22
|
|
subitem thirtythree;33
|
|
.TE
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="28"><DD>
|
|
Result:
|
|
<DL COMPACT><DT id="29"><DD>
|
|
<DL COMPACT>
|
|
<DT id="30"><DD>
|
|
<TABLE>
|
|
<TR VALIGN=top><TD>item one</TD><TD ALIGN=right>1 <BR></TD></TR>
|
|
<TR VALIGN=top><TD>subitem two</TD><TD ALIGN=right>2 <BR></TD></TR>
|
|
<TR VALIGN=top><TD>subitem three</TD><TD ALIGN=right>3 <BR></TD></TR>
|
|
<TR VALIGN=top><TD>item eleven</TD><TD ALIGN=right>11 <BR></TD></TR>
|
|
<TR VALIGN=top><TD>subitem twentytwo</TD><TD ALIGN=right>22 <BR></TD></TR>
|
|
<TR VALIGN=top><TD>subitem thirtythree</TD><TD ALIGN=right>33 <BR></TD></TR>
|
|
</TABLE>
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="31"><B>c</B>,<B>C</B>
|
|
|
|
<DD>
|
|
Center item within the column.
|
|
<DT id="32"><B>l</B>,<B>L</B>
|
|
|
|
<DD>
|
|
Left-justify item within the column.
|
|
<DT id="33"><B>n</B>,<B>N</B>
|
|
|
|
<DD>
|
|
Numerically justify item in the column: Units positions of numbers are
|
|
aligned vertically.
|
|
If there is one or more dots adjacent to a digit, use the rightmost one for
|
|
vertical alignment.
|
|
If there is no dot, use the rightmost digit for vertical alignment;
|
|
otherwise, center the item within the column.
|
|
Alignment can be forced to a certain position using '\&';
|
|
if there is one or more instances of this special (non-printing)
|
|
character present within the data, use the leftmost one for alignment.
|
|
Example:
|
|
<DL COMPACT><DT id="34"><DD>
|
|
<DL COMPACT>
|
|
<DT id="35"><DD>
|
|
|
|
.TS
|
|
n.
|
|
1
|
|
1.5
|
|
1.5.3
|
|
abcde
|
|
a\&bcde
|
|
.TE
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="36"><DD>
|
|
Result:
|
|
<DL COMPACT><DT id="37"><DD>
|
|
<DL COMPACT>
|
|
<DT id="38"><DD>
|
|
<TABLE>
|
|
<TR VALIGN=top><TD ALIGN=right>1 <BR></TD></TR>
|
|
<TR VALIGN=top><TD ALIGN=right>1.5 <BR></TD></TR>
|
|
<TR VALIGN=top><TD ALIGN=right>1.5.3 <BR></TD></TR>
|
|
<TR VALIGN=top><TD ALIGN=right>abcde <BR></TD></TR>
|
|
<TR VALIGN=top><TD ALIGN=right>abcde <BR></TD></TR>
|
|
</TABLE>
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="39"><DD>
|
|
If numerical entries are combined with
|
|
<B>L</B>
|
|
|
|
or
|
|
<B>R</B>~entries
|
|
|
|
- this can happen if the table format is changed with
|
|
<B>.T&</B>
|
|
|
|
-
|
|
center the widest
|
|
<I>number</I>
|
|
|
|
(of the data entered under the
|
|
<B>N</B>~specifier
|
|
|
|
regime) relative to the widest
|
|
<B>L</B>
|
|
|
|
or
|
|
<B>R</B>~entry,
|
|
|
|
preserving the alignment of all numerical entries.
|
|
Contrary to
|
|
<B>A</B>~type
|
|
|
|
entries, there is no extra indentation.
|
|
<DT id="40"><DD>
|
|
Using equations (to be processed with
|
|
<B>eqn</B>)
|
|
|
|
within columns which use the
|
|
<B>N</B>~specifier
|
|
|
|
is problematic in most cases due to
|
|
<B>tbl</B>'s
|
|
|
|
algorithm for finding the vertical alignment, as described above.
|
|
Using the global
|
|
<B>delim</B>
|
|
|
|
option, however, it is possible to make
|
|
<B>tbl</B>
|
|
|
|
ignore the data within
|
|
<B>eqn</B>
|
|
|
|
delimiters for that purpose.
|
|
<DT id="41"><B>r</B>,<B>R</B>
|
|
|
|
<DD>
|
|
Right-justify item within the column.
|
|
<DT id="42"><B>s</B>,<B>S</B>
|
|
|
|
<DD>
|
|
Span previous item on the left into this column.
|
|
Not allowed for the first column.
|
|
<DT id="43"><B>^</B>
|
|
|
|
<DD>
|
|
Span down entry from previous row in this column.
|
|
Not allowed for the first row.
|
|
<DT id="44"><B>_</B>,<B>-</B>
|
|
|
|
<DD>
|
|
Replace this entry with a horizontal line.
|
|
Note that '_' and '-' can be used for table fields only,
|
|
not for column separator lines.
|
|
<DT id="45"><B>=</B>
|
|
|
|
<DD>
|
|
Replace this entry with a double horizontal line.
|
|
Note that '=' can be used for table fields only,
|
|
not for column separator lines.
|
|
<DT id="46"><B>|</B>
|
|
|
|
<DD>
|
|
The corresponding column becomes a vertical rule (if two of these are
|
|
adjacent, a double vertical rule).
|
|
</DL>
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
To change the data format within a table, use the
|
|
<B>.T&</B>
|
|
|
|
command (at the start of a line).
|
|
It is followed by format and data lines (but no global options)
|
|
similar to the
|
|
<B>.TS</B>
|
|
|
|
request.
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H3>Column specifiers</H3>
|
|
|
|
|
|
Here are the specifiers that can appear in suffixes to column key
|
|
letters (in any order):
|
|
<DL COMPACT>
|
|
<DT id="47"><B>b</B>,<B>B</B>
|
|
|
|
<DD>
|
|
Short form of
|
|
<B>fB</B>
|
|
|
|
(make affected entries bold).
|
|
<DT id="48"><B>d</B>,<B>D</B>
|
|
|
|
<DD>
|
|
Start an item that vertically spans rows,
|
|
using the '^' column specifier or '\^' data item,
|
|
at the bottom of its range rather
|
|
than vertically centering it (GNU tbl only).
|
|
Example:
|
|
<DL COMPACT><DT id="49"><DD>
|
|
<DL COMPACT>
|
|
<DT id="50"><DD>
|
|
|
|
.TS
|
|
tab(;) allbox;
|
|
l l
|
|
l ld
|
|
r ^
|
|
l rd.
|
|
0000;foobar
|
|
T{
|
|
1111
|
|
.br
|
|
2222
|
|
T};foo
|
|
r;
|
|
T{
|
|
3333
|
|
.br
|
|
4444
|
|
T};bar
|
|
\^;\^
|
|
.TE
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="51"><DD>
|
|
Result:
|
|
<DL COMPACT><DT id="52"><DD>
|
|
<DL COMPACT>
|
|
<DT id="53"><DD>
|
|
<TABLE BORDER>
|
|
<TR VALIGN=top><TD>0000</TD><TD>foobar<BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
1111
|
|
<BR>
|
|
|
|
2222
|
|
</TD><TD VALIGN=center ROWSPAN=2>foo<BR></TD></TR>
|
|
<TR VALIGN=top><TD ALIGN=right>r</TD></TR>
|
|
<TR VALIGN=top><TD VALIGN=center ROWSPAN=2>
|
|
3333
|
|
<BR>
|
|
|
|
4444
|
|
</TD><TD ALIGN=right VALIGN=center ROWSPAN=2>bar<BR></TD></TR>
|
|
<TR VALIGN=top></TR>
|
|
</TABLE>
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="54"><B>e</B>,<B>E</B>
|
|
|
|
<DD>
|
|
Make equally-spaced columns.
|
|
All columns marked with this specifier get the same width; this happens
|
|
after the affected column widths have been computed (this means that the
|
|
largest width value rules).
|
|
<DT id="55"><B>f</B>,<B>F</B>
|
|
|
|
<DD>
|
|
Either of these specifiers may be followed by a font name (either one or two
|
|
characters long), font number (a single digit), or long name in parentheses
|
|
(the last form is a GNU tbl extension).
|
|
A one-letter font name must be separated by one or more blanks from whatever
|
|
follows.
|
|
<DT id="56"><B>i</B>,<B>I</B>
|
|
|
|
<DD>
|
|
Short form of
|
|
<B>fI</B>
|
|
|
|
(make affected entries italic).
|
|
<DT id="57"><B>m</B>,<B>M</B>
|
|
|
|
<DD>
|
|
This is a GNU tbl extension.
|
|
Either of these specifiers may be followed by a macro name
|
|
(either one or two characters long),
|
|
or long name in parentheses.
|
|
A one-letter macro name must be separated by one or more blanks from
|
|
whatever follows.
|
|
The macro which name can be specified here must be defined before
|
|
creating the table.
|
|
It is called just before the table's cell text is output.
|
|
As implemented currently, this macro is only called if block input is
|
|
used, that is, text between 'T{' and 'T}'.
|
|
The macro should contain only simple
|
|
<B>troff</B>
|
|
|
|
requests to change the text block formatting, like text adjustment,
|
|
hyphenation, size, or font.
|
|
The macro is called
|
|
<I>after</I>
|
|
|
|
other cell modifications like
|
|
<B>b</B>,
|
|
|
|
<B>f</B>
|
|
|
|
or
|
|
<B>v</B>
|
|
|
|
are output.
|
|
Thus the macro can overwrite other modification specifiers.
|
|
<DT id="58"><B>p</B>,<B>P</B>
|
|
|
|
<DD>
|
|
Followed by a number, this does a point size change for the affected fields.
|
|
If signed, the current point size is incremented or decremented (using
|
|
a signed number instead of a signed digit is a GNU tbl extension).
|
|
A point size specifier followed by a column separation number must be
|
|
separated by one or more blanks.
|
|
<DT id="59"><B>t</B>,<B>T</B>
|
|
|
|
<DD>
|
|
Start an item vertically spanning rows at the top of its range rather than
|
|
vertically centering it.
|
|
<DT id="60"><B>u</B>,<B>U</B>
|
|
|
|
<DD>
|
|
Move the corresponding column up one half-line.
|
|
<DT id="61"><B>v</B>,<B>V</B>
|
|
|
|
<DD>
|
|
Followed by a number, this indicates the vertical line spacing to be
|
|
used in a multi-line table entry.
|
|
If signed, the current vertical line spacing is incremented or
|
|
decremented (using a signed number instead of a signed digit is a GNU
|
|
tbl extension).
|
|
A vertical line spacing specifier followed by a column separation
|
|
number must be separated by one or more blanks.
|
|
No effect if the corresponding table entry isn't a text block.
|
|
<DT id="62"><B>w</B>,<B>W</B>
|
|
|
|
<DD>
|
|
Minimum column width value.
|
|
Must be followed either by a
|
|
<B><A HREF="/cgi-bin/man/man2html?1+troff">troff</A></B>(1)
|
|
|
|
width expression in parentheses or a unitless integer.
|
|
If no unit is given, en units are used.
|
|
Also used as the default line length for included text blocks.
|
|
If used multiple times to specify the width for a particular column,
|
|
the last entry takes effect.
|
|
<DT id="63"><B>x</B>,<B>X</B>
|
|
|
|
<DD>
|
|
An expanded column.
|
|
After computing all column widths without an
|
|
<B>x</B>~specifier,
|
|
|
|
use the remaining line width for this column.
|
|
If there is more than one expanded column, distribute the remaining
|
|
horizontal space evenly among the affected columns (this is a GNU
|
|
extension).
|
|
This feature has the same effect as specifying a minimum column width.
|
|
<DT id="64"><B>z</B>,<B>Z</B>
|
|
|
|
<DD>
|
|
Ignore the corresponding column for width-calculation purposes, this
|
|
is, don't use the fields but only the specifiers of this column to
|
|
compute its width.
|
|
</DL>
|
|
<P>
|
|
|
|
A number suffix on a key character is interpreted as a column
|
|
separation in en units (multiplied in proportion if the
|
|
<B>expand</B>
|
|
|
|
option is on - in case of overfull tables this might be zero).
|
|
Default separation is 3n.
|
|
<P>
|
|
|
|
The column
|
|
specifier~<B>x</B>
|
|
|
|
is mutually exclusive with
|
|
<B>e</B>
|
|
|
|
and~<B>w</B>
|
|
|
|
(but
|
|
<B>e</B>
|
|
|
|
is not mutually exclusive
|
|
with~<B>w</B>);
|
|
|
|
if specified multiple times for a particular column, the last entry takes
|
|
effect:
|
|
<B>x</B>~unsets
|
|
|
|
both
|
|
<B>e</B>
|
|
|
|
and~<B>w</B>,
|
|
|
|
while either
|
|
<B>e</B>
|
|
|
|
or
|
|
<B>w</B>
|
|
|
|
overrides~<B>x</B>.
|
|
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H3>Table data</H3>
|
|
|
|
|
|
The format lines are followed by lines containing the actual data for the
|
|
table, followed finally by
|
|
<B>.TE</B>.
|
|
|
|
Within such data lines, items are normally separated by tab characters
|
|
(or the character specified with the
|
|
<B>tab</B>
|
|
|
|
option).
|
|
Long input lines can be broken across multiple lines if the last
|
|
character on the line is '\' (which vanishes after
|
|
concatenation).
|
|
<P>
|
|
|
|
Note that
|
|
<B>tbl</B>
|
|
|
|
computes the column widths line by line, applying \w on each entry
|
|
which isn't a text block.
|
|
As a consequence, constructions like
|
|
<DL COMPACT>
|
|
<DT id="65"><DD>
|
|
|
|
.TS
|
|
c,l.
|
|
\s[20]MM
|
|
MMMM
|
|
.TE
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
fail; you must either say
|
|
<DL COMPACT>
|
|
<DT id="66"><DD>
|
|
|
|
.TS
|
|
cp20,lp20.
|
|
MM
|
|
MMMM
|
|
.TE
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
or
|
|
<DL COMPACT>
|
|
<DT id="67"><DD>
|
|
|
|
.TS
|
|
c,l.
|
|
\s[20]MM
|
|
\s[20]MMMM
|
|
.TE
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
A dot starting a line, followed by anything but a digit is handled as
|
|
a troff command, passed through without changes.
|
|
The table position is unchanged in this case.
|
|
<P>
|
|
|
|
If a data line consists of only '_' or '=', a single
|
|
or double line, respectively, is drawn across the table at that point;
|
|
if a single item in a data line consists of only '_' or
|
|
'=', then that item is replaced by a single or double line,
|
|
joining its neighbours.
|
|
If a data item consists only of '\_' or '\=',
|
|
a single or double line, respectively, is drawn across the field at
|
|
that point which does not join its neighbours.
|
|
<P>
|
|
|
|
A data item consisting only of '\Rx' ('x' any
|
|
character) is replaced by repetitions of character 'x' as wide
|
|
as the column (not joining its neighbours).
|
|
<P>
|
|
|
|
A data item consisting only of '\^' indicates that the
|
|
field immediately above spans downward over this row.
|
|
|
|
<A NAME="lbAM"> </A>
|
|
<H3>Text blocks</H3>
|
|
|
|
|
|
A text block can be used to enter data as a single entry which would
|
|
be too long as a simple string between tabs.
|
|
It is started with 'T{' and closed with 'T}'.
|
|
The former must end a line, and the latter must start a line, probably
|
|
followed by other data columns (separated with tabs or the character
|
|
given with the
|
|
<B>tab</B>
|
|
|
|
global option).
|
|
<P>
|
|
|
|
By default, the text block is formatted with the settings which were
|
|
active before entering the table, possibly overridden by the
|
|
<B>m</B>,
|
|
|
|
<B>v</B>,
|
|
|
|
and
|
|
<B>w</B>
|
|
|
|
tbl specifiers.
|
|
For example, to make all text blocks ragged-right, insert
|
|
<B>.na</B>
|
|
|
|
right before the starting
|
|
<B>.TS</B>
|
|
|
|
(and
|
|
<B>.ad</B>
|
|
|
|
after the table).
|
|
<P>
|
|
|
|
If either 'w' or 'x' specifiers are not given for
|
|
<I>all</I>
|
|
|
|
columns of a text block span, the default length of the text block (to
|
|
be more precise, the line length used to process the text block
|
|
diversion) is computed as LmuC/(N+1), where 'L' is the
|
|
current line length, 'C' the number of columns spanned by the
|
|
text block, and 'N' the total number of columns in the table.
|
|
Note, however, that the actual diversion width as returned in register
|
|
<B>\n[dl]</B>
|
|
|
|
is used eventually as the text block width.
|
|
If necessary, you can also control the text block width with a direct
|
|
insertion of a
|
|
<B>.ll</B>
|
|
|
|
request right after 'T{'.
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H3>Miscellaneous</H3>
|
|
|
|
|
|
The number register
|
|
<B>\n[TW]</B>
|
|
|
|
holds the table width; it can't be used within the table itself
|
|
but is defined right before calling
|
|
<B>.TE</B>
|
|
|
|
so that this macro can make use of it.
|
|
<P>
|
|
|
|
<B>tbl</B>
|
|
|
|
also defines a macro
|
|
<B>.T#</B>
|
|
|
|
which produces the bottom and side lines of a boxed table.
|
|
While
|
|
<B>tbl</B>
|
|
|
|
does call this macro itself at the end of the table, it can be used by
|
|
macro packages to create boxes for multi-page tables by calling it within the
|
|
page footer.
|
|
An example of this is shown by the
|
|
<B>-ms</B>
|
|
|
|
macros which provide this functionality if a table starts with
|
|
<B>.TS H</B>
|
|
|
|
instead of the standard call to the
|
|
<B>.TS</B>
|
|
|
|
macro.
|
|
|
|
<A NAME="lbAO"> </A>
|
|
<H2>INTERACTION WITH EQN</H2>
|
|
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+tbl">tbl</A></B>(1)
|
|
|
|
should always be called before
|
|
<B><A HREF="/cgi-bin/man/man2html?1+eqn">eqn</A></B>(1)
|
|
|
|
(<B><A HREF="/cgi-bin/man/man2html?1+groff">groff</A></B>(1)
|
|
|
|
automatically takes care of the correct order of preprocessors).
|
|
|
|
<A NAME="lbAP"> </A>
|
|
<H2>GNU TBL ENHANCEMENTS</H2>
|
|
|
|
|
|
There is no limit on the number of columns in a table, nor any limit on the
|
|
number of text blocks.
|
|
All the lines of a table are considered in deciding column widths, not just
|
|
the first 200.
|
|
Table continuation
|
|
(<B>.T&</B>)
|
|
|
|
lines are not restricted to the first 200 lines.
|
|
<P>
|
|
|
|
Numeric and alphabetic items may appear in the same column.
|
|
<P>
|
|
|
|
Numeric and alphabetic items may span horizontally.
|
|
<P>
|
|
|
|
<B>tbl</B>
|
|
|
|
uses register, string, macro and diversion names beginning with the digit~<B>3</B>.
|
|
|
|
When using
|
|
<B>tbl</B>
|
|
|
|
you should avoid using any names beginning with a~<B>3</B>.
|
|
|
|
|
|
<A NAME="lbAQ"> </A>
|
|
<H2>GNU TBL WITHIN MACROS</H2>
|
|
|
|
|
|
Since
|
|
<B>tbl</B>
|
|
|
|
defines its own macros (right before each table) it is necessary to use
|
|
an 'end-of-macro' macro.
|
|
Additionally, the escape character has to be switched off.
|
|
Here an example.
|
|
<DL COMPACT>
|
|
<DT id="68"><DD>
|
|
|
|
.eo
|
|
.de ATABLE ..
|
|
.TS
|
|
allbox tab(;);
|
|
cl.
|
|
\$1;\$2
|
|
.TE
|
|
...
|
|
.ec
|
|
.ATABLE A table
|
|
.ATABLE Another table
|
|
.ATABLE And "another one"
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
Note, however, that not all features of
|
|
<B>tbl</B>
|
|
|
|
can be wrapped into a macro because
|
|
<B>tbl</B>
|
|
|
|
sees the input earlier than
|
|
<B>troff</B>.
|
|
|
|
For example, number formatting with vertically aligned decimal points
|
|
fails if those numbers are passed on as macro parameters because
|
|
decimal point alignment is handled by
|
|
<B>tbl</B>
|
|
|
|
itself: It only sees '\$1', '\$2', etc., and
|
|
therefore can't recognize the decimal point.
|
|
|
|
<A NAME="lbAR"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
|
|
You should use
|
|
<B>.TS H</B>/<B>.TH</B>
|
|
|
|
in conjunction with a supporting macro package for
|
|
<I>all</I>
|
|
|
|
multi-page boxed tables.
|
|
If there is no header that you wish to appear at the top of each page
|
|
of the table, place the
|
|
<B>.TH</B>
|
|
|
|
line immediately after the format section.
|
|
Do not enclose a multi-page table within keep/release macros,
|
|
or divert it in any other way.
|
|
<P>
|
|
|
|
A text block within a table must be able to fit on one page.
|
|
<P>
|
|
|
|
The
|
|
<B>bp</B>
|
|
|
|
request cannot be used to force a page-break in a multi-page table.
|
|
Instead, define
|
|
<B>BP</B>
|
|
|
|
as follows
|
|
<DL COMPACT>
|
|
<DT id="69"><DD>
|
|
|
|
.de BP
|
|
. ie '\\n(.z'' .bp \\$1
|
|
. el \!.BP \\$1
|
|
..
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
and use
|
|
<B>BP</B>
|
|
|
|
instead of
|
|
<B>bp</B>.
|
|
|
|
<P>
|
|
|
|
Using \a directly in a table to get leaders does not work (except in
|
|
compatibility mode).
|
|
This is correct behaviour: \a is an
|
|
<B>uninterpreted</B>
|
|
|
|
leader.
|
|
To get leaders use a real leader, either by using a control A or like
|
|
this:
|
|
<DL COMPACT>
|
|
<DT id="70"><DD>
|
|
|
|
.ds a \a
|
|
.TS
|
|
tab(;);
|
|
<A HREF="/cgi-bin/man/man2html?1i+lw">lw</A>(1i) l.
|
|
A\*a;B
|
|
.TE
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
A leading and/or trailing '|' in a format line, such as
|
|
<DL COMPACT>
|
|
<DT id="71"><DD>
|
|
|
|
|l r|.
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
gives output which has a 1n~space between the resulting
|
|
bordering vertical rule and the content of the adjacent column,
|
|
as in
|
|
<DL COMPACT>
|
|
<DT id="72"><DD>
|
|
|
|
.TS
|
|
tab(#);
|
|
|l r|.
|
|
left column#right column
|
|
.TE
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
If it is desired to have zero space (so that the rule touches
|
|
the content), this can be achieved by introducing extra "dummy"
|
|
columns, with no content and zero separation, before and/or after,
|
|
as in
|
|
<DL COMPACT>
|
|
<DT id="73"><DD>
|
|
|
|
.TS
|
|
tab(#);
|
|
r0|l r0|l.
|
|
#left column#right column#
|
|
.TE
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
The resulting "dummy" columns are invisible and have zero width;
|
|
note that such columns usually don't work with TTY devices.
|
|
|
|
<A NAME="lbAS"> </A>
|
|
<H2>REFERENCE</H2>
|
|
|
|
|
|
Lesk, M.E.: "TBL - A Program to Format Tables".
|
|
For copyright reasons it cannot be included in the groff distribution,
|
|
but copies can be found with a title search on the World Wide Web.
|
|
|
|
<A NAME="lbAT"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+groff">groff</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+troff">troff</A></B>(1)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="74"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="75"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="76"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="77"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="78"><A HREF="#lbAF">LANGUAGE OVERVIEW</A><DD>
|
|
<DT id="79"><A HREF="#lbAG">SIMPLE EXAMPLES</A><DD>
|
|
<DT id="80"><A HREF="#lbAH">USAGE</A><DD>
|
|
<DL>
|
|
<DT id="81"><A HREF="#lbAI">Global options</A><DD>
|
|
<DT id="82"><A HREF="#lbAJ">Table format specification</A><DD>
|
|
<DT id="83"><A HREF="#lbAK">Column specifiers</A><DD>
|
|
<DT id="84"><A HREF="#lbAL">Table data</A><DD>
|
|
<DT id="85"><A HREF="#lbAM">Text blocks</A><DD>
|
|
<DT id="86"><A HREF="#lbAN">Miscellaneous</A><DD>
|
|
</DL>
|
|
<DT id="87"><A HREF="#lbAO">INTERACTION WITH EQN</A><DD>
|
|
<DT id="88"><A HREF="#lbAP">GNU TBL ENHANCEMENTS</A><DD>
|
|
<DT id="89"><A HREF="#lbAQ">GNU TBL WITHIN MACROS</A><DD>
|
|
<DT id="90"><A HREF="#lbAR">BUGS</A><DD>
|
|
<DT id="91"><A HREF="#lbAS">REFERENCE</A><DD>
|
|
<DT id="92"><A HREF="#lbAT">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:28 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|