| blob | 00dfe4f83009ecc17d3ccc85b2971193797a38ed |
1 .ig
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
18 the original English.
19 ..
20 .TH @G@TBL @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
21 .SH NAME
22 @g@tbl \- format tables for troff
23 .
24 .
25 .SH SYNOPSIS
26 .B @g@tbl
27 [
28 .B \-Cv
29 ]
30 [
31 .IR files \|.\|.\|.\&
32 ]
33 .
34 .
35 .SH DESCRIPTION
36 This manual page describes the GNU version of
37 .BR tbl ,
38 which is part of the groff document formatting system.
39 .B tbl
40 compiles descriptions of tables embedded within
41 .B troff
42 input files into commands that are understood by
43 .BR troff .
44 Normally, it should be invoked using the
45 .B \-t
46 option of
47 .B groff.
48 It is highly compatible with Unix
49 .BR tbl .
50 The output generated by GNU
51 .B tbl
52 cannot be processed with Unix
53 .BR troff ;
54 it must be processed with GNU
55 .BR troff .
56 If no files are given on the command line, the standard input
57 will be read.
58 A filename of
59 .B \-
60 will cause the standard input to be read.
61 .
62 .
63 .SH OPTIONS
64 .TP
65 .B \-C
66 Enable compatibility mode to
67 recognize
68 .B .TS
69 and
70 .B .TE
71 even when followed by a character other than space or newline.
72 Leader characters (\[rs]a) are handled as interpreted.
73 .TP
74 .B \-v
75 Print the version number.
76 .
77 .
78 .SH USAGE
79 .B tbl
80 expects to find table descriptions wrapped in the
81 .B .TS
82 (table start) and
83 .B .TE
84 (table end) macros.
85 The line immediately following the
86 .B .TS
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):
90 .
91 .TP
92 .B center
93 Centers the table (default is left-justified).
94 The alternative keyword name
95 .B centre
96 is also recognized (this is a GNU tbl extension).
97 .
98 .TP
99 .BI delim( xy )
100 Use
101 .I x
102 and
103 .I y
104 as start and end delimiters for
105 .BR @g@eqn (@MAN1EXT@).
106 .
107 .TP
108 .B expand
109 Makes the table as wide as the current line length.
110 .
111 .TP
112 .B box
113 Encloses the table in a box.
114 .
115 .TP
116 .B doublebox
117 Encloses the table in a double box.
118 .
119 .TP
120 .B allbox
121 Encloses each item of the table in a box.
122 .
123 .TP
124 .B frame
125 Same as box (GNU tbl only).
126 .
127 .TP
128 .B doubleframe
129 Same as doublebox (GNU tbl only).
130 .
131 .TP
132 .BI tab( x )
133 Uses the character
134 .I x
135 instead of a tab to separate items in a line of input data.
136 .
137 .TP
138 .BI linesize( n )
139 Sets lines or rules (e.g. from
140 .BR box )
141 in
142 .IR n -point
143 type.
144 .
145 .TP
146 .B nokeep
147 Don't use diversions to prevent page breaks (GNU tbl only).
148 Normally
149 .B tbl
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.
153 .
154 .TP
155 .BI decimalpoint( c )
156 Set the character to be recognized as the decimal point in numeric
157 columns (GNU tbl only).
158 .
159 .TP
160 .B nospaces
161 Ignore leading and trailing spaces in data items (GNU tbl only).
162 .
163 .LP
164 The global options must end with a semicolon.
165 There might be whitespace after an option and its argument in parentheses.
166 .LP
167 After global options come lines describing the format of each line of
168 the table.
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.
175 .LP
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.
179 .LP
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
183 ignored.
184 .LP
185 The available key characters are:
186 .
187 .TP
188 c,C
189 Centers item within the column.
190 .
191 .TP
192 r,R
193 Right-justifies item within the column.
194 .
195 .TP
196 l,L
197 Left-justifies item within the column.
198 .
199 .TP
200 n,N
201 Numerically justifies item in the column: Units positions of numbers are
202 aligned vertically.
203 .
204 .TP
205 s,S
206 Spans previous item on the left into this column.
207 .
208 .TP
209 a,A
210 Centers longest line in this column and then left-justifies all other lines
211 in this column with respect to that centered line.
212 .
213 .TP
214 ^
215 Spans down entry from previous row in this column.
216 .
217 .TP
218 _,-
219 Replaces this entry with a horizontal line.
220 .
221 .TP
222 =
223 .
224 Replaces this entry with a double horizontal line.
225 .
226 .TP
227 |
228 The corresponding column becomes a vertical rule (if two of these are
229 adjacent, a double vertical rule).
230 .
231 .LP
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.
234 .LP
235 Here are the specifiers that can appear in suffixes to column key letters:
236 .
237 .TP
238 b,B
239 Short form of fB (make affected entries bold).
240 .
241 .TP
242 i,I
243 Short form of fI (make affected entries italic).
244 .
245 .TP
246 t,T
247 Start an item vertically spanning rows at the top of its range rather than
248 vertically centering it.
249 .
250 .TP
251 d,D
252 Start an item vertically spanning rows at the bottom of its range rather
253 than vertically centering it (GNU tbl only).
254 .
255 .TP
256 v,V
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.
264 .
265 .TP
266 f,F
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
271 follows.
272 .
273 .TP
274 p,P
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.
280 .
281 .TP
282 w,W
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.
291 .
292 .TP
293 x,X
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
306 .B troff
307 requests to change the text block formatting, like text adjustment,
308 hyphenation, size, or font.
309 The macro is called
310 .I after
311 other cell modifications like
312 .BR b ,
313 .B f
314 or
315 .B v
316 are output.
317 Thus the macro can overwrite other modification specifiers.
318 .
319 .TP
320 e,E
321 Make equally-spaced columns.
322 .
323 .TP
324 u,U
325 Move the corresponding column up one half-line.
326 .
327 .TP
328 z,Z
329 Ignore the corresponding column for width-calculation purposes.
330 .
331 .LP
332 A number suffix on a key character is interpreted as a column
333 separation in ens (multiplied in proportion if the
334 .B expand
335 option is on).
336 Default separation is 3n.
337 .LP
338 The format lines are followed by lines containing the actual data for the
339 table, followed finally by
340 .BR .TE .
341 Within such data lines, items are normally separated by tab characters (or
342 the character specified with the
343 .B tab
344 option).
345 Long input lines can be broken across multiple lines if the last character
346 on the line is `\e' (which vanishes after concatenation).
347 .LP
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.
351 .LP
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
358 its neighbours.
359 .LP
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
362 neighbours).
363 .LP
364 A data item consisting only of `\e^' indicates that the field immediately
365 above spans downward over this row.
366 .LP
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
374 .B v
375 and
376 .B w
377 tbl specifiers.
378 For example, to make all text blocks ragged-right, insert
379 .B .na
380 right before the starting
381 .B .TS
382 (and
383 .B .ad
384 after the table).
385 .LP
386 To change the data format within a table, use the
387 .B .T&
388 command (at the start of a line).
389 It is followed by format and data lines (but no global options) similar to
390 the
391 .B .TS
392 request.
393 .
394 .
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).
401 .
402 .
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
407 the first 200.
408 Table continuation
409 .RB ( .T& )
410 lines are not restricted to the first 200 lines.
411 .LP
412 Numeric and alphabetic items may appear in the same column.
413 .LP
414 Numeric and alphabetic items may span horizontally.
415 .LP
416 .B @g@tbl
417 uses register, string, macro and diversion names beginning with the digit\~\c
418 .BR 3 .
419 When using
420 .B @g@tbl
421 you should avoid using any names beginning with a\~\c
422 .BR 3 .
423 .
424 .
425 .SH BUGS
426 You should use
427 .BR .TS\ H / .TH
428 in conjunction with a supporting macro package for
429 .I all
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
433 .B .TH
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.
437 .LP
438 A text block within a table must be able to fit on one page.
439 .LP
440 The
441 .B bp
442 request cannot be used to force a page-break in a multi-page table.
443 Instead, define
444 .B BP
445 as follows
446 .IP
447 .B .de BP
448 .br
449 .B .ie '\e\en(.z'' .bp \e\e$1
450 .br
451 .B .el \e!.BP \e\e$1
452 .br
453 .B ..
454 .br
455 .LP
456 and use
457 .B BP
458 instead of
459 .BR bp .
460 .LP
461 Using \ea directly in a table to get leaders will not work (except in
462 compatibility mode).
463 This is correct behaviour: \ea is an
464 .B uninterpreted
465 leader.
466 To get leaders use a real leader, either by using a control A or like
467 this:
468 .IP
469 .nf
470 .ft B
471 \&.ds a \ea
472 \&.TS
473 tab(;);
474 lw(1i) l.
475 A\e*a;B
476 \&.TE
477 .ft
478 .fi
479 .
480 .
481 .SH REFERENCE
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.
485 .
486 .
487 .SH "SEE ALSO"
488 .BR groff (@MAN1EXT@),
489 .BR @g@troff (@MAN1EXT@)
490 .
491 .\" Local Variables:
492 .\" mode: nroff
493 .\" End: