2 Copyright (C) 1989-1995, 2001, 2002, 2003, 2004
3 Free Software Foundation, Inc.
5 Permission is granted to make and distribute verbatim copies of
6 this manual provided the copyright notice and this permission notice
7 are preserved on all copies.
9 Permission is granted to copy and distribute modified versions of this
10 manual under the conditions for verbatim copying, provided that the
11 entire resulting derived work is distributed under the terms of a
12 permission notice identical to this one.
14 Permission is granted to copy and distribute translations of this
15 manual into another language, under the above conditions for modified
16 versions, except that this permission notice may be included in
17 translations approved by the Free Software Foundation instead of in
20 .TH @G@TBL @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
22 @g@tbl \- format tables for troff
36 This manual page describes the GNU version of
38 which is part of the groff document formatting system.
40 compiles descriptions of tables embedded within
42 input files into commands that are understood by
44 Normally, it should be invoked using the
48 It is highly compatible with Unix
50 The output generated by GNU
52 cannot be processed with Unix
54 it must be processed with GNU
56 If no files are given on the command line, the standard input
60 will cause the standard input to be read.
66 Enable compatibility mode to
71 even when followed by a character other than space or newline.
72 Leader characters (\[rs]a) are handled as interpreted.
75 Print the version number.
80 expects to find table descriptions wrapped in the
85 The line immediately following the
87 macro may contain any of the following global options (ignoring the case
88 of characters -- Unix tbl only accepts options with all characters lowercase
89 or all characters uppercase):
93 Centers the table (default is left-justified).
94 The alternative keyword name
96 is also recognized (this is a GNU tbl extension).
104 as start and end delimiters for
105 .BR @g@eqn (@MAN1EXT@).
109 Makes the table as wide as the current line length.
113 Encloses the table in a box.
117 Encloses the table in a double box.
121 Encloses each item of the table in a box.
125 Same as box (GNU tbl only).
129 Same as doublebox (GNU tbl only).
135 instead of a tab to separate items in a line of input data.
139 Sets lines or rules (e.g. from
147 Don't use diversions to prevent page breaks (GNU tbl only).
150 attempts to prevent undesirable breaks in the table by using diversions.
151 This can sometimes interact badly with macro packages' own use of
152 diversions, when footnotes, for example, are used.
155 .BI decimalpoint( c )
156 Set the character to be recognized as the decimal point in numeric
157 columns (GNU tbl only).
161 Ignore leading and trailing spaces in data items (GNU tbl only).
164 The global options must end with a semicolon.
165 There might be whitespace after an option and its argument in parentheses.
167 After global options come lines describing the format of each line of
169 Each such format line describes one line of the table itself, except that
170 the last format line (which you must end with a period) describes all
171 remaining lines of the table.
172 A single key character describes each column of each line of the table.
173 You may run format specs for multiple lines together on the same line by
174 separating them with commas.
176 You may follow each key character with specifiers that determine the font
177 and point size of the corresponding item, that determine column width,
178 inter-column spacing, etc.
180 The longest format line defines the number of columns in the table; missing
181 format descriptors at the end of format lines are assumed to be `L'.
182 Extra columns in the data (which have no corresponding format entry) are
185 The available key characters are:
189 Centers item within the column.
193 Right-justifies item within the column.
197 Left-justifies item within the column.
201 Numerically justifies item in the column: Units positions of numbers are
206 Spans previous item on the left into this column.
210 Centers longest line in this column and then left-justifies all other lines
211 in this column with respect to that centered line.
215 Spans down entry from previous row in this column.
219 Replaces this entry with a horizontal line.
224 Replaces this entry with a double horizontal line.
228 The corresponding column becomes a vertical rule (if two of these are
229 adjacent, a double vertical rule).
232 A vertical bar to the left of the first key-letter or to the right of the
233 last one produces a line at the edge of the table.
235 Here are the specifiers that can appear in suffixes to column key letters:
239 Short form of fB (make affected entries bold).
243 Short form of fI (make affected entries italic).
247 Start an item vertically spanning rows at the top of its range rather than
248 vertically centering it.
252 Start an item vertically spanning rows at the bottom of its range rather
253 than vertically centering it (GNU tbl only).
257 Followed by a number, this indicates the vertical line spacing to be used in
258 a multi-line table entry.
259 If signed, the current vertical line spacing is incremented or decremented
260 (using a signed number instead of a signed digit is a GNU tbl extension).
261 A vertical line spacing specifier followed by a column separation number
262 must be separated by one or more blanks.
263 No effect if the corresponding table entry isn't a text block.
267 Either of these specifiers may be followed by a font name (either one or two
268 characters long), font number (a single digit), or long name in parentheses
269 (the last form is a GNU tbl extension).
270 A one-letter font name must be separated by one or more blanks from whatever
275 Followed by a number, this does a point size change for the affected fields.
276 If signed, the current point size is incremented or decremented (using a
277 signed number instead of a signed digit is a GNU tbl extension).
278 A point size specifier followed by a column separation number must be
279 separated by one or more blanks.
283 Minimal column width value.
284 Must be followed either by a
285 .BR @g@troff (@MAN1EXT@)
286 width expression in parentheses or a unitless integer.
287 If no unit is given, en units are used.
288 Also used as the default line length for included text blocks.
289 If used multiple times to specify the width for a particular column,
290 the last entry takes effect.
294 This is a GNU tbl extension.
295 Either of these specifiers may be followed by a macro name
296 (either one or two characters long),
297 or long name in parentheses.
298 A one-letter macro name must be separated by one or more blanks
299 from whatever follows.
300 The macro which name can be specified here
301 must be defined before creating the table.
302 It is called just before the table's cell text is output.
303 As implemented currently, this macro is only called if block input is used,
304 that is, text between `T{' and `T}'.
305 The macro should contain only simple
307 requests to change the text block formatting, like text adjustment,
308 hyphenation, size, or font.
311 other cell modifications like
317 Thus the macro can overwrite other modification specifiers.
321 Make equally-spaced columns.
325 Move the corresponding column up one half-line.
329 Ignore the corresponding column for width-calculation purposes.
332 A number suffix on a key character is interpreted as a column
333 separation in ens (multiplied in proportion if the
336 Default separation is 3n.
338 The format lines are followed by lines containing the actual data for the
339 table, followed finally by
341 Within such data lines, items are normally separated by tab characters (or
342 the character specified with the
345 Long input lines can be broken across multiple lines if the last character
346 on the line is `\e' (which vanishes after concatenation).
348 A dot starting a line, followed by anything but a digit is handled as a
349 troff command, passed through without changes.
350 The table position is unchanged in this case.
352 If a data line consists of only `_' or `=', a single or double line,
353 respectively, is drawn across the table at that point; if a single item in a
354 data line consists of only `_' or `=', then that item is replaced by a
355 single or double line, joining its neighbours.
356 If a data item consists only of `\e_' or `\e=', a single or double line,
357 respectively, is drawn across the field at that point which does not join
360 A data item consisting only of `\eRx' (`x' any character) is replaced by
361 repetitions of character `x' as wide as the column (not joining its
364 A data item consisting only of `\e^' indicates that the field immediately
365 above spans downward over this row.
367 A text block can be used to enter data as a single entry which would be
368 too long as a simple string between tabs.
369 It is started with `T{' and closed with `T}'.
370 The former must end a line, and the latter must start a line, probably
371 followed by other data columns (separated with tabs).
372 By default, the text block is formatted with the settings which were
373 active before entering the table, possibly overridden by the
378 For example, to make all text blocks ragged-right, insert
380 right before the starting
386 To change the data format within a table, use the
388 command (at the start of a line).
389 It is followed by format and data lines (but no global options) similar to
395 .SH "INTERACTION WITH @G@EQN"
396 .BR @g@tbl (@MAN1EXT@)
397 should always be called before
398 .BR @g@eqn (@MAN1EXT@)
399 .RB ( groff (@MAN1EXT@)
400 automatically takes care of the correct order of preprocessors).
403 .SH "GNU TBL ENHANCEMENTS"
404 There is no limit on the number of columns in a table, nor any limit on the
405 number of text blocks.
406 All the lines of a table are considered in deciding column widths, not just
410 lines are not restricted to the first 200 lines.
412 Numeric and alphabetic items may appear in the same column.
414 Numeric and alphabetic items may span horizontally.
417 uses register, string, macro and diversion names beginning with the digit\~\c
421 you should avoid using any names beginning with a\~\c
428 in conjunction with a supporting macro package for
430 multi-page boxed tables.
431 If there is no header that you wish to appear at the top of each page
432 of the table, place the
434 line immediately after the format section.
435 Do not enclose a multi-page table within keep/release macros,
436 or divert it in any other way.
438 A text block within a table must be able to fit on one page.
442 request cannot be used to force a page-break in a multi-page table.
449 .B .ie '\e\en(.z'' .bp \e\e$1
461 Using \ea directly in a table to get leaders will not work (except in
463 This is correct behaviour: \ea is an
466 To get leaders use a real leader, either by using a control A or like
482 Lesk, M.E.: "TBL -- A Program to Format Tables".
483 For copyright reasons it cannot be included in the groff distribution,
484 but copies can be found with a title search on the World Wide Web.
488 .BR groff (@MAN1EXT@),
489 .BR @g@troff (@MAN1EXT@)
tuxillo's projects / dragonfly.git / blob