1TBL(1)                      General Commands Manual                     TBL(1)
2
3
4

NAME

6       tbl - format tables for troff
7

SYNOPSIS

9       tbl [-Cv] [file ...]
10

DESCRIPTION

12       This manual page describes the GNU version of tbl, which is part of the
13       groff document formatting system.  tbl compiles descriptions of  tables
14       embedded  within troff input files into commands that are understood by
15       troff.  Normally, it should be invoked using the -t  option  of  groff.
16       It is highly compatible with Unix tbl.  The output generated by GNU tbl
17       cannot be processed with Unix troff; it  must  be  processed  with  GNU
18       troff.  If no files are given on the command line or a filename of - is
19       given, the standard input is read.
20

OPTIONS

22       -C     Enable compatibility mode to recognize .TS  and  .TE  even  when
23              followed  by  a  character  other than space or newline.  Leader
24              characters (\a) are handled as interpreted.
25
26       -v     Print the version number.
27

LANGUAGE OVERVIEW

29       tbl expects to find table descriptions wrapped in the .TS (table start)
30       and  .TE  (table end) macros.  Within each such table sections, another
31       table can be defined by using the request .T& before the final  command
32       .TE.  Each table definition has the following structure:
33
34       Global options
35              This  is optional.  This table part can use several of these op‐
36              tions distributed in 1 or more lines.  The  global  option  part
37              must always be finished by a semi-colon ; .
38
39       Table format specification
40              This  part must be given, it is not optional.  It determines the
41              number of columns (cells) of the table.  Moreover each  cell  is
42              classified  by  being central, left adjusted, or numerical, etc.
43              This specification can have several lines, but must be  finished
44              by  a dot .  at the end of the last line.  After each cell defi‐
45              nition, column specifiers can be appended, but that's optional.
46
47       Cells are separated by a tab character by default.  That can be changed
48       by the global option tab(c), where c is an arbitrary character.
49

SIMPLE EXAMPLES

51       The easiest table definition is.
52              .TS
53              c c c .
54              This is   centered
55              Well,     this also
56              .TE
57       By  using  c  c  c, each cell in the whole table will be centered.  The
58       separating character is here the default tab.
59
60       The result is
61
62              This     is    centered
63              Well,   this     also
64
65       This definition is identical to
66              .TS
67              tab(@);
68              ccc.
69              This@is@centered
70              Well,@this@also
71              .TE
72       Here, the separating tab character is changed to the letter @.
73
74       Moreover a title can be added  and  the  centering  directions  can  be
75       changed to many other formats:
76              .TS
77              tab(@);
78              c s s
79              l c n .
80              Title
81              left@centers@123
82              another@number@75
83              .TE
84       The result is
85
86                       Title
87              left      centers   123
88              another   number     75
89       Here  l  means  left-justified,  and  n  means numerical, which is here
90       right-justified.
91

USAGE

93   Global options
94       The line immediately following the .TS macro may  contain  any  of  the
95       following  global  options  (ignoring the case of characters – Unix tbl
96       only accepts options with all characters lowercase  or  all  characters
97       uppercase), separated by spaces, tabs, or commas:
98
99       allbox Enclose each item of the table in a box.
100
101       box    Enclose the table in a box.
102
103       center Center  the  table (default is left-justified).  The alternative
104              keyword name centre is also recognized (this is a GNU tbl exten‐
105              sion).
106
107       decimalpoint(c)
108              Set  the  character to be recognized as the decimal point in nu‐
109              meric columns (GNU tbl only).
110
111       delim(xy)
112              Use x and y as start and end delimiters for eqn(1).
113
114       doublebox
115              Enclose the table in a double box.
116
117       doubleframe
118              Same as doublebox (GNU tbl only).
119
120       expand Make the table as wide as the current line length  (providing  a
121              column  separation  factor).   Ignored if one or more ‘x’ column
122              specifiers are used (see below).
123
124              In case the sum of the column widths is larger than the  current
125              line  length,  the column separation factor is set to zero; such
126              tables extend into the right margin, and there is no column sep‐
127              aration at all.
128
129       frame  Same as box (GNU tbl only).
130
131       linesize(n)
132              Set lines or rules (e.g. from box) in n-point type.
133
134       nokeep Don't  use  diversions  to  prevent  page breaks (GNU tbl only).
135              Normally tbl attempts to prevent undesirable breaks in boxed ta‐
136              bles  by  using  diversions.   This can sometimes interact badly
137              with macro packages' own use of diversions—when  footnotes,  for
138              example, are used.
139
140       nospaces
141              Ignore leading and trailing spaces in data items (GNU tbl only).
142
143       nowarn Turn  off  warnings related to tables exceeding the current line
144              width (GNU tbl only).
145
146       tab(x) Use the character x instead of a tab to separate items in a line
147              of input data.
148
149       The  global  options  must end with a semicolon.  There might be white‐
150       space between an option and its argument in parentheses.
151
152   Table format specification
153       After global options come lines describing the format of each  line  of
154       the  table.   Each such format line describes one line of the table it‐
155       self, except that the last format line (which you must end with  a  pe‐
156       riod) describes all remaining lines of the table.  A single-key charac‐
157       ter describes each column of each line of the  table.   Key  characters
158       can  be separated by spaces or tabs.  You may run format specifications
159       for multiple lines together on the same line by  separating  them  with
160       commas.
161
162       You  may  follow  each key character with specifiers that determine the
163       font and point size of the corresponding item,  that  determine  column
164       width, inter-column spacing, etc.
165
166       The  longest  format  line  defines the number of columns in the table;
167       missing format descriptors at the end of format lines  are  assumed  to
168       be  L.   Extra  columns in the data (which have no corresponding format
169       entry) are ignored.
170
171       The available key characters are:
172
173       a,A    Center longest line in this column and then  left-justifies  all
174              other  lines  in this column with respect to that centered line.
175              The idea is to use such alphabetic subcolumns (hence the name of
176              the  key  character) in combination with L; they are called sub‐
177              columns because A items are indented by 1n  relative  to  L  en‐
178              tries.  Example:
179
180                     .TS
181                     tab(;);
182                     ln,an.
183                     item one;1
184                     subitem two;2
185                     subitem three;3
186                     .T&
187                     ln,an.
188                     item eleven;11
189                     subitem twentytwo;22
190                     subitem thirtythree;33
191                     .TE
192
193              Result:
194
195                     item one                 1
196                      subitem two             2
197                      subitem three           3
198                     item eleven             11
199                      subitem twentytwo      22
200
201                      subitem thirtythree    33
202
203       c,C    Center item within the column.
204
205       l,L    Left-justify item within the column.
206
207       n,N    Numerically  justify item in the column: Units positions of num‐
208              bers are aligned vertically.  If there is one or more dots adja‐
209              cent  to  a digit, use the rightmost one for vertical alignment.
210              If there is no dot, use the rightmost digit for vertical  align‐
211              ment;  otherwise,  center the item within the column.  Alignment
212              can be forced to a certain position using ‘\&’; if there is  one
213              or  more  instances  of  this  special  (non-printing) character
214              present within the data, use the  leftmost  one  for  alignment.
215              Example:
216
217                     .TS
218                     n.
219                     1
220                     1.5
221                     1.5.3
222                     abcde
223                     a\&bcde
224                     .TE
225
226              Result:
227
228                       1
229                       1.5
230                     1.5.3
231                      abcde
232                       abcde
233
234              If numerical entries are combined with L or R entries – this can
235              happen if the table format is changed  with  .T&  –  center  the
236              widest number (of the data entered under the N specifier regime)
237              relative to the widest L or R entry, preserving the alignment of
238              all  numerical entries.  Contrary to A type entries, there is no
239              extra indentation.
240
241              Using equations (to be processed with eqn) within columns  which
242              use  the  N  specifier is problematic in most cases due to tbl's
243              algorithm for  finding  the  vertical  alignment,  as  described
244              above.   Using  the global delim option, however, it is possible
245              to make tbl ignore the data within eqn delimiters for that  pur‐
246              pose.
247
248       r,R    Right-justify item within the column.
249
250       s,S    Span  previous  item  on the left into this column.  Not allowed
251              for the first column.
252
253       ^      Span down entry from previous row in this column.   Not  allowed
254              for the first row.
255
256       _,-    Replace  this  entry  with a horizontal line.  Note that ‘_’ and
257              ‘-’ can be used for table fields only, not for column  separator
258              lines.
259
260       =      Replace this entry with a double horizontal line.  Note that ‘=’
261              can be used for table fields  only,  not  for  column  separator
262              lines.
263
264       |      The  corresponding  column  becomes  a  vertical rule (if two of
265              these are adjacent, a double vertical rule).
266
267       A vertical bar to the left of the first key letter or to the  right  of
268       the last one produces a line at the edge of the table.
269
270       To  change  the data format within a table, use the .T& command (at the
271       start of a line).  It is followed by format  and  data  lines  (but  no
272       global options) similar to the .TS request.
273
274   Column specifiers
275       Here  are the specifiers that can appear in suffixes to column key let‐
276       ters (in any order):
277
278       b,B    Short form of fB (make affected entries bold).
279
280       d,D    Start an item that vertically spans rows, using the  ‘^’  column
281              specifier  or  ‘\^’ data item, at the bottom of its range rather
282              than vertically centering it (GNU tbl only).  Example:
283
284                     .TS
285                     tab(;) allbox;
286                     l l
287                     l ld
288                     r ^
289                     l rd.
290                     0000;foobar
291                     T{
292                     1111
293                     .br
294                     2222
295                     T};foo
296                     r;
297                     T{
298                     3333
299                     .br
300                     4444
301                     T};bar
302                     \^;\^
303                     .TE
304
305              Result:
306
307                     ┌─────┬────────┐
308                     │0000 │ foobar │
309                     ├─────┼────────┤
310                     │1111 │        │
311                     │2222 │        │
312                     ├─────┤        │
313                     │   r │ foo    │
314                     ├─────┼────────┤
315                     │3333 │        │
316                     │4444 │    bar │
317                     └─────┴────────┘
318       e,E    Make equally-spaced columns.  All columns marked with this spec‐
319              ifier get the same width; this happens after the affected column
320              widths have been computed (this means  that  the  largest  width
321              value rules).
322
323       f,F    Either  of  these specifiers may be followed by a font name (ei‐
324              ther one or two characters long), font number (a single  digit),
325              or  long  name in parentheses (the last form is a GNU tbl exten‐
326              sion).  A one-letter font name must be separated by one or  more
327              blanks from whatever follows.
328
329       i,I    Short form of fI (make affected entries italic).
330
331       m,M    This  is a GNU tbl extension.  Either of these specifiers may be
332              followed by a macro name (either one or two characters long), or
333              long name in parentheses.  A one-letter macro name must be sepa‐
334              rated by one or more blanks from whatever  follows.   The  macro
335              which name can be specified here must be defined before creating
336              the table.  It is called just before the table's  cell  text  is
337              output.   As implemented currently, this macro is only called if
338              block input is used, that is, text between ‘T{’ and  ‘T}’.   The
339              macro  should  contain  only simple troff requests to change the
340              text block formatting, like text adjustment, hyphenation,  size,
341              or  font.   The  macro  is called after other cell modifications
342              like b, f or v are output.  Thus the macro can  overwrite  other
343              modification specifiers.
344
345       p,P    Followed  by a number, this does a point size change for the af‐
346              fected fields.  If signed, the current point size is incremented
347              or  decremented (using a signed number instead of a signed digit
348              is a GNU tbl extension).  A point size specifier followed  by  a
349              column  separation  number  must  be  separated  by  one or more
350              blanks.
351
352       t,T    Start an item vertically spanning rows at the top of  its  range
353              rather than vertically centering it.
354
355       u,U    Move the corresponding column up one half-line.
356
357       v,V    Followed  by  a number, this indicates the vertical line spacing
358              to be used in a multi-line table entry.  If signed, the  current
359              vertical  line  spacing  is  incremented or decremented (using a
360              signed number instead of a signed digit is a GNU tbl extension).
361              A  vertical  line spacing specifier followed by a column separa‐
362              tion number must be separated by one or more blanks.  No  effect
363              if the corresponding table entry isn't a text block.
364
365       w,W    Minimum  column  width  value.   Must  be  followed  either by a
366              troff(1) width expression in parentheses or a unitless  integer.
367              If  no  unit  is given, en units are used.  Also used as the de‐
368              fault line length for included text blocks.   If  used  multiple
369              times to specify the width for a particular column, the last en‐
370              try takes effect.
371
372       x,X    An expanded column.  After computing all column  widths  without
373              an  x  specifier,  use the remaining line width for this column.
374              If there is more than one expanded column,  distribute  the  re‐
375              maining horizontal space evenly among the affected columns (this
376              is a GNU extension).  This feature has the same effect as speci‐
377              fying a minimum column width.
378
379       z,Z    Ignore  the corresponding column for width-calculation purposes,
380              this is, don't use the fields but only the  specifiers  of  this
381              column to compute its width.
382
383       A  number  suffix on a key character is interpreted as a column separa‐
384       tion in en units (multiplied in proportion if the expand option is on –
385       in  case of overfull tables this might be zero).  Default separation is
386       3n.
387
388       The column specifier x is mutually exclusive with e and w (but e is not
389       mutually  exclusive with w); if specified multiple times for a particu‐
390       lar column, the last entry takes effect: x unsets both e and  w,  while
391       either e or w overrides x.
392
393   Table data
394       The  format  lines are followed by lines containing the actual data for
395       the table, followed finally by .TE.  Within such data lines, items  are
396       normally  separated  by tab characters (or the character specified with
397       the tab option).  Long input lines can be broken across multiple  lines
398       if the last character on the line is ‘\’ (which vanishes after concate‐
399       nation).
400
401       Note that tbl computes the column widths line by line, applying  \w  on
402       each  entry  which isn't a text block.  As a consequence, constructions
403       like
404
405              .TS
406              c,l.
407              \s[20]MM
408              MMMM
409              .TE
410
411       fail; you must either say
412
413              .TS
414              cp20,lp20.
415              MM
416              MMMM
417              .TE
418
419       or
420
421              .TS
422              c,l.
423              \s[20]MM
424              \s[20]MMMM
425              .TE
426
427       A dot starting a line, followed by anything but a digit is handled as a
428       troff  command,  passed through without changes.  The table position is
429       unchanged in this case.
430
431       If a data line consists of only ‘_’ or ‘=’, a single  or  double  line,
432       respectively, is drawn across the table at that point; if a single item
433       in a data line consists of only ‘_’ or ‘=’, then that item is  replaced
434       by  a  single  or  double line, joining its neighbours.  If a data item
435       consists only of ‘\_’ or ‘\=’, a single or double  line,  respectively,
436       is  drawn across the field at that point which does not join its neigh‐
437       bours.
438
439       A data item consisting only of ‘\Rx’ (‘x’ any character) is replaced by
440       repetitions  of  character  ‘x’  as wide as the column (not joining its
441       neighbours).
442
443       A data item consisting only of ‘\^’ indicates that  the  field  immedi‐
444       ately above spans downward over this row.
445
446   Text blocks
447       A text block can be used to enter data as a single entry which would be
448       too long as a simple string between tabs.  It is started with ‘T{’  and
449       closed  with  ‘T}’.   The  former  must end a line, and the latter must
450       start a line, probably followed by other data columns  (separated  with
451       tabs or the character given with the tab global option).
452
453       By  default,  the  text block is formatted with the settings which were
454       active before entering the table, possibly overridden by the m, v,  and
455       w  tbl  specifiers.  For example, to make all text blocks ragged-right,
456       insert .na right before the starting .TS (and .ad after the table).
457
458       If either ‘w’ or ‘x’ specifiers are not given for all columns of a text
459       block  span,  the default length of the text block (to be more precise,
460       the line length used to process the text block diversion)  is  computed
461       as  L×C/(N+1),  where ‘L’ is the current line length, ‘C’ the number of
462       columns spanned by the text block, and ‘N’ the total number of  columns
463       in  the  table.   Note, however, that the actual diversion width as re‐
464       turned in register \n[dl] is used eventually as the text  block  width.
465       If  necessary,  you can also control the text block width with a direct
466       insertion of a .ll request right after ‘T{’.
467
468   Miscellaneous
469       The number register \n[TW] holds the table  width;  it  can't  be  used
470       within the table itself but is defined right before calling .TE so that
471       this macro can make use of it.
472
473       tbl also defines a macro .T# which produces the bottom and  side  lines
474       of  a boxed table.  While tbl does call this macro itself at the end of
475       the table, it can be used by macro packages to create boxes for  multi-
476       page  tables  by calling it within the page footer.  An example of this
477       is shown by the -ms macros which provide this functionality if a  table
478       starts with .TS H instead of the standard call to the .TS macro.
479

INTERACTION WITH EQN

481       tbl(1)  should  always  be called before eqn(1) (groff(1) automatically
482       takes care of the correct order of preprocessors).
483

GNU TBL ENHANCEMENTS

485       There is no limit on the number of columns in a table, nor any limit on
486       the  number of text blocks.  All the lines of a table are considered in
487       deciding column widths, not just the  first  200.   Table  continuation
488       (.T&) lines are not restricted to the first 200 lines.
489
490       Numeric and alphabetic items may appear in the same column.
491
492       Numeric and alphabetic items may span horizontally.
493
494       tbl uses register, string, macro and diversion names beginning with the
495       digit 3.  When using tbl you should avoid  using  any  names  beginning
496       with a 3.
497

GNU TBL WITHIN MACROS

499       Since tbl defines its own macros (right before each table) it is neces‐
500       sary to use an ‘end-of-macro’ macro.  Additionally, the escape  charac‐
501       ter has to be switched off.  Here an example.
502
503              .eo
504              .de ATABLE ..
505              .TS
506              allbox tab(;);
507              cl.
508              \$1;\$2
509              .TE
510              ...
511              .ec
512              .ATABLE A table
513              .ATABLE Another table
514              .ATABLE And "another one"
515
516       Note, however, that not all features of tbl can be wrapped into a macro
517       because tbl sees the input earlier than  troff.   For  example,  number
518       formatting  with  vertically aligned decimal points fails if those num‐
519       bers are passed on as macro parameters because decimal point  alignment
520       is  handled  by tbl itself: It only sees ‘\$1’, ‘\$2’, etc., and there‐
521       fore can't recognize the decimal point.
522

BUGS

524       You should use .TS H/.TH in conjunction with a supporting macro package
525       for  all  multi-page boxed tables.  If there is no header that you wish
526       to appear at the top of each page of the table, place the .TH line  im‐
527       mediately  after the format section.  Do not enclose a multi-page table
528       within keep/release macros, or divert it in any other way.
529
530       A text block within a table must be able to fit on one page.
531
532       The bp request cannot be used to force a page-break in a multi-page ta‐
533       ble.  Instead, define BP as follows
534
535              .de BP
536              .  ie '\\n(.z'' .bp \\$1
537              .  el \!.BP \\$1
538              ..
539
540       and use BP instead of bp.
541
542       Using  \a  directly  in a table to get leaders does not work (except in
543       compatibility mode).  This is correct behaviour: \a is an uninterpreted
544       leader.   To get leaders use a real leader, either by using a control A
545       or like this:
546
547              .ds a \a
548              .TS
549              tab(;);
550              lw(1i) l.
551              A\*a;B
552              .TE
553
554       A leading and/or trailing ‘|’ in a format line, such as
555
556              |l r|.
557
558       gives output which has a 1n space between the resulting bordering  ver‐
559       tical rule and the content of the adjacent column, as in
560
561              .TS
562              tab(#);
563              |l r|.
564              left column#right column
565              .TE
566
567       If  it is desired to have zero space (so that the rule touches the con‐
568       tent), this can be achieved by introducing extra “dummy” columns,  with
569       no content and zero separation, before and/or after, as in
570
571              .TS
572              tab(#);
573              r0|l r0|l.
574              #left column#right column#
575              .TE
576
577       The  resulting  “dummy” columns are invisible and have zero width; note
578       that such columns usually don't work with TTY devices.
579

REFERENCE

581       Lesk, M.E.: "TBL – A Program to Format Tables".  For copyright  reasons
582       it  cannot  be  included  in  the groff distribution, but copies can be
583       found with a title search on the World Wide Web.
584

SEE ALSO

586       groff(1), troff(1)
587
588
589
590groff 1.22.4                    19 January 2023                         TBL(1)
Impressum