2 .TH @G@TBL @MAN1EXT@ "@MDATE@" "groff @VERSION@"
4 @g@tbl \- format tables for troff
7 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
12 .\" ====================================================================
14 .\" ====================================================================
16 .\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
18 .\" Permission is granted to make and distribute verbatim copies of this
19 .\" manual provided the copyright notice and this permission notice are
20 .\" preserved on all copies.
22 .\" Permission is granted to copy and distribute modified versions of
23 .\" this manual under the conditions for verbatim copying, provided that
24 .\" the entire resulting derived work is distributed under the terms of
25 .\" a permission notice identical to this one.
27 .\" Permission is granted to copy and distribute translations of this
28 .\" manual into another language, under the above conditions for
29 .\" modified versions, except that this permission notice may be
30 .\" included in translations approved by the Free Software Foundation
31 .\" instead of in the original English.
34 .\" Bernd Warken <groff-bernd.warken-72@web.de> added simple examples.
35 .\" ====================================================================
37 .\" ====================================================================
46 .\" ====================================================================
48 .\" ====================================================================
50 This manual page describes the GNU version of
52 which is part of the groff document formatting system.
55 compiles descriptions of tables embedded within
57 input files into commands that are understood by
60 Normally, it should be invoked using the
65 It is highly compatible with Unix
68 The output generated by GNU
70 cannot be processed with Unix
72 it must be processed with GNU
75 If no files are given on the command line or a filename of
77 is given, the standard input is read.
80 .\" ====================================================================
82 .\" ====================================================================
86 Enable compatibility mode to
91 even when followed by a character other than space or newline.
93 Leader characters (\[rs]a) are handled as interpreted.
97 Print the version number.
100 .\" ====================================================================
101 .SH "LANGUAGE OVERVIEW"
102 .\" ====================================================================
105 expects to find table descriptions wrapped in the
111 Within each such table sections, another table can be defined by
114 before the final command
117 Each table definition has the following structure:
123 This table part can use several of these options distributed in 1 or
127 .I global option part
128 must always be finished by a
132 .I Table format specification
134 This part must be given, it is not optional.
136 It determines the number of columns (cells) of the table.
138 Moreover each cell is classified by being central, left adjusted, or
141 This specification can have several lines, but must be finished by a
143 at the end of the last line.
145 After each cell definition,
147 can be appended, but that's optional.
151 Cells are separated by a tab character by default.
153 That can be changed by the
159 is an arbitrary character.
162 .\" ====================================================================
163 .SH "SIMPLE EXAMPLES"
164 .\" ====================================================================
166 The easiest table definition is.
181 each cell in the whole table will be centered.
183 The separating character is here the default
199 This definition is identical to
211 Here, the separating tab character is changed to the letter
216 Moreover a title can be added and the centering directions can be
217 changed to many other formats:
246 .IR left\-justified ,
252 .IR right\-justified .
255 .\" ====================================================================
258 .\" ====================================================================
260 .\" ====================================================================
262 The line immediately following the
264 macro may contain any of the following global options (ignoring the
265 case of characters \[en] Unix tbl only accepts options with all
266 characters lowercase or all characters uppercase), separated by
267 spaces, tabs, or commas:
271 Enclose each item of the table in a box.
275 Enclose the table in a box.
279 Center the table (default is left-justified).
281 The alternative keyword name
283 is also recognized (this is a GNU tbl extension).
286 .BI decimalpoint( c )
287 Set the character to be recognized as the decimal point in numeric
288 columns (GNU tbl only).
296 as start and end delimiters for
297 .BR @g@eqn (@MAN1EXT@).
301 Enclose the table in a double box.
305 Same as doublebox (GNU tbl only).
309 Make the table as wide as the current line length (providing a column
312 Ignored if one or more \[oq]x\[cq] column specifiers are used (see
316 In case the sum of the column widths is larger than the current line length,
317 the column separation factor is set to zero; such tables extend into the
318 right margin, and there is no column separation at all.
322 Same as box (GNU tbl only).
326 Set lines or rules (e.g.\& from
334 Don't use diversions to prevent page breaks (GNU tbl only).
338 attempts to prevent undesirable breaks in boxed tables by using diversions.
340 This can sometimes interact badly with macro packages' own use of
341 diversions\[em]when footnotes, for example, are used.
345 Ignore leading and trailing spaces in data items (GNU tbl only).
349 Turn off warnings related to tables exceeding the current line width
356 instead of a tab to separate items in a line of input data.
360 The global options must end with a semicolon.
362 There might be whitespace between an option and its argument in
366 .\" ====================================================================
367 .SS Table format specification
368 .\" ====================================================================
370 After global options come lines describing the format of each line of
373 Each such format line describes one line of the table itself, except
374 that the last format line (which you must end with a period) describes
375 all remaining lines of the table.
377 A single-key character describes each column of each line of the table.
378 Key characters can be separated by spaces or tabs.
380 You may run format specifications for multiple lines together on the
381 same line by separating them with commas.
385 You may follow each key character with specifiers that determine the
386 font and point size of the corresponding item, that determine column
387 width, inter-column spacing, etc.
391 The longest format line defines the number of columns in the table;
392 missing format descriptors at the end of format lines are assumed to
396 Extra columns in the data (which have no corresponding format entry)
401 The available key characters are:
405 Center longest line in this column and then left-justifies all other
406 lines in this column with respect to that centered line.
408 The idea is to use such alphabetic subcolumns (hence the name of the
409 key character) in combination with\~
411 they are called subcolumns because
413 are indented by\~1n relative to
429 \&subitem twentytwo;22
430 \&subitem thirtythree;33
450 subitem thirtythree;33
456 Center item within the column.
460 Left-justify item within the column.
464 Numerically justify item in the column: Units positions of numbers are
467 If there is one or more dots adjacent to a digit, use the rightmost one for
470 If there is no dot, use the rightmost digit for vertical alignment;
471 otherwise, center the item within the column.
473 Alignment can be forced to a certain position using \[oq]\[rs]&\[cq];
474 if there is one or more instances of this special (non-printing)
475 character present within the data, use the leftmost one for alignment.
508 If numerical entries are combined with
512 \[en] this can happen if the table format is changed with
517 (of the data entered under the
519 regime) relative to the widest
523 preserving the alignment of all numerical entries.
527 entries, there is no extra indentation.
530 Using equations (to be processed with
532 within columns which use the
534 is problematic in most cases due to
536 algorithm for finding the vertical alignment, as described above.
540 option, however, it is possible to make
542 ignore the data within
544 delimiters for that purpose.
549 Right-justify item within the column.
553 Span previous item on the left into this column.
555 Not allowed for the first column.
559 Span down entry from previous row in this column.
561 Not allowed for the first row.
565 Replace this entry with a horizontal line.
567 Note that \[oq]_\[cq] and \[oq]-\[cq] can be used for table fields only,
568 not for column separator lines.
573 Replace this entry with a double horizontal line.
575 Note that \[oq]=\[cq] can be used for table fields only,
576 not for column separator lines.
580 The corresponding column becomes a vertical rule (if two of these are
581 adjacent, a double vertical rule).
585 A vertical bar to the left of the first key letter or to the right of
586 the last one produces a line at the edge of the table.
590 To change the data format within a table, use the
592 command (at the start of a line).
594 It is followed by format and data lines (but no global options)
600 .\" ====================================================================
601 .SS Column specifiers
602 .\" ====================================================================
604 Here are the specifiers that can appear in suffixes to column key
605 letters (in any order):
611 (make affected entries bold).
615 Start an item that vertically spans rows,
616 using the \[oq]^\[cq] column specifier or \[oq]\[rs]^\[cq] data item,
617 at the bottom of its range rather
618 than vertically centering it (GNU tbl only).
676 Make equally-spaced columns.
678 All columns marked with this specifier get the same width; this happens
679 after the affected column widths have been computed (this means that the
680 largest width value rules).
684 Either of these specifiers may be followed by a font name (either one or two
685 characters long), font number (a single digit), or long name in parentheses
686 (the last form is a GNU tbl extension).
688 A one-letter font name must be separated by one or more blanks from whatever
695 (make affected entries italic).
699 This is a GNU tbl extension.
701 Either of these specifiers may be followed by a macro name
702 (either one or two characters long),
703 or long name in parentheses.
705 A one-letter macro name must be separated by one or more blanks from
708 The macro which name can be specified here must be defined before
711 It is called just before the table's cell text is output.
713 As implemented currently, this macro is only called if block input is
714 used, that is, text between \[oq]T{\[cq] and \[oq]T}\[cq].
716 The macro should contain only simple
718 requests to change the text block formatting, like text adjustment,
719 hyphenation, size, or font.
723 other cell modifications like
730 Thus the macro can overwrite other modification specifiers.
734 Followed by a number, this does a point size change for the affected fields.
736 If signed, the current point size is incremented or decremented (using
737 a signed number instead of a signed digit is a GNU tbl extension).
739 A point size specifier followed by a column separation number must be
740 separated by one or more blanks.
744 Start an item vertically spanning rows at the top of its range rather than
745 vertically centering it.
749 Move the corresponding column up one half-line.
753 Followed by a number, this indicates the vertical line spacing to be
754 used in a multi-line table entry.
756 If signed, the current vertical line spacing is incremented or
757 decremented (using a signed number instead of a signed digit is a GNU
760 A vertical line spacing specifier followed by a column separation
761 number must be separated by one or more blanks.
763 No effect if the corresponding table entry isn't a text block.
767 Minimum column width value.
768 Must be followed either by a
769 .BR @g@troff (@MAN1EXT@)
770 width expression in parentheses or a unitless integer.
772 If no unit is given, en units are used.
774 Also used as the default line length for included text blocks.
776 If used multiple times to specify the width for a particular column,
777 the last entry takes effect.
783 After computing all column widths without an
785 use the remaining line width for this column.
787 If there is more than one expanded column, distribute the remaining
788 horizontal space evenly among the affected columns (this is a GNU
791 This feature has the same effect as specifying a minimum column width.
795 Ignore the corresponding column for width-calculation purposes, this
796 is, don't use the fields but only the specifiers of this column to
801 A number suffix on a key character is interpreted as a column
802 separation in en units (multiplied in proportion if the
804 option is on \[en] in case of overfull tables this might be zero).
806 Default separation is 3n.
812 is mutually exclusive with
817 is not mutually exclusive
819 if specified multiple times for a particular column, the last entry takes
832 .\" ====================================================================
834 .\" ====================================================================
836 The format lines are followed by lines containing the actual data for the
837 table, followed finally by
840 Within such data lines, items are normally separated by tab characters
841 (or the character specified with the
845 Long input lines can be broken across multiple lines if the last
846 character on the line is \[oq]\[rs]\[cq] (which vanishes after
853 computes the column widths line by line, applying \[rs]w on each entry
854 which isn't a text block.
856 As a consequence, constructions like
867 fail; you must either say
891 A dot starting a line, followed by anything but a digit is handled as
892 a troff command, passed through without changes.
894 The table position is unchanged in this case.
898 If a data line consists of only \[oq]_\[cq] or \[oq]=\[cq], a single
899 or double line, respectively, is drawn across the table at that point;
900 if a single item in a data line consists of only \[oq]_\[cq] or
901 \[oq]=\[cq], then that item is replaced by a single or double line,
902 joining its neighbours.
904 If a data item consists only of \[oq]\[rs]_\[cq] or \[oq]\[rs]=\[cq],
905 a single or double line, respectively, is drawn across the field at
906 that point which does not join its neighbours.
910 A data item consisting only of \[oq]\[rs]Rx\[cq] (\[oq]x\[cq] any
911 character) is replaced by repetitions of character \[oq]x\[cq] as wide
912 as the column (not joining its neighbours).
916 A data item consisting only of \[oq]\[rs]^\[cq] indicates that the
917 field immediately above spans downward over this row.
920 .\" ====================================================================
922 .\" ====================================================================
924 A text block can be used to enter data as a single entry which would
925 be too long as a simple string between tabs.
927 It is started with \[oq]T{\[cq] and closed with \[oq]T}\[cq].
929 The former must end a line, and the latter must start a line, probably
930 followed by other data columns (separated with tabs or the character
937 By default, the text block is formatted with the settings which were
938 active before entering the table, possibly overridden by the
945 For example, to make all text blocks ragged-right, insert
947 right before the starting
955 If either \[oq]w\[cq] or \[oq]x\[cq] specifiers are not given for
957 columns of a text block span, the default length of the text block (to
958 be more precise, the line length used to process the text block
959 diversion) is computed as L\[tmu]C/(N+1), where \[oq]L\[cq] is the
960 current line length, \[oq]C\[cq] the number of columns spanned by the
961 text block, and \[oq]N\[cq] the total number of columns in the table.
963 Note, however, that the actual diversion width as returned in register
965 is used eventually as the text block width.
967 If necessary, you can also control the text block width with a direct
970 request right after \[oq]T{\[cq].
973 .\" ====================================================================
975 .\" ====================================================================
979 holds the table width; it can't be used within the table itself
980 but is defined right before calling
982 so that this macro can make use of it.
989 which produces the bottom and side lines of a boxed table.
993 does call this macro itself at the end of the table, it can be used by
994 macro packages to create boxes for multi-page tables by calling it within the
997 An example of this is shown by the
999 macros which provide this functionality if a table starts with
1001 instead of the standard call to the
1006 .\" ====================================================================
1007 .SH "INTERACTION WITH @G@EQN"
1008 .\" ====================================================================
1010 .BR @g@tbl (@MAN1EXT@)
1011 should always be called before
1012 .BR @g@eqn (@MAN1EXT@)
1013 .RB ( groff (@MAN1EXT@)
1014 automatically takes care of the correct order of preprocessors).
1017 .\" ====================================================================
1018 .SH "GNU TBL ENHANCEMENTS"
1019 .\" ====================================================================
1021 There is no limit on the number of columns in a table, nor any limit on the
1022 number of text blocks.
1024 All the lines of a table are considered in deciding column widths, not just
1029 lines are not restricted to the first 200 lines.
1033 Numeric and alphabetic items may appear in the same column.
1037 Numeric and alphabetic items may span horizontally.
1042 uses register, string, macro and diversion names beginning with the digit\~\c
1047 you should avoid using any names beginning with a\~\c
1051 .\" ====================================================================
1052 .SH "GNU TBL WITHIN MACROS"
1053 .\" ====================================================================
1057 defines its own macros (right before each table) it is necessary to use
1058 an \[oq]end-of-macro\[cq] macro.
1060 Additionally, the escape character has to be switched off.
1075 \&.ATABLE Another table
1076 \&.ATABLE And \[dq]another one\[dq]
1081 Note, however, that not all features of
1083 can be wrapped into a macro because
1085 sees the input earlier than
1088 For example, number formatting with vertically aligned decimal points
1089 fails if those numbers are passed on as macro parameters because
1090 decimal point alignment is handled by
1092 itself: It only sees \[oq]\[rs]$1\[cq], \[oq]\[rs]$2\[cq], etc., and
1093 therefore can't recognize the decimal point.
1096 .\" ====================================================================
1098 .\" ====================================================================
1102 in conjunction with a supporting macro package for
1104 multi-page boxed tables.
1106 If there is no header that you wish to appear at the top of each page
1107 of the table, place the
1109 line immediately after the format section.
1111 Do not enclose a multi-page table within keep/release macros,
1112 or divert it in any other way.
1116 A text block within a table must be able to fit on one page.
1122 request cannot be used to force a page-break in a multi-page table.
1131 \&. ie '\[rs]\[rs]n(.z'' .bp \[rs]\[rs]$1
1132 \&. el \[rs]!.BP \[rs]\[rs]$1
1145 Using \[rs]a directly in a table to get leaders does not work (except in
1146 compatibility mode).
1148 This is correct behaviour: \[rs]a is an
1152 To get leaders use a real leader, either by using a control A or like
1167 A leading and/or trailing \[oq]|\[cq] in a format line, such as
1176 gives output which has a 1n\~space between the resulting
1177 bordering vertical rule and the content of the adjacent column,
1185 \&left column#right column
1191 If it is desired to have zero space (so that the rule touches
1192 the content), this can be achieved by introducing extra \[lq]dummy\[rq]
1193 columns, with no content and zero separation, before and/or after,
1201 \&#left column#right column#
1207 The resulting \[lq]dummy\[rq] columns are invisible and have zero width;
1208 note that such columns usually don't work with TTY devices.
1211 .\" ====================================================================
1213 .\" ====================================================================
1214 Lesk, M.E.: "TBL \[en] A Program to Format Tables".
1215 For copyright reasons it cannot be included in the groff distribution,
1216 but copies can be found with a title search on the World Wide Web.
1219 .\" ====================================================================
1221 .\" ====================================================================
1222 .BR groff (@MAN1EXT@),
1223 .BR @g@troff (@MAN1EXT@)
1226 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
1230 .\" Local Variables:
1233 .\" vim: set filetype=groff:
projects / platform / upstream / groff.git / blob