gtbl
(1)
Name
gtbl - format tables for troff
Synopsis
gtbl [ -Cv ] [ files... ]
Description
User Commands GTBL(1)
NAME
gtbl - format tables for troff
SYNOPSIS
gtbl [ -Cv ] [ files... ]
DESCRIPTION
This manual page describes the GNU version of tbl, which is
part of the groff document formatting system. tbl compiles
descriptions of tables embedded within troff input files
into commands that are understood by troff. Normally, it
should be invoked using the -t option of groff. It is
highly compatible with Unix tbl. The output generated by
GNU tbl cannot be processed with Unix troff; it must be pro-
cessed with GNU troff. If no files are given on the command
line, the standard input will be read. A filename of - will
cause the standard input to be read.
OPTIONS
-C Enable compatibility mode to recognize .TS and .TE even
when followed by a character other than space or new-
line. Leader characters ([rs]a) are handled as inter-
preted.
-v Print the version number.
USAGE
tbl expects to find table descriptions wrapped in the .TS
(table start) and .TE (table end) macros. The line immedi-
ately following the .TS macro may contain any of the follow-
ing global options (ignoring the case of characters -- Unix
tbl only accepts options with all characters lowercase or
all characters uppercase):
center
Centers the table (default is left-justified). The
alternative keyword name centre is also recognized
(this is a GNU tbl extension).
delim(xy)
Use x and y as start and end delimiters for geqn(1).
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 item of the table in a box.
Groff Version 1.19Last change: 11 September 2004 1
User Commands GTBL(1)
frame
Same as box (GNU tbl only).
doubleframe
Same as doublebox (GNU tbl only).
tab(x)
Uses the character x instead of a tab to separate items
in a line of input data.
linesize(n)
Sets lines or rules (e.g. from box) in n-point type.
nokeep
Don't use diversions to prevent page breaks (GNU tbl
only). Normally tbl attempts to prevent undesirable
breaks in the table by using diversions. This can
sometimes interact badly with macro packages' own use
of diversions, when footnotes, for example, are used.
decimalpoint(c)
Set the character to be recognized as the decimal point
in numeric columns (GNU tbl only).
nospaces
Ignore leading and trailing spaces in data items (GNU
tbl only).
The global options must end with a semicolon. There might
be whitespace after an option and its argument in parenthe-
ses.
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. You may run format specs
for multiple lines together on the same line by separating
them with commas.
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.
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 `L'. Extra columns in the data (which
have no corresponding format entry) are ignored.
The available key characters are:
Groff Version 1.19Last change: 11 September 2004 2
User Commands GTBL(1)
c,C Centers item within the column.
r,R Right-justifies item within the column.
l,L Left-justifies item within the column.
n,N Numerically justifies item in the column: Units posi-
tions of numbers are aligned vertically.
s,S Spans previous item on the left into this column.
a,A Centers longest line in this column and then left-jus-
tifies all other lines in this column with respect to
that centered line.
^ Spans down entry from previous row in this column.
_,- Replaces this entry with a horizontal line.
= Replaces this entry with a double horizontal line.
| The corresponding column becomes a vertical rule (if
two of these are adjacent, a double vertical rule).
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 ta-
ble.
Here are the specifiers that can appear in suffixes to col-
umn key letters:
b,B Short form of fB (make affected entries bold).
i,I Short form of fI (make affected entries italic).
t,T Start an item vertically spanning rows at the top of
its range rather than vertically centering it.
d,D Start an item vertically spanning rows at the bottom of
its range rather than vertically centering it (GNU tbl
only).
v,V 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 incre-
mented 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.
Groff Version 1.19Last change: 11 September 2004 3
User Commands GTBL(1)
f,F 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.
p,P 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.
w,W Minimal column width value. Must be followed either by
a gtroff(1) width expression in parentheses or a unit-
less 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.
x,X This is a GNU tbl extension. Either of these speci-
fiers 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 troff requests to change the text block format-
ting, like text adjustment, hyphenation, size, or font.
The macro is called after other cell modifications like
b, f or v are output. Thus the macro can overwrite
other modification specifiers.
e,E Make equally-spaced columns.
u,U Move the corresponding column up one half-line.
z,Z Ignore the corresponding column for width-calculation
purposes.
A number suffix on a key character is interpreted as a col-
umn separation in ens (multiplied in proportion if the
expand option is on). Default separation is 3n.
The format lines are followed by lines containing the actual
data for the table, followed finally by .TE. Within such
data lines, items are normally separated by tab characters
(or the character specified with the tab option). Long
Groff Version 1.19Last change: 11 September 2004 4
User Commands GTBL(1)
input lines can be broken across multiple lines if the last
character on the line is `\' (which vanishes after concate-
nation).
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.
If a data line consists of only `_' or `=', a single or dou-
ble 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.
A data item consisting only of `\Rx' (`x' any character) is
replaced by repetitions of character `x' as wide as the col-
umn (not joining its neighbours).
A data item consisting only of `\^' indicates that the field
immediately above spans downward over this row.
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 fol-
lowed by other data columns (separated with tabs). By
default, the text block is formatted with the settings which
were active before entering the table, possibly overridden
by the v and w tbl specifiers. For example, to make all
text blocks ragged-right, insert .na right before the start-
ing .TS (and .ad after the table).
To change the data format within a table, use the .T& com-
mand (at the start of a line). It is followed by format and
data lines (but no global options) similar to the .TS
request.
INTERACTION WITH GEQN
gtbl(1) should always be called before geqn(1) (groff(1)
automatically takes care of the correct order of preproces-
sors).
GNU TBL ENHANCEMENTS
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 (.T&) lines are not
restricted to the first 200 lines.
Groff Version 1.19Last change: 11 September 2004 5
User Commands GTBL(1)
Numeric and alphabetic items may appear in the same column.
Numeric and alphabetic items may span horizontally.
gtbl uses register, string, macro and diversion names begin-
ning with the digit 3. When using gtbl you should avoid
using any names beginning with a 3.
BUGS
You should use .TS H/.TH in conjunction with a supporting
macro package for all 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 .TH line immediately after the format
section. Do not enclose a multi-page table within
keep/release macros, or divert it in any other way.
A text block within a table must be able to fit on one page.
The bp request cannot be used to force a page-break in a
multi-page table. Instead, define BP as follows
.de BP
.ie '\\n(.z'' .bp \\$1
.el \!.BP \\$1
..
and use BP instead of bp.
Using \a directly in a table to get leaders will not work
(except in compatibility mode). This is correct behaviour:
\a is an uninterpreted leader. To get leaders use a real
leader, either by using a control A or like this:
.ds a \a
.TS
tab(;);
lw(1i) l.
A\*a;B
.TE
REFERENCE
Lesk, M.E.: "TBL -- A Program to Format Tables". For copy-
right reasons it cannot be included in the groff distribu-
tion, but copies can be found with a title search on the
World Wide Web.
ATTRIBUTES
See attributes(5) for descriptions of the following
attributes:
Groff Version 1.19Last change: 11 September 2004 6
User Commands GTBL(1)
+---------------+-----------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------------+
|Availability | text/groff/groff-core |
+---------------+-----------------------+
|Stability | Uncommitted |
+---------------+-----------------------+
SEE ALSO
groff(1), gtroff(1)
NOTES
This software was built from source available at
https://java.net/projects/solaris-userland. The original
community source was downloaded from
http://ftp.gnu.org/gnu/groff/groff-1.19.2.tar.gz
Further information about this software can be found on the
open source community website at http://www.gnu.org/soft-
ware/groff/.
Groff Version 1.19Last change: 11 September 2004 7