| blob | 0b6bdce68bdf8290b6d983458d89e5d2e6e6dd74 |
1 '\" t -- preprocess: tbl(1)
2 .ig
3 @ @L_P_TBL@.1
5 Copyright (c) 2014 - 2017 Steffen (Daode) Nurpmeso <steffen@sdaoden.eu>.
7 Copyright (C) 1989 - 1995, 2001 - 2004, 2006 - 2008
8 Free Software Foundation, Inc.
10 Permission is granted to make and distribute verbatim copies of
11 this manual provided the copyright notice and this permission notice
12 are preserved on all copies.
14 Permission is granted to copy and distribute modified versions of this
15 manual under the conditions for verbatim copying, provided that the
16 entire resulting derived work is distributed under the terms of a
17 permission notice identical to this one.
19 Permission is granted to copy and distribute translations of this
20 manual into another language, under the above conditions for modified
21 versions, except that this permission notice may be included in
22 translations approved by the Free Software Foundation instead of in
23 the original English.
24 ..
25 .
26 .do nr __compat \n[.C]
27 .cp 0
28 .
29 .
30 .TH @U_P_TBL@ @MAN1EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
31 .
32 .
33 .SH NAME
34 @L_P_TBL@ \- format tables for @T_ROFF@
35 .
36 .
37 .SH SYNOPSIS
38 .SY @L_P_TBL@
39 .OP \-Cv
40 .RI [ files\~ .\|.\|.]
41 .YS
42 .
43 .
44 .SH DESCRIPTION
45 .B @L_P_TBL@
46 compiles descriptions of tables embedded within
47 .B roff
48 input files into commands that are understood by
49 .BR @L_TROFF@ .
50 Normally, it should be invoked using the
51 .B \-t
52 option of
53 .B @L_ROFF@ .
54 It is highly compatible with Unix
55 .BR tbl .
56 The output generated by
57 .B @L_P_TBL@
58 cannot be processed with Unix
59 .BR troff ;
60 it must be processed with
61 .BR @L_TROFF@ .
62 If no files are given on the command line or a filename of
63 .B \-
64 is given, the standard input is read.
65 .
66 .
67 .SH OPTIONS
68 .TP
69 .B \-C
70 Enable compatibility mode to
71 recognize
72 .B .TS
73 and
74 .B .TE
75 even when followed by a character other than space or newline.
76 Leader characters (\[rs]a) are handled as interpreted.
77 .
78 .TP
79 .B \-v
80 Print the version number.
81 .
82 .
83 .SH USAGE
84 .B @L_P_TBL@
85 expects to find table descriptions wrapped in the
86 .B .TS
87 (table start) and
88 .B .TE
89 (table end) macros.
90 .
91 .
92 .SS Global options
93 The line immediately following the
94 .B .TS
95 macro may contain any of the following global options (ignoring the case of
96 characters \[en] Unix tbl only accepts options with all characters lowercase
97 or all characters uppercase), separated by spaces, tabs, or commas:
98 .
99 .TP
100 .B allbox
101 Enclose each item of the table in a box.
102 .
103 .TP
104 .B box
105 Enclose the table in a box.
106 .
107 .TP
108 .B center
109 Center the table (default is left-justified).
110 The alternative keyword name
111 .B centre
112 is also recognized (this is a @L_P_TBL@ extension).
113 .
114 .TP
115 .BI decimalpoint( c )
116 Set the character to be recognized as the decimal point in numeric
117 columns (@L_P_TBL@ only).
118 .
119 .TP
120 .BI delim( xy )
121 Use
122 .I x
123 and\~\c
124 .I y
125 as start and end delimiters for
126 .BR @L_P_EQN@ (@MAN1EXT@).
127 .
128 .TP
129 .B doublebox
130 Enclose the table in a double box.
131 .
132 .TP
133 .B doubleframe
134 Same as doublebox (@L_P_TBL@ only).
135 .
136 .TP
137 .B expand
138 Make the table as wide as the current line length (providing a column
139 separation factor).
140 Ignored if one or more `x' column specifiers are used (see below).
141 .
142 .IP
143 In case the sum of the column widths is larger than the current line length,
144 the column separation factor is set to zero; such tables extend into the
145 right margin, and there is no column separation at all.
146 .
147 .TP
148 .B frame
149 Same as box (@L_P_TBL@ only).
150 .
151 .TP
152 .BI linesize( n )
153 Set lines or rules (e.g. from
154 .BR box )
155 in
156 .IR n -point
157 type.
158 .
159 .TP
160 .B nokeep
161 Don't use diversions to prevent page breaks (@L_P_TBL@ only).
162 Normally
163 .B @L_P_TBL@
164 attempts to prevent undesirable breaks in boxed tables by using diversions.
165 This can sometimes interact badly with macro packages' own use of
166 diversions, when footnotes, for example, are used.
167 .
168 .TP
169 .B nospaces
170 Ignore leading and trailing spaces in data items (@L_P_TBL@ only).
171 .
172 .TP
173 .BI tab( x )
174 Use the character
175 .I x
176 instead of a tab to separate items in a line of input data.
177 .
178 .LP
179 The global options must end with a semicolon.
180 There might be whitespace between an option and its argument in parentheses.
181 .
182 .
183 .SS Table format specification
184 After global options come lines describing the format of each line of
185 the table.
186 Each such format line describes one line of the table itself, except that
187 the last format line (which you must end with a period) describes all
188 remaining lines of the table.
189 A single-key character describes each column of each line of the table.
190 Key characters can be separated by spaces or tabs.
191 You may run format specifications for multiple lines together on the same
192 line by separating them with commas.
193 .
194 .LP
195 You may follow each key character with specifiers that determine the font
196 and point size of the corresponding item, that determine column width,
197 inter-column spacing, etc.
198 .
199 .LP
200 The longest format line defines the number of columns in the table; missing
201 format descriptors at the end of format lines are assumed to be\~\c
202 .BR L .
203 Extra columns in the data (which have no corresponding format entry) are
204 ignored.
205 .
206 .LP
207 The available key characters are:
208 .
209 .TP
210 .BR a , A
211 Center longest line in this column and then left-justifies all other lines
212 in this column with respect to that centered line.
213 The idea is to use such alphabetic subcolumns (hence the name of the key
214 character) in combination with\~
215 .BR L ;
216 they are called subcolumns because
217 .BR A \~items
218 are indented by\~1n relative to
219 .BR L \~entries.
220 Example:
221 .RS
222 .IP
223 .EX
224 \&.TS
225 \&tab(;);
226 \&ln,an.
227 \&item one;1
228 \&subitem two;2
229 \&subitem three;3
230 \&.T&
231 \&ln,an.
232 \&item eleven;11
233 \&subitem twentytwo;22
234 \&subitem thirtythree;33
235 \&.TE
236 .EE
237 .RE
238 .
239 .IP
240 Result:
241 .
242 .RS
243 .IP
244 .TS
245 tab(;);
246 ln,an.
247 item one;1
248 subitem two;2
249 subitem three;3
250 .T&
251 ln,an.
252 item eleven;11
253 subitem twentytwo;22
254 subitem thirtythree;33
255 .TE
256 .RE
257 .
258 .TP
259 .BR c , C
260 Center item within the column.
261 .
262 .TP
263 .BR l , L
264 Left-justify item within the column.
265 .
266 .TP
267 .BR n , N
268 Numerically justify item in the column: Units positions of numbers are
269 aligned vertically.
270 If there is one or more dots adjacent to a digit, use the rightmost one for
271 vertical alignment.
272 If there is no dot, use the rightmost digit for vertical alignment;
273 otherwise, center the item within the column.
274 Alignment can be forced to a certain position using `\[rs]&'; if there is
275 one or more instances of this special (non-printing) character present
276 within the data, use the leftmost one for alignment.
277 Example:
278 .RS
279 .IP
280 .EX
281 \&.TS
282 \&n.
283 \&1
284 \&1.5
285 \&1.5.3
286 \&abcde
287 \&a\[rs]&bcde
288 \&.TE
289 .EE
290 .RE
291 .
292 .IP
293 Result:
294 .
295 .RS
296 .IP
297 .TS
298 n.
299 1
300 1.5
301 1.5.3
302 abcde
303 a\&bcde
304 .TE
305 .RE
306 .
307 .IP
308 If numerical entries are combined with
309 .B L
310 or
311 .BR R \~entries
312 \[en] this can happen if the table format is changed with
313 .B .T&
314 \%\[en],
315 center the widest
316 .I number
317 (of the data entered under the
318 .BR N \~specifier
319 regime) relative to the widest
320 .B L
321 or
322 .BR R \~entry,
323 preserving the alignment of all numerical entries.
324 Contrary to
325 .BR A \~type
326 entries, there is no extra indentation.
327 .
328 .IP
329 Using equations (to be processed with
330 .BR eqn )
331 within columns which use the
332 .BR N \~specifier
333 is problematic in most cases due to
334 .BR @L_P_TBL@ 's
335 algorithm for finding the vertical alignment, as described above.
336 Using the global
337 .B delim
338 option, however, it is possible to make
339 .B @L_P_TBL@
340 ignore the data within
341 .B eqn
342 delimiters for that purpose.
343 .
344 .
345 .TP
346 .BR r , R
347 Right-justify item within the column.
348 .
349 .TP
350 .BR s , S
351 Span previous item on the left into this column.
352 Not allowed for the first column.
353 .
354 .TP
355 .B ^
356 Span down entry from previous row in this column.
357 Not allowed for the first row.
358 .
359 .TP
360 .BR _ , -
361 Replace this entry with a horizontal line.
362 Note that `_' and `-' can be used for table fields only,
363 not for column separator lines.
364 .
365 .TP
366 .B =
367 Replace this entry with a double horizontal line.
368 Note that `=' can be used for table fields only,
369 not for column separator lines.
370 .
371 .TP
372 .B |
373 The corresponding column becomes a vertical rule (if two of these are
374 adjacent, a double vertical rule).
375 .
376 .LP
377 A vertical bar to the left of the first key letter or to the right of the
378 last one produces a line at the edge of the table.
379 .
380 .LP
381 To change the data format within a table, use the
382 .B .T&
383 command (at the start of a line).
384 It is followed by format and data lines (but no global options) similar to
385 the
386 .B .TS
387 request.
388 .
389 .
390 .SS Column specifiers
391 Here are the specifiers that can appear in suffixes to column key letters
392 (in any order):
393 .
394 .TP
395 .BR b , B
396 Short form of
397 .B fB
398 (make affected entries bold).
399 .
400 .TP
401 .BR d , D
402 Start an item that vertically spans rows,
403 using the `^' column specifier or `\[rs]^' data item,
404 than vertically centering it (@L_P_TBL@ only).
405 Example:
406 .RS
407 .IP
408 .EX
409 \&.TS
410 \&tab(;) allbox;
411 \&l l
412 \&l ld
413 \&r ^
414 \&l rd.
415 \&0000;foobar
416 \&T{
417 \&1111
418 \&.br
419 \&2222
420 \&T};foo
421 \&r;
422 \&T{
423 \&3333
424 \&.br
425 \&4444
426 \&T};bar
427 \&\[rs]^;\[rs]^
428 \&.TE
429 .EE
430 .RE
431 .
432 .IP
433 Result:
434 .
435 .RS
436 .IP
437 .TS
438 tab(;) allbox;
439 l l
440 l ld
441 r ^
442 l rd.
443 0000;foobar
444 T{
445 1111
446 .br
447 2222
448 T};foo
449 r;
450 T{
451 3333
452 .br
453 4444
454 T};bar
455 \^;\^
456 .TE
457 .RE
458 .
459 .TP
460 .BR e , E
461 Make equally-spaced columns.
462 All columns marked with this specifier get the same width; this happens
463 after the affected column widths have been computed (this means that the
464 largest width value rules).
465 .
466 .TP
467 .BR f , F
468 Either of these specifiers may be followed by a font name (either one or two
469 characters long), font number (a single digit), or long name in parentheses
470 (the last form is a @L_P_TBL@ extension).
471 A one-letter font name must be separated by one or more blanks from whatever
472 follows.
473 .
474 .TP
475 .BR i , I
476 Short form of
477 .B fI
478 (make affected entries italic).
479 .
480 .TP
481 .BR m , M
482 This is a @L_P_TBL@ extension.
483 Either of these specifiers may be followed by a macro name
484 (either one or two characters long),
485 or long name in parentheses.
486 A one-letter macro name must be separated by one or more blanks
487 from whatever follows.
488 The macro which name can be specified here
489 must be defined before creating the table.
490 It is called just before the table's cell text is output.
491 As implemented currently, this macro is only called if block input is used,
492 that is, text between `T{' and `T}'.
493 The macro should contain only simple
494 .B troff
495 requests to change the text block formatting, like text adjustment,
496 hyphenation, size, or font.
497 The macro is called
498 .I after
499 other cell modifications like
500 .BR b ,
501 .B f
502 or
503 .B v
504 are output.
505 Thus the macro can overwrite other modification specifiers.
506 .
507 .TP
508 .BR p , P
509 Followed by a number, this does a point size change for the affected fields.
510 If signed, the current point size is incremented or decremented (using a
511 signed number instead of a signed digit is a @L_P_TBL@ extension).
512 A point size specifier followed by a column separation number must be
513 separated by one or more blanks.
514 .
515 .TP
516 .BR t , T
517 Start an item vertically spanning rows at the top of its range rather than
518 vertically centering it.
519 .
520 .TP
521 .BR u , U
522 Move the corresponding column up one half-line.
523 .
524 .TP
525 .BR v , V
526 Followed by a number, this indicates the vertical line spacing to be used in
527 a multi-line table entry.
528 If signed, the current vertical line spacing is incremented or decremented
529 (using a signed number instead of a signed digit is a @L_P_TBL@ extension).
530 A vertical line spacing specifier followed by a column separation number
531 must be separated by one or more blanks.
532 No effect if the corresponding table entry isn't a text block.
533 .
534 .TP
535 .BR w , W
536 Minimal column width value.
537 Must be followed either by a
538 .BR @L_TROFF@ (@MAN1EXT@)
539 width expression in parentheses or a unitless integer.
540 If no unit is given, en units are used.
541 Also used as the default line length for included text blocks.
542 If used multiple times to specify the width for a particular column,
543 the last entry takes effect.
544 .
545 .TP
546 .BR x , X
547 An expanded column.
548 After computing all column widths without an
549 .BR x \~specifier,
550 use the remaining line width for this column.
551 If there is more than one expanded column, distribute the remaining
552 horizontal space evenly among the affected columns (this is a @L_P_TBL@
553 extension).
554 This feature has the same effect as specifying a minimum column width.
555 .
556 .TP
557 .BR z , Z
558 Ignore the corresponding column for width-calculation purposes, this is,
559 don't use the fields but only the specifiers of this column to compute
560 its width.
561 .
562 .LP
563 A number suffix on a key character is interpreted as a column
564 separation in en units (multiplied in proportion if the
565 .B expand
566 option is on \[en] in case of overfull tables this might be zero).
567 Default separation is 3n.
568 .
569 .LP
570 The column
571 .RB specifier\~ x
572 is mutually exclusive with
573 .B e
574 .RB and\~ w
575 (but
576 .B e
577 is not mutually exclusive
578 .RB with\~ w );
579 if specified multiple times for a particular column, the last entry takes
580 effect:
581 .BR x \~unsets
582 both
583 .B e
584 .RB and\~ w ,
585 while either
586 .B e
587 or
588 .B w
589 .RB overrides\~ x .
590 .
591 .
592 .SS Table data
593 The format lines are followed by lines containing the actual data for the
594 table, followed finally by
595 .BR .TE .
596 Within such data lines, items are normally separated by tab characters (or
597 the character specified with the
598 .B tab
599 option).
600 Long input lines can be broken across multiple lines if the last character
601 on the line is `\[rs]' (which vanishes after concatenation).
602 .
603 .LP
604 Note that
605 .B @L_P_TBL@
606 computes the column widths line by line, applying \[rs]w on each entry
607 which isn't a text block.
608 As a consequence, constructions like
609 .IP
610 .EX
611 \&.TS
612 \&c,l.
613 \&\[rs]s[20]MM
614 \&MMMM
615 \&.TE
616 .EE
617 .
618 .LP
619 fail; you must either say
620 .IP
621 .EX
622 \&.TS
623 \&cp20,lp20.
624 \&MM
625 \&MMMM
626 \&.TE
627 .EE
628 .
629 .LP
630 or
631 .
632 .IP
633 .EX
634 \&.TS
635 \&c,l.
636 \&\[rs]s[20]MM
637 \&\[rs]s[20]MMMM
638 \&.TE
639 .EE
640 .
641 .LP
642 A dot starting a line, followed by anything but a digit is handled as a
643 troff command, passed through without changes.
644 The table position is unchanged in this case.
645 .
646 .LP
647 If a data line consists of only `_' or `=', a single or double line,
648 respectively, is drawn across the table at that point; if a single item in a
649 data line consists of only `_' or `=', then that item is replaced by a
650 single or double line, joining its neighbours.
651 If a data item consists only of `\[rs]_' or `\[rs]=', a single or double line,
652 respectively, is drawn across the field at that point which does not join
653 its neighbours.
654 .
655 .LP
656 A data item consisting only of `\[rs]Rx' (`x' any character) is replaced by
657 repetitions of character `x' as wide as the column (not joining its
658 neighbours).
659 .
660 .LP
661 A data item consisting only of `\[rs]^' indicates that the field immediately
662 above spans downward over this row.
663 .
664 .
665 .SS Text blocks
666 A text block can be used to enter data as a single entry which would be
667 too long as a simple string between tabs.
668 It is started with `T{' and closed with `T}'.
669 The former must end a line, and the latter must start a line, probably
670 followed by other data columns (separated with tabs or the character given
671 with the
672 .B tab
673 global option).
674 .
675 .LP
676 By default, the text block is formatted with the settings which were
677 active before entering the table, possibly overridden by the
678 .BR m ,
679 .BR v ,
680 and
681 .B w
682 @L_P_TBL@ specifiers.
683 For example, to make all text blocks ragged-right, insert
684 .B .na
685 right before the starting
686 .B .TS
687 (and
688 .B .ad
689 after the table).
690 .
691 .LP
692 If either `w' or `x' specifiers are not given for
693 .I all
694 columns of a text block span, the default length of the text block (to be
695 more precise, the line length used to process the text block diversion) is
696 computed as L\[tmu]C/(N+1), where `L' is the current line length, `C' the
697 number of columns spanned by the text block, and `N' the total number of
698 columns in the table.
699 Note, however, that the actual diversion width as returned in register
700 .B \[rs]n[dl]
701 is used eventually as the text block width.
702 If necessary, you can also control the text block width with a direct
703 insertion of a
704 .B .ll
705 request right after `T{'.
706 .
707 .
708 .SS Miscellaneous
709 The number register
710 .B \[rs]n[TW]
711 holds the table width; it can't be used within the table itself but is defined
712 right before calling
713 .B .TE
714 so that this macro can make use of it.
715 .
716 .LP
717 .B @L_P_TBL@
718 also defines a macro
719 .B .T#
720 which produces the bottom and side lines of a boxed table.
721 While
722 .B @L_P_TBL@
723 does call this macro itself at the end of the table, it can be used by
724 macro packages to create boxes for multi-page tables by calling it within the
725 page footer.
726 An example of this is shown by the
727 .B \-ms
728 macros which provide this functionality if a table starts with
729 .B .TS\ H
730 instead of the standard call to the
731 .B .TS
732 macro.
733 .
734 .
735 .SH "INTERACTION WITH @L_P_EQN@"
736 .BR @L_P_TBL@ (@MAN1EXT@)
737 should always be called before
738 .BR @L_P_EQN@ (@MAN1EXT@)
739 .RB ( @L_ROFF@ (@MAN1EXT@)
740 automatically takes care of the correct order of preprocessors).
741 .
742 .
743 .SH "@L_P_TBL@ ENHANCEMENTS"
744 There is no limit on the number of columns in a table, nor any limit on the
745 number of text blocks.
746 All the lines of a table are considered in deciding column widths, not just
747 the first 200.
748 Table continuation
749 .RB ( .T& )
750 lines are not restricted to the first 200 lines.
751 .
752 .LP
753 Numeric and alphabetic items may appear in the same column.
754 .
755 .LP
756 Numeric and alphabetic items may span horizontally.
757 .
758 .LP
759 .B @L_P_TBL@
760 uses register, string, macro and diversion names beginning with the digit\~\c
761 .BR 3 .
762 When using
763 .B @L_P_TBL@
764 you should avoid using any names beginning with a\~\c
765 .BR 3 .
766 .
767 .
768 .SH "@L_P_TBL@ WITHIN MACROS"
769 Since
770 .B @L_P_TBL@
771 defines its own macros (right before each table) it is necessary to use
772 an `end-of-macro' macro. Additionally, the escape character has to be switched
773 off. Here an example.
774 .IP
775 .EX
776 \&.eo
777 \&.de ATABLE ..
778 \&.TS
779 \&allbox tab(;);
780 \&cl.
781 \&\[rs]$1;\[rs]$2
782 \&.TE
783 \&...
784 \&.ec
785 \&.ATABLE A table
786 \&.ATABLE Another table
787 \&.ATABLE And \[dq]another one\[dq]
788 .EE
789 .
790 .LP
791 Note, however, that not all features of
792 .B @L_P_TBL@
793 can be wrapped into a macro because
794 .B @L_P_TBL@
795 sees the input earlier than
796 .BR @L_TROFF@ .
797 For example, number formatting with vertically aligned decimal points
798 fails if those numbers are passed on as macro parameters because
799 decimal point alignment is handled by
800 .B @L_P_TBL@
801 itself: It only sees `\[rs]$1', `\[rs]$2', etc., and therefore can't
802 recognize the decimal point.
803 .
804 .
805 .SH BUGS
806 You should use
807 .BR .TS\ H / .TH
808 in conjunction with a supporting macro package for
809 .I all
810 multi-page boxed tables.
811 If there is no header that you wish to appear at the top of each page
812 of the table, place the
813 .B .TH
814 line immediately after the format section.
815 Do not enclose a multi-page table within keep/release macros,
816 or divert it in any other way.
817 .
818 .LP
819 A text block within a table must be able to fit on one page.
820 .
821 .LP
822 The
823 .B bp
824 request cannot be used to force a page-break in a multi-page table.
825 Instead, define
826 .B BP
827 as follows
828 .
829 .IP
830 .EX
831 \&.de BP
832 \&. ie '\[rs]\[rs]n(.z'' .bp \[rs]\[rs]$1
833 \&. el \[rs]!.BP \[rs]\[rs]$1
834 \&..
835 .EE
836 .
837 .LP
838 and use
839 .B BP
840 instead of
841 .BR bp .
842 .
843 .LP
844 Using \[rs]a directly in a table to get leaders does not work (except in
845 compatibility mode).
846 This is correct behaviour: \[rs]a is an
847 .B uninterpreted
848 leader.
849 To get leaders use a real leader, either by using a control A or like
850 this:
851 .
852 .IP
853 .EX
854 \&.ds a \[rs]a
855 \&.TS
856 \&tab(;);
857 \&lw(1i) l.
858 \&A\[rs]*a;B
859 \&.TE
860 .EE
861 .
862 .
863 .LP
864 A leading and/or trailing `|' in a format line, such as
865 .
866 .IP
867 .EX
868 |l r|.
869 .EE
870 .
871 .LP
872 gives output which has a 1n\~space between the resulting
873 bordering vertical rule and the content of the adjacent column,
874 as in
875 .
876 .IP
877 .EX
878 \&.TS
879 \&tab(#);
880 \&|l r|.
881 \&left column#right column
882 \&.TE
883 .EE
884 .
885 .LP
886 If it is desired to have zero space (so that the rule touches
887 the content), this can be achieved by introducing extra \[lq]dummy\[rq]
888 columns, with no content and zero separation, before and/or after,
889 as in
890 .
891 .IP
892 .EX
893 \&.TS
894 \&tab(#);
895 \&r0|l r0|l.
896 \&#left column#right column#
897 \&.TE
898 .EE
899 .
900 .LP
901 The resulting \[lq]dummy\[rq] columns are invisible and have zero width;
902 note that such columns usually don't work with TTY devices.
903 .
904 .
905 .SH REFERENCE
906 Lesk, M.E.: "TBL \[en] A Program to Format Tables".
907 For copyright reasons it cannot be included in the groff distribution,
908 but copies can be found with a title search on the World Wide Web.
909 .
910 .
911 .SH "SEE ALSO"
912 .BR @L_ROFF@ (@MAN1EXT@),
913 .BR @L_TROFF@ (@MAN1EXT@)
914 .
915 .cp \n[__compat]
916 .rr __compat
917 .
918 .\" s-ts-mode