2 .TH @G@TBL @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
4 @g@tbl \- format tables for troff
9 Copyright \[co] 1989-2014 Free Software Foundation, Inc.
11 Bernd Warken <groff-bernd.warken-72@web.de> added simple examples.
13 Permission is granted to make and distribute verbatim copies of
14 this manual provided the copyright notice and this permission notice
15 are preserved on all copies.
17 Permission is granted to copy and distribute modified versions of this
18 manual under the conditions for verbatim copying, provided that the
19 entire resulting derived work is distributed under the terms of a
20 permission notice identical to this one.
22 Permission is granted to copy and distribute translations of this
23 manual into another language, under the above conditions for modified
24 versions, except that this permission notice may be included in
25 translations approved by the Free Software Foundation instead of in
29 .\" --------------------------------------------------------------------
31 .\" --------------------------------------------------------------------
35 .RI [ files\~ .\|.\|.]
39 .\" --------------------------------------------------------------------
41 .\" --------------------------------------------------------------------
43 This manual page describes the GNU version of
45 which is part of the groff document formatting system.
48 compiles descriptions of tables embedded within
50 input files into commands that are understood by
53 Normally, it should be invoked using the
58 It is highly compatible with Unix
61 The output generated by GNU
63 cannot be processed with Unix
65 it must be processed with GNU
68 If no files are given on the command line or a filename of
70 is given, the standard input is read.
73 .\" --------------------------------------------------------------------
75 .\" --------------------------------------------------------------------
79 Enable compatibility mode to
84 even when followed by a character other than space or newline.
86 Leader characters (\[rs]a) are handled as interpreted.
90 Print the version number.
93 .\" --------------------------------------------------------------------
94 .SH "LANGUAGE OVERVIEW"
95 .\" --------------------------------------------------------------------
98 expects to find table descriptions wrapped in the
104 Within each such table sections, another table can be defined by
107 before the final command
110 Each table definition has the following structure:
116 This table part can use several of these options distributed in 1 or
120 .I global option part
121 must always be finished by a
125 .I Table format specification
127 This part must be given, it is not optional.
129 It determines the number of columns (cells) of the table.
131 Moreover each cell is classified by being central, left adjusted, or
134 This specification can have several lines, but must be finished by a
136 at the end of the last line.
138 After each cell definition,
140 can be appended, but that\[aq]s optional.
144 Cells are separated by a tab character by default.
146 That can be changed by the
151 is an arbitrary character.
154 .\" --------------------------------------------------------------------
155 .SH "SIMPLE EXAMPLES"
156 .\" --------------------------------------------------------------------
158 The easiest table definition is.
173 each cell in the whole table will be centered.
175 The separating character is here the default
193 This definition is identical to
205 Here, the separating tab character is changed to the letter
210 Moreover a title can be added and the centering directions can be
211 changed to many other formats:
242 .IR left\-justified ,
248 .IR right\-justified .
251 .\" --------------------------------------------------------------------
254 .\" --------------------------------------------------------------------
256 .\" --------------------------------------------------------------------
258 The line immediately following the
260 macro may contain any of the following global options (ignoring the
261 case of characters \[en] Unix tbl only accepts options with all
262 characters lowercase or all characters uppercase), separated by
263 spaces, tabs, or commas:
267 Enclose each item of the table in a box.
271 Enclose the table in a box.
275 Center the table (default is left-justified).
277 The alternative keyword name
279 is also recognized (this is a GNU tbl extension).
282 .BI decimalpoint( c )
283 Set the character to be recognized as the decimal point in numeric
284 columns (GNU tbl only).
292 as start and end delimiters for
293 .BR @g@eqn (@MAN1EXT@).
297 Enclose the table in a double box.
301 Same as doublebox (GNU tbl only).
305 Make the table as wide as the current line length (providing a column
308 Ignored if one or more \[oq]x\[cq] column specifiers are used (see
312 In case the sum of the column widths is larger than the current line length,
313 the column separation factor is set to zero; such tables extend into the
314 right margin, and there is no column separation at all.
318 Same as box (GNU tbl only).
322 Set lines or rules (e.g.\& from
330 Don\[aq]t use diversions to prevent page breaks (GNU tbl only).
334 attempts to prevent undesirable breaks in boxed tables by using diversions.
336 This can sometimes interact badly with macro packages own use of
337 diversions, when footnotes, for example, are used.
341 Ignore leading and trailing spaces in data items (GNU tbl only).
345 Turn off warnings related to tables exceeding the current line width
352 instead of a tab to separate items in a line of input data.
356 The global options must end with a semicolon.
358 There might be whitespace between an option and its argument in
362 .\" --------------------------------------------------------------------
363 .SS Table format specification
364 .\" --------------------------------------------------------------------
366 After global options come lines describing the format of each line of
369 Each such format line describes one line of the table itself, except
370 that the last format line (which you must end with a period) describes
371 all remaining lines of the table.
373 A single-key character describes each column of each line of the table.
374 Key characters can be separated by spaces or tabs.
376 You may run format specifications for multiple lines together on the
377 same line by separating them with commas.
381 You may follow each key character with specifiers that determine the
382 font and point size of the corresponding item, that determine column
383 width, inter-column spacing, etc.
387 The longest format line defines the number of columns in the table;
388 missing format descriptors at the end of format lines are assumed to
392 Extra columns in the data (which have no corresponding format entry)
397 The available key characters are:
401 Center longest line in this column and then left-justifies all other
402 lines in this column with respect to that centered line.
404 The idea is to use such alphabetic subcolumns (hence the name of the
405 key character) in combination with\~
407 they are called subcolumns because
409 are indented by\~1n relative to
425 \&subitem twentytwo;22
426 \&subitem thirtythree;33
446 subitem thirtythree;33
452 Center item within the column.
456 Left-justify item within the column.
460 Numerically justify item in the column: Units positions of numbers are
463 If there is one or more dots adjacent to a digit, use the rightmost one for
466 If there is no dot, use the rightmost digit for vertical alignment;
467 otherwise, center the item within the column.
469 Alignment can be forced to a certain position using \[oq]\[rs]&\[cq];
470 if there is one or more instances of this special (non-printing)
471 character present within the data, use the leftmost one for alignment.
504 If numerical entries are combined with
508 \[en] this can happen if the table format is changed with
513 (of the data entered under the
515 regime) relative to the widest
519 preserving the alignment of all numerical entries.
523 entries, there is no extra indentation.
526 Using equations (to be processed with
528 within columns which use the
530 is problematic in most cases due to
532 algorithm for finding the vertical alignment, as described above.
536 option, however, it is possible to make
538 ignore the data within
540 delimiters for that purpose.
545 Right-justify item within the column.
549 Span previous item on the left into this column.
551 Not allowed for the first column.
555 Span down entry from previous row in this column.
557 Not allowed for the first row.
561 Replace this entry with a horizontal line.
563 Note that \[oq]_\[cq] and \[oq]-\[cq] can be used for table fields only,
564 not for column separator lines.
569 Replace this entry with a double horizontal line.
571 Note that \[oq]=\[cq] can be used for table fields only,
572 not for column separator lines.
576 The corresponding column becomes a vertical rule (if two of these are
577 adjacent, a double vertical rule).
581 A vertical bar to the left of the first key letter or to the right of
582 the last one produces a line at the edge of the table.
586 To change the data format within a table, use the
588 command (at the start of a line).
590 It is followed by format and data lines (but no global options)
596 .\" --------------------------------------------------------------------
597 .SS Column specifiers
598 .\" --------------------------------------------------------------------
600 Here are the specifiers that can appear in suffixes to column key
601 letters (in any order):
607 (make affected entries bold).
611 Start an item that vertically spans rows,
612 using the \[oq]^\[cq] column specifier or \[oq]\[rs]^\[cq] data item,
613 at the bottom of its range rather
614 than vertically centering it (GNU tbl only).
672 Make equally-spaced columns.
674 All columns marked with this specifier get the same width; this happens
675 after the affected column widths have been computed (this means that the
676 largest width value rules).
680 Either of these specifiers may be followed by a font name (either one or two
681 characters long), font number (a single digit), or long name in parentheses
682 (the last form is a GNU tbl extension).
684 A one-letter font name must be separated by one or more blanks from whatever
691 (make affected entries italic).
695 This is a GNU tbl extension.
697 Either of these specifiers may be followed by a macro name
698 (either one or two characters long),
699 or long name in parentheses.
701 A one-letter macro name must be separated by one or more blanks from
704 The macro which name can be specified here must be defined before
707 It is called just before the table\[aq]s cell text is output.
709 As implemented currently, this macro is only called if block input is
710 used, that is, text between \[oq]T{\[cq] and \[oq]T}\[cq].
712 The macro should contain only simple
714 requests to change the text block formatting, like text adjustment,
715 hyphenation, size, or font.
719 other cell modifications like
726 Thus the macro can overwrite other modification specifiers.
730 Followed by a number, this does a point size change for the affected fields.
732 If signed, the current point size is incremented or decremented (using
733 a signed number instead of a signed digit is a GNU tbl extension).
735 A point size specifier followed by a column separation number must be
736 separated by one or more blanks.
740 Start an item vertically spanning rows at the top of its range rather than
741 vertically centering it.
745 Move the corresponding column up one half-line.
749 Followed by a number, this indicates the vertical line spacing to be
750 used in a multi-line table entry.
752 If signed, the current vertical line spacing is incremented or
753 decremented (using a signed number instead of a signed digit is a GNU
756 A vertical line spacing specifier followed by a column separation
757 number must be separated by one or more blanks.
759 No effect if the corresponding table entry isn\[aq]t a text block.
763 Minimum column width value.
764 Must be followed either by a
765 .BR @g@troff (@MAN1EXT@)
766 width expression in parentheses or a unitless integer.
768 If no unit is given, en units are used.
770 Also used as the default line length for included text blocks.
772 If used multiple times to specify the width for a particular column,
773 the last entry takes effect.
779 After computing all column widths without an
781 use the remaining line width for this column.
783 If there is more than one expanded column, distribute the remaining
784 horizontal space evenly among the affected columns (this is a GNU
787 This feature has the same effect as specifying a minimum column width.
791 Ignore the corresponding column for width-calculation purposes, this
792 is, don\[aq]t use the fields but only the specifiers of this column to
797 A number suffix on a key character is interpreted as a column
798 separation in en units (multiplied in proportion if the
800 option is on \[en] in case of overfull tables this might be zero).
802 Default separation is 3n.
808 is mutually exclusive with
813 is not mutually exclusive
815 if specified multiple times for a particular column, the last entry takes
828 .\" --------------------------------------------------------------------
830 .\" --------------------------------------------------------------------
832 The format lines are followed by lines containing the actual data for the
833 table, followed finally by
836 Within such data lines, items are normally separated by tab characters
837 (or the character specified with the
841 Long input lines can be broken across multiple lines if the last
842 character on the line is \[oq]\[rs]\[cq] (which vanishes after
849 computes the column widths line by line, applying \[rs]w on each entry
850 which isn\[aq]t a text block.
852 As a consequence, constructions like
863 fail; you must either say
887 A dot starting a line, followed by anything but a digit is handled as
888 a troff command, passed through without changes.
890 The table position is unchanged in this case.
894 If a data line consists of only \[oq]_\[cq] or \[oq]=\[cq], a single
895 or double line, respectively, is drawn across the table at that point;
896 if a single item in a data line consists of only \[oq]_\[cq] or
897 \[oq]=\[cq], then that item is replaced by a single or double line,
898 joining its neighbours.
900 If a data item consists only of \[oq]\[rs]_\[cq] or \[oq]\[rs]=\[cq],
901 a single or double line, respectively, is drawn across the field at
902 that point which does not join its neighbours.
906 A data item consisting only of \[oq]\[rs]Rx\[cq] (\[oq]x\[cq] any
907 character) is replaced by repetitions of character \[oq]x\[cq] as wide
908 as the column (not joining its neighbours).
912 A data item consisting only of \[oq]\[rs]^\[cq] indicates that the
913 field immediately above spans downward over this row.
916 .\" --------------------------------------------------------------------
918 .\" --------------------------------------------------------------------
920 A text block can be used to enter data as a single entry which would
921 be too long as a simple string between tabs.
923 It is started with \[oq]T{\[cq] and closed with \[oq]T}\[cq].
925 The former must end a line, and the latter must start a line, probably
926 followed by other data columns (separated with tabs or the character
933 By default, the text block is formatted with the settings which were
934 active before entering the table, possibly overridden by the
941 For example, to make all text blocks ragged-right, insert
943 right before the starting
951 If either \[oq]w\[cq] or \[oq]x[cq] specifiers are not given for
953 columns of a text block span, the default length of the text block (to
954 be more precise, the line length used to process the text block
955 diversion) is computed as L\[tmu]C/(N+1), where \[oq]L\[cq] is the
956 current line length, \[oq]C\[cq] the number of columns spanned by the
957 text block, and \[oq]N\[cq] the total number of columns in the table.
959 Note, however, that the actual diversion width as returned in register
961 is used eventually as the text block width.
963 If necessary, you can also control the text block width with a direct
966 request right after \[oq]T{\[cq].
969 .\" --------------------------------------------------------------------
971 .\" --------------------------------------------------------------------
975 holds the table width; it can\[aq]t be used within the table itself
976 but is defined right before calling
978 so that this macro can make use of it.
985 which produces the bottom and side lines of a boxed table.
989 does call this macro itself at the end of the table, it can be used by
990 macro packages to create boxes for multi-page tables by calling it within the
993 An example of this is shown by the
995 macros which provide this functionality if a table starts with
997 instead of the standard call to the
1002 .\" --------------------------------------------------------------------
1003 .SH "INTERACTION WITH @G@EQN"
1004 .\" --------------------------------------------------------------------
1006 .BR @g@tbl (@MAN1EXT@)
1007 should always be called before
1008 .BR @g@eqn (@MAN1EXT@)
1009 .RB ( groff (@MAN1EXT@)
1010 automatically takes care of the correct order of preprocessors).
1013 .\" --------------------------------------------------------------------
1014 .SH "GNU TBL ENHANCEMENTS"
1015 .\" --------------------------------------------------------------------
1017 There is no limit on the number of columns in a table, nor any limit on the
1018 number of text blocks.
1020 All the lines of a table are considered in deciding column widths, not just
1025 lines are not restricted to the first 200 lines.
1029 Numeric and alphabetic items may appear in the same column.
1033 Numeric and alphabetic items may span horizontally.
1038 uses register, string, macro and diversion names beginning with the digit\~\c
1043 you should avoid using any names beginning with a\~\c
1047 .\" --------------------------------------------------------------------
1048 .SH "GNU TBL WITHIN MACROS"
1049 .\" --------------------------------------------------------------------
1053 defines its own macros (right before each table) it is necessary to use
1054 an \[oq]end-of-macro\[cq] macro.
1056 Additionally, the escape character has to be switched off.
1071 \&.ATABLE Another table
1072 \&.ATABLE And \[dq]another one\[dq]
1077 Note, however, that not all features of
1079 can be wrapped into a macro because
1081 sees the input earlier than
1084 For example, number formatting with vertically aligned decimal points
1085 fails if those numbers are passed on as macro parameters because
1086 decimal point alignment is handled by
1088 itself: It only sees \[oq]\[rs]$1\[cq], \[oq]\[rs]$2\[cq], etc., and
1089 therefore can\[aq]t recognize the decimal point.
1092 .\" --------------------------------------------------------------------
1094 .\" --------------------------------------------------------------------
1098 in conjunction with a supporting macro package for
1100 multi-page boxed tables.
1102 If there is no header that you wish to appear at the top of each page
1103 of the table, place the
1105 line immediately after the format section.
1107 Do not enclose a multi-page table within keep/release macros,
1108 or divert it in any other way.
1112 A text block within a table must be able to fit on one page.
1118 request cannot be used to force a page-break in a multi-page table.
1127 \&. ie '\[rs]\[rs]n(.z'' .bp \[rs]\[rs]$1
1128 \&. el \[rs]!.BP \[rs]\[rs]$1
1141 Using \[rs]a directly in a table to get leaders does not work (except in
1142 compatibility mode).
1144 This is correct behaviour: \[rs]a is an
1148 To get leaders use a real leader, either by using a control A or like
1163 A leading and/or trailing \[oq]|\[cq] in a format line, such as
1172 gives output which has a 1n\~space between the resulting
1173 bordering vertical rule and the content of the adjacent column,
1181 \&left column#right column
1187 If it is desired to have zero space (so that the rule touches
1188 the content), this can be achieved by introducing extra \[lq]dummy\[rq]
1189 columns, with no content and zero separation, before and/or after,
1197 \&#left column#right column#
1203 The resulting \[lq]dummy\[rq] columns are invisible and have zero width;
1204 note that such columns usually don\[aq]t work with TTY devices.
1207 .\" --------------------------------------------------------------------
1209 .\" --------------------------------------------------------------------
1210 Lesk, M.E.: "TBL \[en] A Program to Format Tables".
1211 For copyright reasons it cannot be included in the groff distribution,
1212 but copies can be found with a title search on the World Wide Web.
1215 .\" --------------------------------------------------------------------
1217 .\" --------------------------------------------------------------------
1218 .BR groff (@MAN1EXT@),
1219 .BR @g@troff (@MAN1EXT@)
1222 .\" --------------------------------------------------------------------
1224 .\" --------------------------------------------------------------------
1228 .\" Local Variables:
projects / platform / upstream / groff.git / blob