2 Copyright (C) 1989-1995, 2001, 2002 Free Software Foundation, Inc.
4 Permission is granted to make and distribute verbatim copies of
5 this manual provided the copyright notice and this permission notice
6 are preserved on all copies.
8 Permission is granted to copy and distribute modified versions of this
9 manual under the conditions for verbatim copying, provided that the
10 entire resulting derived work is distributed under the terms of a
11 permission notice identical to this one.
13 Permission is granted to copy and distribute translations of this
14 manual into another language, under the above conditions for modified
15 versions, except that this permission notice may be included in
16 translations approved by the Free Software Foundation instead of in
19 .TH @G@TBL @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
21 @g@tbl \- format tables for troff
35 This manual page describes the GNU version of
37 which is part of the groff document formatting system.
39 compiles descriptions of tables embedded within
41 input files into commands that are understood by
43 Normally, it should be invoked using the
47 It is highly compatible with Unix
49 The output generated by GNU
51 cannot be processed with Unix
53 it must be processed with GNU
55 If no files are given on the command line, the standard input
59 will cause the standard input to be read.
69 even when followed by a character other than space or newline.
72 Print the version number.
77 expects to find table descriptions wrapped in the
82 The line immediately following the
84 macro may contain any of the following global options (ignoring the case
85 of characters -- Unix tbl only accepts options with all characters lowercase
86 or all characters uppercase):
90 Centers the table (default is left-justified).
91 The alternative keyword name
93 is also recognized (this is a GNU tbl extension).
101 as start and end delimiters for
102 .BR @g@eqn (@MAN1EXT@).
106 Makes the table as wide as the current line length.
110 Encloses the table in a box.
114 Encloses the table in a double box.
118 Encloses each item of the table in a box.
122 Same as box (GNU tbl only).
126 Same as doublebox (GNU tbl only).
132 instead of a tab to separate items in a line of input data.
136 Sets lines or rules (e.g. from
144 Don't use diversions to prevent page breaks (GNU tbl only).
147 attempts to prevent undesirable breaks in the table by using diversions.
148 This can sometimes interact badly with macro packages' own use of
149 diversions, when footnotes, for example, are used.
152 .BI decimalpoint( c )
153 Set the character to be recognized as the decimal point in numeric
154 columns (GNU tbl only).
158 Ignore leading and trailing spaces in data items (GNU tbl only).
161 The global options must end with a semicolon.
162 There might be whitespace after an option and its argument in parentheses.
164 After global options come lines describing the format of each line of
166 Each such format line describes one line of the table itself, except that
167 the last format line (which you must end with a period) describes all
168 remaining lines of the table.
169 A single key character describes each column of each line of the table.
170 You may run format specs for multiple lines together on the same line by
171 separating them with commas.
173 You may follow each key character with specifiers that determine the font
174 and point size of the corresponding item, that determine column width,
175 inter-column spacing, etc.
177 The longest format line defines the number of columns in the table; missing
178 format descriptors at the end of format lines are assumed to be `L'.
179 Extra columns in the data (which have no corresponding format entry) are
182 The available key characters are:
186 Centers item within the column.
190 Right-justifies item within the column.
194 Left-justifies item within the column.
198 Numerically justifies item in the column: Units positions of numbers are
203 Spans previous item on the left into this column.
207 Centers longest line in this column and then left-justifies all other lines
208 in this column with respect to that centered line.
212 Spans down entry from previous row in this column.
216 Replaces this entry with a horizontal line.
221 Replaces this entry with a double horizontal line.
225 The corresponding column becomes a vertical rule (if two of these are
226 adjacent, a double vertical rule).
229 A vertical bar to the left of the first key-letter or to the right of the
230 last one produces a line at the edge of the table.
232 Here are the specifiers that can appear in suffixes to column key letters:
236 Short form of fB (make affected entries bold).
240 Short form of fI (make affected entries italic).
244 Start an item vertically spanning rows at the top of its range rather than
245 vertically centering it.
249 Start an item vertically spanning rows at the bottom of its range rather
250 than vertically centering it (GNU tbl only).
254 Followed by a number, this indicates the vertical line spacing to be used in
255 a multi-line table entry.
256 If signed, the current vertical line spacing is incremented or decremented
257 (using a signed number instead of a signed digit is a GNU tbl extension).
258 A vertical line spacing specifier followed by a column separation number
259 must be separated by one or more blanks.
260 No effect if the corresponding table entry isn't a text block.
264 Either of these specifiers may be followed by a font name (either one or two
265 characters long), font number (a single digit), or long name in parentheses
266 (the last form is a GNU tbl extension).
267 A one-letter font name must be separated by one or more blanks from whatever
272 Followed by a number, this does a point size change for the affected fields.
273 If signed, the current point size is incremented or decremented (using a
274 signed number instead of a signed digit is a GNU tbl extension).
275 A point size specifier followed by a column separation number must be
276 separated by one or more blanks.
280 Minimal column width value.
281 Must be followed either by a
282 .BR @g@troff (@MAN1EXT@)
283 width expression in parentheses or a unitless integer.
284 If no unit is given, en units are used.
285 Also used as the default line length for included text blocks.
286 If used multiple times to specify the width for a particular column,
287 the last entry takes effect.
291 Make equally-spaced columns.
295 Move the corresponding column up one half-line.
299 Ignore the corresponding column for width-calculation purposes.
302 A number suffix on a key character is interpreted as a column
303 separation in ens (multiplied in proportion if the
306 Default separation is 3n.
308 The format lines are followed by lines containing the actual data for the
309 table, followed finally by
311 Within such data lines, items are normally separated by tab characters (or
312 the character specified with the
315 Long input lines can be broken across multiple lines if the last character
316 on the line is `\e' (which vanishes after concatenation).
318 A dot starting a line, followed by anything but a digit is handled as a
319 troff command, passed through without changes.
320 The table position is unchanged in this case.
322 If a data line consists of only `_' or `=', a single or double line,
323 respectively, is drawn across the table at that point; if a single item in a
324 data line consists of only `_' or `=', then that item is replaced by a
325 single or double line, joining its neighbours.
326 If a data item consists only of `\e_' or `\e=', a single or double line,
327 respectively, is drawn across the field at that point which does not join
330 A data item consisting only of `\eRx' (`x' any character) is replaced by
331 repetitions of character `x' as wide as the column (not joining its
334 A data item consisting only of `\e^' indicates that the field immediately
335 above spans downward over this row.
337 A text block can be used to enter data as a single entry which would be
338 too long as a simple string between tabs.
339 It is started with `T{' and closed with `T}'.
340 The former must end a line, and the latter must start a line, probably
341 followed by other data columns (separated with tabs).
343 To change the data format within a table, use the
345 command (at the start of a line).
346 It is followed by format and data lines (but no global options) similar to
352 .SH "INTERACTION WITH @G@EQN"
353 .BR @g@tbl (@MAN1EXT@)
354 should always be called before
355 .BR @g@eqn (@MAN1EXT@)
356 .RB ( groff (@MAN1EXT@)
357 automatically takes care of the correct order of preprocessors).
360 .SH "GNU TBL ENHANCEMENTS"
361 There is no limit on the number of columns in a table, nor any limit on the
362 number of text blocks.
363 All the lines of a table are considered in deciding column widths, not just
367 lines are not restricted to the first 200 lines.
369 Numeric and alphabetic items may appear in the same column.
371 Numeric and alphabetic items may span horizontally.
374 uses register, string, macro and diversion names beginning with the digit\~\c
378 you should avoid using any names beginning with a\~\c
385 in conjunction with a supporting macro package for
387 multi-page boxed tables.
388 If there is no header that you wish to appear at the top of each page
389 of the table, place the
391 line immediately after the format section.
392 Do not enclose a multi-page table within keep/release macros,
393 or divert it in any other way.
395 A text block within a table must be able to fit on one page.
399 request cannot be used to force a page-break in a multi-page table.
406 .B .ie '\e\en(.z'' .bp \e\e$1
418 Using \ea directly in a table to get leaders will not work.
419 This is correct behaviour: \ea is an
422 To get leaders use a real leader, either by using a control A or like
438 Lesk, M.E.: "TBL -- A Program to Format Tables".
439 For copyright reasons it cannot be included in the groff distribution,
440 but copies can be found with a title search on the World Wide Web.
444 .BR groff (@MAN1EXT@),
445 .BR @g@troff (@MAN1EXT@)
projects / FreeBSD / FreeBSD.git / blob