3 Copyright (C) 1989-1995, 2001, 2002, 2003, 2004, 2006, 2007, 2008,
5 Free Software Foundation, Inc.
7 Permission is granted to make and distribute verbatim copies of
8 this manual provided the copyright notice and this permission notice
9 are preserved on all copies.
11 Permission is granted to copy and distribute modified versions of this
12 manual under the conditions for verbatim copying, provided that the
13 entire resulting derived work is distributed under the terms of a
14 permission notice identical to this one.
16 Permission is granted to copy and distribute translations of this
17 manual into another language, under the above conditions for modified
18 versions, except that this permission notice may be included in
19 translations approved by the Free Software Foundation instead of in
24 .TH @G@TBL @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
28 @g@tbl \- format tables for troff
34 .RI [ files\~ .\|.\|.]
39 This manual page describes the GNU version of
41 which is part of the groff document formatting system.
43 compiles descriptions of tables embedded within
45 input files into commands that are understood by
47 Normally, it should be invoked using the
51 It is highly compatible with Unix
53 The output generated by GNU
55 cannot be processed with Unix
57 it must be processed with GNU
59 If no files are given on the command line or a filename of
61 is given, the standard input is read.
67 Enable compatibility mode to
72 even when followed by a character other than space or newline.
73 Leader characters (\[rs]a) are handled as interpreted.
77 Print the version number.
82 expects to find table descriptions wrapped in the
90 The line immediately following the
92 macro may contain any of the following global options (ignoring the case of
93 characters \[en] Unix tbl only accepts options with all characters lowercase
94 or all characters uppercase), separated by spaces, tabs, or commas:
98 Enclose each item of the table in a box.
102 Enclose the table in a box.
106 Center the table (default is left-justified).
107 The alternative keyword name
109 is also recognized (this is a GNU tbl extension).
112 .BI decimalpoint( c )
113 Set the character to be recognized as the decimal point in numeric
114 columns (GNU tbl only).
122 as start and end delimiters for
123 .BR @g@eqn (@MAN1EXT@).
127 Enclose the table in a double box.
131 Same as doublebox (GNU tbl only).
135 Make the table as wide as the current line length (providing a column
137 Ignored if one or more `x' column specifiers are used (see below).
140 In case the sum of the column widths is larger than the current line length,
141 the column separation factor is set to zero; such tables extend into the
142 right margin, and there is no column separation at all.
146 Same as box (GNU tbl only).
150 Set lines or rules (e.g. from
158 Don't use diversions to prevent page breaks (GNU tbl only).
161 attempts to prevent undesirable breaks in boxed tables by using diversions.
162 This can sometimes interact badly with macro packages' own use of
163 diversions, when footnotes, for example, are used.
167 Ignore leading and trailing spaces in data items (GNU tbl only).
173 instead of a tab to separate items in a line of input data.
176 The global options must end with a semicolon.
177 There might be whitespace between an option and its argument in parentheses.
180 .SS Table format specification
181 After global options come lines describing the format of each line of
183 Each such format line describes one line of the table itself, except that
184 the last format line (which you must end with a period) describes all
185 remaining lines of the table.
186 A single-key character describes each column of each line of the table.
187 Key characters can be separated by spaces or tabs.
188 You may run format specifications for multiple lines together on the same
189 line by separating them with commas.
192 You may follow each key character with specifiers that determine the font
193 and point size of the corresponding item, that determine column width,
194 inter-column spacing, etc.
197 The longest format line defines the number of columns in the table; missing
198 format descriptors at the end of format lines are assumed to be\~\c
200 Extra columns in the data (which have no corresponding format entry) are
204 The available key characters are:
208 Center longest line in this column and then left-justifies all other lines
209 in this column with respect to that centered line.
210 The idea is to use such alphabetic subcolumns (hence the name of the key
211 character) in combination with\~
213 they are called subcolumns because
215 are indented by\~1n relative to
230 \&subitem twentytwo;22
231 \&subitem thirtythree;33
251 subitem thirtythree;33
257 Center item within the column.
261 Left-justify item within the column.
265 Numerically justify item in the column: Units positions of numbers are
267 If there is one or more dots adjacent to a digit, use the rightmost one for
269 If there is no dot, use the rightmost digit for vertical alignment;
270 otherwise, center the item within the column.
271 Alignment can be forced to a certain position using `\[rs]&'; if there is
272 one or more instances of this special (non-printing) character present
273 within the data, use the leftmost one for alignment.
305 If numerical entries are combined with
309 \[en] this can happen if the table format is changed with
314 (of the data entered under the
316 regime) relative to the widest
320 preserving the alignment of all numerical entries.
323 entries, there is no extra indentation.
326 Using equations (to be processed with
328 within columns which use the
330 is problematic in most cases due to
332 algorithm for finding the vertical alignment, as described above.
335 option, however, it is possible to make
337 ignore the data within
339 delimiters for that purpose.
344 Right-justify item within the column.
348 Span previous item on the left into this column.
349 Not allowed for the first column.
353 Span down entry from previous row in this column.
354 Not allowed for the first row.
358 Replace this entry with a horizontal line.
363 Replace this entry with a double horizontal line.
367 The corresponding column becomes a vertical rule (if two of these are
368 adjacent, a double vertical rule).
371 A vertical bar to the left of the first key letter or to the right of the
372 last one produces a line at the edge of the table.
375 To change the data format within a table, use the
377 command (at the start of a line).
378 It is followed by format and data lines (but no global options) similar to
384 .SS Column specifiers
385 Here are the specifiers that can appear in suffixes to column key letters
392 (make affected entries bold).
396 Start an item vertically spanning rows at the bottom of its range rather
397 than vertically centering it (GNU tbl only).
401 Make equally-spaced columns.
402 All columns marked with this specifier get the same width; this happens
403 after the affected column widths have been computed (this means that the
404 largest width value rules).
408 Either of these specifiers may be followed by a font name (either one or two
409 characters long), font number (a single digit), or long name in parentheses
410 (the last form is a GNU tbl extension).
411 A one-letter font name must be separated by one or more blanks from whatever
418 (make affected entries italic).
422 This is a GNU tbl extension.
423 Either of these specifiers may be followed by a macro name
424 (either one or two characters long),
425 or long name in parentheses.
426 A one-letter macro name must be separated by one or more blanks
427 from whatever follows.
428 The macro which name can be specified here
429 must be defined before creating the table.
430 It is called just before the table's cell text is output.
431 As implemented currently, this macro is only called if block input is used,
432 that is, text between `T{' and `T}'.
433 The macro should contain only simple
435 requests to change the text block formatting, like text adjustment,
436 hyphenation, size, or font.
439 other cell modifications like
445 Thus the macro can overwrite other modification specifiers.
449 Followed by a number, this does a point size change for the affected fields.
450 If signed, the current point size is incremented or decremented (using a
451 signed number instead of a signed digit is a GNU tbl extension).
452 A point size specifier followed by a column separation number must be
453 separated by one or more blanks.
457 Start an item vertically spanning rows at the top of its range rather than
458 vertically centering it.
462 Move the corresponding column up one half-line.
466 Followed by a number, this indicates the vertical line spacing to be used in
467 a multi-line table entry.
468 If signed, the current vertical line spacing is incremented or decremented
469 (using a signed number instead of a signed digit is a GNU tbl extension).
470 A vertical line spacing specifier followed by a column separation number
471 must be separated by one or more blanks.
472 No effect if the corresponding table entry isn't a text block.
476 Minimal column width value.
477 Must be followed either by a
478 .BR @g@troff (@MAN1EXT@)
479 width expression in parentheses or a unitless integer.
480 If no unit is given, en units are used.
481 Also used as the default line length for included text blocks.
482 If used multiple times to specify the width for a particular column,
483 the last entry takes effect.
488 After computing all column widths without an
490 use the remaining line width for this column.
491 If there is more than one expanded column, distribute the remaining
492 horizontal space evenly among the affected columns (this is a GNU
494 This feature has the same effect as specifying a minimum column width.
498 Ignore the corresponding column for width-calculation purposes, this is,
499 don't use the fields but only the specifiers of this column to compute
503 A number suffix on a key character is interpreted as a column
504 separation in en units (multiplied in proportion if the
506 option is on \[en] in case of overfull tables this might be zero).
507 Default separation is 3n.
512 is mutually exclusive with
517 is not mutually exclusive
519 if specified multiple times for a particular column, the last entry takes
533 The format lines are followed by lines containing the actual data for the
534 table, followed finally by
536 Within such data lines, items are normally separated by tab characters (or
537 the character specified with the
540 Long input lines can be broken across multiple lines if the last character
541 on the line is `\[rs]' (which vanishes after concatenation).
546 computes the column widths line by line, applying \[rs]w on each entry
547 which isn't a text block.
548 As a consequence, constructions like
559 fail; you must either say
582 A dot starting a line, followed by anything but a digit is handled as a
583 troff command, passed through without changes.
584 The table position is unchanged in this case.
587 If a data line consists of only `_' or `=', a single or double line,
588 respectively, is drawn across the table at that point; if a single item in a
589 data line consists of only `_' or `=', then that item is replaced by a
590 single or double line, joining its neighbours.
591 If a data item consists only of `\[rs]_' or `\[rs]=', a single or double line,
592 respectively, is drawn across the field at that point which does not join
596 A data item consisting only of `\[rs]Rx' (`x' any character) is replaced by
597 repetitions of character `x' as wide as the column (not joining its
601 A data item consisting only of `\[rs]^' indicates that the field immediately
602 above spans downward over this row.
606 A text block can be used to enter data as a single entry which would be
607 too long as a simple string between tabs.
608 It is started with `T{' and closed with `T}'.
609 The former must end a line, and the latter must start a line, probably
610 followed by other data columns (separated with tabs or the character given
616 By default, the text block is formatted with the settings which were
617 active before entering the table, possibly overridden by the
623 For example, to make all text blocks ragged-right, insert
625 right before the starting
632 If either `w' or `x' specifiers are not given for
634 columns of a text block span, the default length of the text block (to be
635 more precise, the line length used to process the text block diversion) is
636 computed as L\[tmu]C/(N+1), where `L' is the current line length, `C' the
637 number of columns spanned by the text block, and `N' the total number of
638 columns in the table.
639 Note, however, that the actual diversion width as returned in register
641 is used eventually as the text block width.
642 If necessary, you can also control the text block width with a direct
645 request right after `T{'.
651 holds the table width; it can't be used within the table itself but is defined
654 so that this macro can make use of it.
660 which produces the bottom and side lines of a boxed table.
663 does call this macro itself at the end of the table, it can be used by
664 macro packages to create boxes for multi-page tables by calling it within the
666 An example of this is shown by the
668 macros which provide this functionality if a table starts with
670 instead of the standard call to the
675 .SH "INTERACTION WITH @G@EQN"
676 .BR @g@tbl (@MAN1EXT@)
677 should always be called before
678 .BR @g@eqn (@MAN1EXT@)
679 .RB ( groff (@MAN1EXT@)
680 automatically takes care of the correct order of preprocessors).
683 .SH "GNU TBL ENHANCEMENTS"
684 There is no limit on the number of columns in a table, nor any limit on the
685 number of text blocks.
686 All the lines of a table are considered in deciding column widths, not just
690 lines are not restricted to the first 200 lines.
693 Numeric and alphabetic items may appear in the same column.
696 Numeric and alphabetic items may span horizontally.
700 uses register, string, macro and diversion names beginning with the digit\~\c
704 you should avoid using any names beginning with a\~\c
708 .SH "GNU TBL WITHIN MACROS"
711 defines its own macros (right before each table) it is necessary to use
712 an `end-of-macro' macro. Additionally, the escape character has to be switched
713 off. Here an example.
726 \&.ATABLE Another table
727 \&.ATABLE And \[dq]another one\[dq]
731 Note, however, that not all features of
733 can be wrapped into a macro because
735 sees the input earlier than
737 For example, number formatting with vertically aligned decimal points
738 fails if those numbers are passed on as macro parameters because
739 decimal point alignment is handled by
741 itself: It only sees `\[rs]$1', `\[rs]$2', etc., and therefore can't
742 recognize the decimal point.
748 in conjunction with a supporting macro package for
750 multi-page boxed tables.
751 If there is no header that you wish to appear at the top of each page
752 of the table, place the
754 line immediately after the format section.
755 Do not enclose a multi-page table within keep/release macros,
756 or divert it in any other way.
759 A text block within a table must be able to fit on one page.
764 request cannot be used to force a page-break in a multi-page table.
772 \&. ie '\[rs]\[rs]n(.z'' .bp \[rs]\[rs]$1
773 \&. el \[rs]!.BP \[rs]\[rs]$1
784 Using \[rs]a directly in a table to get leaders does not work (except in
786 This is correct behaviour: \[rs]a is an
789 To get leaders use a real leader, either by using a control A or like
804 Lesk, M.E.: "TBL \[en] A Program to Format Tables".
805 For copyright reasons it cannot be included in the groff distribution,
806 but copies can be found with a title search on the World Wide Web.
810 .BR groff (@MAN1EXT@),
811 .BR @g@troff (@MAN1EXT@)
projects / dragonfly.git / blob