Debian Codegraph @

upstream/debian-unstable/man1/tbl.1

raw
1 '\" t
2 .TH \%tbl 1 "2026-04-22" "groff 1.24.1"
3 .SH Name
4 \%tbl \- prepare tables for
5 .I groff
6 documents
7 .
8 .
9 .\" ====================================================================
10 .\" Legal Terms
11 .\" ====================================================================
12 .\"
13 .\" Copyright 1989-2020 Free Software Foundation, Inc.
14 .\" 2020-2024 G. Branden Robinson
15 .\"
16 .\" Permission is granted to make and distribute verbatim copies of this
17 .\" manual provided the copyright notice and this permission notice are
18 .\" preserved on all copies.
19 .\"
20 .\" Permission is granted to copy and distribute modified versions of
21 .\" this manual under the conditions for verbatim copying, provided that
22 .\" the entire resulting derived work is distributed under the terms of
23 .\" a permission notice identical to this one.
24 .\"
25 .\" Permission is granted to copy and distribute translations of this
26 .\" manual into another language, under the above conditions for
27 .\" modified versions, except that this permission notice may be
28 .\" included in translations approved by the Free Software Foundation
29 .\" instead of in the original English.
30 .
31 .
32 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
33 .do nr *groff_tbl_1_man_C \n[.cp]
34 .cp 0
35 .
36 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
37 .nr do-fallback 0
38 .if !\n(.f .nr do-fallback 1 \" mandoc
39 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
40 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
41 .if \n[do-fallback] \{\
42 . de MR
43 . ie \\n(.$=1 \
44 . I \%\\$1
45 . el \
46 . IR \%\\$1 (\\$2)\\$3
47 . .
48 .\}
49 .rr do-fallback
50 .
51 .
52 .\" ====================================================================
53 .SH Synopsis
54 .\" ====================================================================
55 .
56 .SY \%tbl
57 .RB [ \-C ]
58 .RI [ file\~ .\|.\|.]
59 .YS
60 .
61 .
62 .P
63 .SY \%tbl
64 .B \-\-help
65 .YS
66 .
67 .
68 .P
69 .SY \%tbl
70 .B \-v
71 .YS
72 .
73 .SY \%tbl
74 .B \%\-\-version
75 .YS
76 .
77 .
78 .\" ====================================================================
79 .SH Description
80 .\" ====================================================================
81 .
82 The GNU implementation of
83 .I tbl \" generic
84 is part of the
85 .MR groff 1
86 document formatting system.
87 .
88 .I \%tbl
89 is a
90 .MR \%troff 1
91 preprocessor that translates descriptions of tables embedded in
92 .MR roff 7
93 input into the language understood by
94 .IR \%troff .
95 .
96 It copies each
97 .IR file 's
98 contents to the standard output stream,
99 transforming each
100 .I "table region"
101 between lines starting with
102 .B .TS
103 and
104 .B .TE
105 into instructions to the GNU
106 .I troff \" GNU
107 formatter.
108 .
109 While GNU
110 .IR tbl 's \" GNU
111 input syntax is highly compatible with AT&T
112 .IR tbl , \" AT&T
113 the output GNU
114 .I tbl \" GNU
115 produces cannot be processed by AT&T
116 .IR troff ; \" AT&T
117 GNU
118 .I troff \" GNU
119 (or a
120 .I troff \" generic
121 implementing any GNU extensions employed)
122 must be used.
123 .
124 Normally,
125 .I \%tbl
126 is not executed directly by the user,
127 but invoked by specifying the
128 .B \-t
129 option to
130 .MR groff 1 .
131 .
132 If no
133 .I file
134 operands are present,
135 or if
136 .I file
137 is
138 .RB \[lq] \- \[rq],
139 .I \%tbl
140 reads the standard input stream.
141 .
142 .
143 .\" ====================================================================
144 .SS Overview
145 .\" ====================================================================
146 .
147 .I \%tbl
148 expects to find table descriptions between input lines that begin with
149 .B .TS
150 (table start)
151 and
152 .B .TE
153 (table end).
154 .
155 Each such table region encloses one or more table descriptions.
156 .
157 Within a table region,
158 table descriptions beyond the first must each be preceded
159 by an input line beginning with
160 .BR .T& .
161 .
162 This mechanism does not start a new table region;
163 all table descriptions are treated as part of their
164 .BR .TS / .TE
165 enclosure,
166 even if they are boxed or have column headings that repeat on subsequent
167 pages
168 (see below).
169 .
170 .
171 .\" XXX: The following is a general caveat about preprocessors (or would
172 .\" be, once recast); move it.
173 .P
174 (Experienced
175 .I roff
176 users should observe that
177 .I \%tbl
178 is not a
179 .I roff
180 language interpreter:
181 the default control character must be used,
182 and no spaces or tabs are permitted between the control character and
183 the macro name.
184 .
185 These
186 .I \%tbl
187 input tokens remain as-is in the output,
188 where they become ordinary macro calls.
189 .
190 Macro packages often define
191 .BR TS ,
192 .BR T& ,
193 and
194 .B TE
195 macros to handle issues of table placement on the page.
196 .
197 .I \%tbl
198 produces
199 .I troff \" generic
200 requests to define these macros as empty
201 if their definitions do not exist
202 when the formatter encounters a table region.)
203 .
204 .
205 .P
206 Each table region may begin with
207 .I region options,
208 and must contain one or more
209 .I table definitions;
210 each table definition contains a
211 .I format specification
212 followed by one or more input lines (rows) of
213 .I entries.
214 .
215 These entries comprise the
216 .I table data.
217 .
218 .
219 .
220 .\" ====================================================================
221 .SS "Region options"
222 .\" ====================================================================
223 .
224 The line immediately following the
225 .B .TS
226 token may specify region options,
227 keywords that influence the interpretation or rendering of the region as
228 a whole or all table entries within it indiscriminately.
229 .
230 Separate multiple region options with commas,
231 spaces,
232 or tabs.
233 .
234 Those that require a parenthesized argument permit spaces and tabs
235 between the option's name and the opening parenthesis.
236 .
237 Options accumulate and cannot be unset within a region once declared;
238 if an option that takes a parameter is repeated,
239 the last occurrence controls.
240 .
241 If present,
242 the set of region options must be terminated with a semicolon
243 .RB ( ; ).
244 .
245 .
246 .P
247 Any of the
248 .BR allbox ,
249 .BR box ,
250 .BR doublebox ,
251 .BR frame ,
252 and
253 .B doubleframe
254 region options makes a table \[lq]boxed\[rq] for the purpose of later
255 discussion.
256 .
257 .
258 .TP 17n \" "decimalpoint(c)" + 2n
259 .B allbox
260 Enclose each table entry in a box;
261 implies
262 .BR box .
263 .
264 .
265 .TP
266 .B box
267 Enclose the entire table region in a box.
268 .
269 GNU
270 .I tbl \" GNU
271 recognizes
272 .B frame
273 as a synonym.
274 .
275 .
276 .TP
277 .B center
278 Center the table region with respect to the line length,
279 reducing the indentation if necessary
280 (with a warning at formatting time)
281 to make the table region fit;
282 the default is to left-align it.
283 .
284 GNU
285 .I tbl \" GNU
286 recognizes
287 .B centre
288 as a synonym.
289 .
290 .
291 .TP
292 .BI decimalpoint( c )
293 Recognize character
294 .I c
295 as the decimal separator in columns using the
296 .B N
297 (numeric) classifier
298 (see subsection \[lq]Column classifiers\[rq] below).
299 .
300 This is a GNU extension.
301 .
302 .
303 .TP
304 .BI delim( xy )
305 Recognize characters
306 .I x
307 .RI and\~ y
308 as start and end delimiters,
309 respectively,
310 for
311 .MR \%eqn 1
312 input,
313 and ignore input between them.
314 .
315 .I x
316 .RI and\~ y
317 need not be distinct.
318 .
319 .
320 .TP
321 .B doublebox
322 Enclose the entire table region in a double box;
323 implies
324 .BR box .
325 .
326 GNU
327 .I tbl \" GNU
328 recognizes
329 .B \%doubleframe
330 as a synonym.
331 .
332 .
333 .TP
334 .B expand
335 Spread the table horizontally to fill the available space
336 (line length minus indentation)
337 by increasing column separation.
338 .
339 Ordinarily,
340 a table is made only as wide as necessary to accommodate the widths of
341 its entries and its column separations
342 (whether specified or default).
343 .
344 When
345 .B \%expand
346 applies to a table that exceeds the available horizontal space,
347 .I tbl \" generic
348 reduces column separation as far as necessary
349 (even to zero).
350 .
351 .I \%tbl
352 produces
353 .I \%troff
354 input that issues a diagnostic if such compression occurs.
355 .
356 The column modifier
357 .B x
358 (see below)
359 overrides this option.
360 .
361 .
362 .TP
363 .BI linesize( n )
364 Draw lines or rules
365 (e.g.,
366 from
367 .BR box )
368 with a thickness of
369 .IR n \~points.
370 .
371 The default is the current type size when the region begins.
372 .
373 This option has no effect on terminal devices.
374 .
375 .
376 .TP
377 .B nokeep
378 Don't use
379 .I roff
380 diversions to manage page breaks.
381 .
382 Normally,
383 .I \%tbl
384 employs them to avoid breaking a page within a table row.
385 .
386 This usage can sometimes interact badly with macro packages' own use of
387 diversions\[em]when footnotes,
388 for example,
389 are employed.
390 .
391 This is a GNU extension.
392 .
393 .
394 .TP
395 .B nospaces
396 Ignore leading and trailing spaces in table entries.
397 .
398 This is a GNU extension.
399 .
400 .
401 .TP
402 .B nowarn
403 Suppress diagnostic messages produced at document formatting time when
404 the line length and indentation
405 or page length
406 is inadequate to contain a table row.
407 .
408 This is a GNU extension.
409 .
410 .
411 .\" TODO: How about "right"? (and "left" for symmetry)
412 .TP
413 .BI tab( c )
414 Use the character
415 .I c
416 instead of a tab to separate entries in a row of table data.
417 .
418 .
419 .\" ====================================================================
420 .SS "Table format specification"
421 .\" ====================================================================
422 .
423 The table format specification is mandatory:
424 it determines the number of columns in the table and directs how the
425 entries within it are to be typeset.
426 .
427 The format specification is a series of column
428 .I descriptors.
429 .
430 Each descriptor encodes a
431 .I classifier
432 followed by zero or more
433 .I modifiers.
434 .
435 Classifiers are letters
436 (recognized case-insensitively)
437 or punctuation symbols;
438 modifiers consist of or begin with letters or numerals.
439 .
440 Spaces,
441 tabs,
442 newlines,
443 and commas separate descriptors.
444 .
445 Newlines and commas apply the descriptors following them
446 to a subsequent row of the table
447 (enabling column headings to be centered or emboldened
448 while the table entries for the data are not,
449 for instance).
450 .
451 We term the resulting group of column descriptors a
452 .I row definition.
453 .
454 Within a row definition,
455 separation between column descriptors
456 by spaces or tabs
457 is often optional;
458 only some modifiers,
459 described below,
460 make separation necessary.
461 .
462 .
463 .P
464 The classifier selects from one of several arrangements.
465 .
466 Some determine the positioning of table entries within a rectangular
467 cell:
468 centered,
469 left-aligned,
470 numeric
471 (aligned to a configurable decimal separator),
472 and so on.
473 .
474 Others perform special operations like drawing lines or spanning entries
475 from adjacent cells in the table.
476 .
477 Except for
478 .RB \[lq]\^ | \^\[rq],
479 any classifier can be followed by one or more
480 .I modifiers;
481 some of these accept an argument,
482 which in GNU
483 .I tbl \" GNU
484 can be parenthesized.
485 .\" AT&T tbl allowed parentheses only after 'w'.
486 .\" TODO: Accept parentheses after 'p' and 'v'.
487 .
488 Modifiers select fonts,
489 set the type size,
490 .\"define the column width,
491 .\"adjust inter-column spacing, \" slack text for window/orphan control
492 and perform other tasks described below.
493 .
494 .
495 .P
496 The format specification can occupy multiple input lines,
497 but must conclude with a dot
498 .RB \[lq] .\& \[rq]
499 followed by a newline.
500 .
501 Each row definition applies in turn to one row of the table.
502 .
503 .I tbl \" generic
504 applies the last row definition to rows of table data
505 in excess of the row definitions.
506 .
507 .
508 .P
509 For clarity in this document's examples,
510 we write classifiers in uppercase and modifiers in lowercase.
511 .
512 Thus,
513 .RB \[lq] CbCb,LR.\& \[rq]
514 defines two rows of two columns.
515 .
516 The first row's entries are centered and boldfaced;
517 the second and any further rows' first and second columns are left- and
518 right-aligned,
519 respectively.
520 .
521 Any rows of entries appended to the table data reuse the row definition
522 .RB \[lq] LR \[rq].
523 .
524 .
525 .br
526 .ne 3v
527 .P
528 The row definition with the most column descriptors determines the
529 number of columns in the table;
530 any row definition with fewer,
531 GNU
532 .I tbl \" GNU
533 implicitly extends on the right-hand side with
534 .B L
535 descriptors as many times as necessary to make the table rectangular.
536 .\" Heirloom Doctools tbl also does that; DWB tbl does not.
537 .
538 .
539 .br
540 .ne 5v
541 .\" ====================================================================
542 .SS "Column classifiers"
543 .\" ====================================================================
544 .
545 The
546 .BR L ,
547 .BR R ,
548 and
549 .B C
550 classifiers are the easiest to understand and use.
551 .
552 .
553 .TP
554 .BR A ,\~ a
555 Center longest entry in this column,
556 left-align remaining entries in the column with respect to the centered
557 entry,
558 then indent all entries by one en.
559 .
560 Such \[lq]alphabetic\[rq] entries
561 (hence the name of the classifier)
562 can be used in the same column as
563 .BR L -classified
564 entries,
565 as in
566 .RB \[lq] LL,AR.\& \[rq].
567 .
568 The
569 .B A
570 entries are often termed \[lq]sub-columns\[rq] due to their indentation.
571 .
572 .
573 .TP
574 .BR C ,\~ c
575 Center entry within the column.
576 .
577 .
578 .TP
579 .BR L ,\~ l
580 Left-align entry within the column.
581 .
582 .
583 .TP
584 .BR N ,\~ n
585 Numerically align entry in the column.
586 .
587 .I \%tbl
588 aligns columns of decimal numbers vertically at the units place.
589 .
590 If multiple decimal separators are adjacent to a digit,
591 it uses the rightmost one for vertical alignment.
592 .
593 If there is no decimal separator,
594 .I \%tbl
595 uses the rightmost digit for vertical alignment;
596 if no digits are present,
597 .I \%tbl
598 centers the entry within the column.
599 .
600 The
601 .I roff
602 dummy character
603 .B \[rs]&
604 in an entry marks the glyph preceding it
605 (if any)
606 as the units place;
607 if multiple instances occur in the data,
608 .I tbl \" generic
609 uses the leftmost for alignment.
610 .
611 .
612 .IP
613 If
614 .BR N -classified
615 entries share a column with
616 .B L
617 or
618 .BR R \~entries,
619 .I \%tbl
620 centers the widest
621 .BR N \~entry
622 with respect to the widest
623 .B L
624 or
625 .BR R \~entry,
626 preserving the alignment of
627 .BR N \~entries
628 with respect to each other.
629 .
630 .
631 .IP
632 Decimal separators in
633 .I \%eqn
634 equations
635 within
636 .BR N -classified
637 columns
638 can conflict with
639 .IR \%tbl 's
640 use of them for alignment.
641 .
642 Specify the
643 .B \%delim
644 region option to make
645 .I \%tbl
646 ignore the data within
647 .I eqn
648 delimiters.
649 .
650 .
651 .TP
652 .BR R ,\~ r
653 Right-align entry within the column.
654 .
655 .
656 .TP
657 .BR S ,\~ s
658 Span previous entry on the left into this column.
659 .
660 .
661 .TP
662 .B \[ha]
663 Span entry in the same column from the previous row into this row.
664 .
665 .
666 .TP
667 .BR _ ,\~ \-
668 Replace table entry with a horizontal rule.
669 .
670 .I \%tbl
671 expects an empty table entry to correspond to this classifier;
672 if data are found there,
673 it issues a diagnostic message.
674 .
675 If the entire row definition consists of these classifiers
676 (only one is necessary),
677 it is treated as a
678 .RB \[lq] _ \[rq]
679 occupying a row of table entries,
680 and no corresponding data are expected.
681 .
682 .
683 .TP
684 .B =
685 Replace table entry with a double horizontal rule.
686 .
687 .I \%tbl
688 expects an empty table entry to correspond to this classifier;
689 if data are found there,
690 it issues a diagnostic message.
691 .
692 If the entire row definition consists of these classifiers
693 (only one is necessary),
694 it is treated as a
695 .RB \[lq] = \[rq]
696 occupying a row of table entries,
697 and no corresponding data are expected.
698 .
699 .
700 .TP
701 .B |
702 Place a vertical rule (line) on the corresponding row of the table
703 (if two of these are adjacent,
704 a double vertical rule).
705 .
706 This classifier does not contribute to the column count and no table
707 entries correspond to it.
708 .
709 A
710 .B |
711 to the left of the first column descriptor or to the right of the last
712 one produces a vertical rule at the edge of the table;
713 these are redundant
714 (and ignored)
715 in boxed tables.
716 .
717 .
718 .P
719 To change the table format within a
720 .I \%tbl
721 region,
722 use the
723 .B .T&
724 token at the start of a line.
725 .
726 Follow it with a format specification and table data,
727 but
728 .I not
729 region options.
730 .
731 The quantity of columns in a format thus introduced cannot increase
732 relative to the previous format;
733 in that case,
734 you must end the table region and start another.
735 .
736 If that will not serve because the region uses box options or the
737 columns align in an undesirable manner,
738 you must design the initial table format specification to include the
739 maximum quantity of columns required,
740 and use the
741 .B S
742 horizontal spanning classifier where necessary to achieve the desired
743 columnar alignment.
744 .
745 .
746 .P
747 Spanning horizontally in the first column or vertically on the first row
748 is an error.
749 .
750 .I \%tbl
751 does not support non-rectangular span areas.
752 .
753 .
754 .\" ====================================================================
755 .SS "Column modifiers"
756 .\" ====================================================================
757 .
758 Any number of modifiers can follow a column classifier.
759 .
760 Modifier arguments,
761 where accepted,
762 are case-sensitive.
763 .
764 If you apply a given modifier to a classifier more than once,
765 or apply conflicting modifiers,
766 only the last occurrence has effect.
767 .
768 The
769 .RB modifier\~ x
770 is mutually exclusive with
771 .B e
772 .RB and\~ w ,
773 but
774 .B e
775 is not mutually exclusive
776 .RB with\~ w ;
777 if these are used in combination,
778 .BR x \~unsets
779 both
780 .B e
781 .RB and\~ w ,
782 while either
783 .B e
784 or
785 .B w
786 .RB overrides\~ x .
787 .
788 .
789 .br
790 .ne 4v \" Keep next two tagged paragraphs together.
791 .TP
792 .BR b ,\~ B
793 Typeset entry in boldface,
794 abbreviating
795 .BR f(B) .
796 .
797 .
798 .TP
799 .BR d ,\~ D
800 Align a vertically spanned table entry to the bottom
801 (\[lq]down\[rq]),
802 instead of the center,
803 of its range.
804 .
805 This is a GNU extension.
806 .
807 .
808 .TP
809 .BR e ,\~ E
810 Equalize the widths of columns with this modifier
811 to that of the widest.
812 .
813 This modifier sets the default line length used in a text block.
814 .
815 .
816 .TP
817 .BR f ,\~ F
818 Select the typeface for the table entry.
819 .
820 A font or style name
821 (one or two characters not starting with a digit),
822 font mounting position
823 (a single digit),
824 or a name or mounting position of any length in parentheses,
825 must follow.
826 .
827 The last form is a GNU extension.
828 .
829 (The parameter corresponds to that accepted by the
830 .I troff \" generic
831 .B ft
832 request.)
833 .
834 A one-character argument not in parentheses
835 must end the row description
836 or be separated by one or more spaces or tabs from what follows.
837 .
838 .
839 .TP
840 .BR i ,\~ I
841 Typeset entry in an oblique or italic face,
842 abbreviating
843 .BR f(I) .
844 .
845 .
846 .TP
847 .BR m ,\~ M
848 Call a
849 .I groff
850 macro before typesetting a text block
851 (see subsection \[lq]Text blocks\[rq] below).
852 .
853 This is a GNU extension.
854 .
855 A macro name of one or two characters,
856 or a name of any length in parentheses,
857 must follow.
858 .
859 A one-character macro name not in parentheses must be separated by one
860 or more spaces or tabs from what follows.
861 .
862 The named macro must be defined before the table region containing this
863 column modifier is encountered.
864 .
865 The macro should contain only simple
866 .I groff
867 requests to change text formatting,
868 like adjustment or hyphenation.
869 .
870 The macro is called
871 .I after
872 the column modifiers
873 .BR b ,
874 .BR f ,
875 .BR i ,
876 .BR p ,
877 and
878 .B v
879 take effect;
880 it can thus override other column modifiers.
881 .
882 .
883 .TP
884 .BR p ,\~ P
885 Set the type size.
886 .
887 An
888 .RI integer\~ n
889 with an optional leading sign must follow.
890 .
891 If unsigned,
892 the type size is set to
893 .IR n \~points.
894 .
895 Otherwise,
896 the type size is incremented or decremented per the sign by
897 .IR n \~points.
898 .
899 The use of a signed multi-digit number is a GNU extension.
900 .
901 (The parameter corresponds to that accepted by the
902 .I troff \" generic
903 .B ps
904 request.)
905 .
906 If a type size modifier is followed by a column separation modifier
907 (see below),
908 they must be separated by at least one space or tab.
909 .\" TODO: Allow parentheses so scaling units and fractional values can
910 .\" be used?
911 .
912 .
913 .TP
914 .BR t ,\~ T
915 Align a vertically spanned table entry to the top,
916 instead of the center,
917 of its range.
918 .
919 .
920 .TP
921 .BR u ,\~ U
922 Move the column up one half-line,
923 \[lq]staggering\[rq] the rows.
924 .
925 This is a Documenter's Workbench (DWB) 1.0 and Research Tenth Edition
926 Unix extension.
927 .
928 .
929 .TP
930 .BR v ,\~ V
931 Set the vertical spacing of a text block.
932 .
933 An
934 .RI integer\~ n
935 with an optional leading sign must follow.
936 .
937 If unsigned,
938 the vertical spacing is set to
939 .IR n\~ points.
940 .
941 Otherwise,
942 the vertical spacing is incremented or decremented per the sign by
943 .IR n\~ points.
944 .
945 The use of a signed multi-digit number is a GNU extension.
946 .
947 (This parameter corresponds to that accepted by the
948 .I troff \" generic
949 .B vs
950 request.)
951 .
952 If a vertical spacing modifier is followed by a column separation
953 modifier
954 (see below),
955 they must be separated by at least one space or tab.
956 .\" TODO: Allow parentheses so scaling units and fractional values can
957 .\" be used?
958 .
959 .
960 .TP
961 .BR w ,\~ W
962 Set the column's minimum width.
963 .
964 A number,
965 either a unitless integer,
966 or a
967 .I roff
968 horizontal measurement in parentheses,
969 must follow.
970 .
971 Parentheses are required if the width is to be followed immediately by
972 an explicit column separation
973 (alternatively,
974 follow the width with one or more spaces or tabs).
975 .
976 If no unit is specified,
977 ens are assumed.
978 .
979 This modifier sets the default line length used in a text block.
980 .
981 .
982 .TP
983 .BR x ,\~ X
984 Expand the column.
985 .
986 After computing the column widths,
987 distribute any remaining line length evenly over all columns bearing
988 this modifier.
989 .
990 This is a Documenter's Workbench (DWB) 3.3 extension.
991 .
992 Applying the
993 .BR x \~modifier
994 to more than one column is a GNU extension.
995 .
996 This modifier sets the default line length used in a text block.
997 .
998 .
999 .TP
1000 .BR z ,\~ Z
1001 Ignore the table entries corresponding to this column for width
1002 calculation purposes;
1003 that is,
1004 compute the column's width using only the information in its descriptor.
1005 .
1006 This is a Documenter's Workbench (DWB) 1.0 and Research Tenth Edition
1007 Unix extension.
1008 .
1009 .
1010 .TP
1011 .I n
1012 A numeric suffix on a column descriptor sets the separation distance
1013 (in ens)
1014 from the succeeding column;
1015 the default separation is
1016 .BR 3n .
1017 .
1018 This separation is
1019 proportionally multiplied if the
1020 .B expand
1021 region option is in effect;
1022 in the case of tables wider than the output line length,
1023 this separation might be zero.
1024 .
1025 A negative separation cannot be specified.
1026 .
1027 A separation amount after the last column in a row is nonsensical and
1028 provokes a diagnostic from
1029 .IR \%tbl .
1030 .
1031 .
1032 .\" ====================================================================
1033 .SS "Table data"
1034 .\" ====================================================================
1035 .
1036 Place table data on lines after the format specification.
1037 .
1038 Each text line corresponds to a table row,
1039 except that a backslash at the end of a line of table data continues an
1040 entry on the next input line.
1041 .
1042 (Text blocks,
1043 discussed below,
1044 also spread table entries across multiple input lines.)
1045 .
1046 Table entries within a row are separated in the input by a tab character
1047 by default;
1048 see the
1049 .B tab
1050 region option above.
1051 .
1052 Excess entries in a row of table data
1053 (those that have no corresponding column descriptor,
1054 not even an implicit one arising from rectangularization of the table),
1055 .I \%tbl
1056 discards with a diagnostic message.
1057 .
1058 .I \%tbl
1059 passes
1060 .I roff
1061 control lines through unaltered to its output.
1062 .
1063 If you wish to visibly mark an empty table entry in the document source,
1064 populate it with the
1065 .B \[rs]&
1066 .I roff
1067 dummy character.
1068 .
1069 The table data are interrupted by a line consisting of the
1070 .B .T&
1071 input token,
1072 and conclude with the line
1073 .BR .TE .
1074 .
1075 .
1076 .P
1077 Ordinarily,
1078 a table entry is typeset rigidly.
1079 .
1080 It is not filled,
1081 broken,
1082 hyphenated,
1083 adjusted,
1084 or populated with supplemental inter-sentence space.
1085 .
1086 .I \%tbl
1087 instructs the formatter to measure each table entry as it occurs in the
1088 input,
1089 updating the width required by its corresponding column.
1090 .
1091 If the
1092 .B z
1093 modifier applies to the entry,
1094 this measurement is ignored;
1095 if
1096 .B w
1097 applies and its argument is larger than this width,
1098 that argument is used instead.
1099 .
1100 In contrast to conventional
1101 .I roff
1102 input
1103 (within a paragraph,
1104 say),
1105 changes to text formatting,
1106 such as font selection or vertical spacing,
1107 do not persist between entries.
1108 .
1109 .
1110 .P
1111 .I \%tbl
1112 interprets several forms of table entry specially.
1113 .
1114 .
1115 .IP \[bu] 3n
1116 If a table row contains only an underscore or equals sign
1117 .RB ( _
1118 or
1119 .BR = ),
1120 .I \%tbl
1121 draws a a single or double horizontal rule (line),
1122 respectively,
1123 across the table at that point.
1124 .
1125 .
1126 .IP \[bu]
1127 If a table entry contains only
1128 .B _
1129 or
1130 .B =
1131 on an otherwise populated row,
1132 .I \%tbl
1133 populates its cell with a single or double horizontal rule,
1134 respectively,
1135 that joins its
1136 neighbors.
1137 .
1138 .
1139 .IP \[bu]
1140 If a table entry contains only
1141 .B \[rs]_
1142 or
1143 .B \[rs]=
1144 on an otherwise populated row,
1145 .I \%tbl
1146 populates its cell with a single or double horizontal rule,
1147 respectively,
1148 that does
1149 .I not
1150 (quite) join its neighbors.
1151 .
1152 .
1153 .IP \[bu]
1154 If a table entry contains only
1155 .BI \[rs]R x\c
1156 ,
1157 where
1158 .IR x \~is
1159 any
1160 .I roff
1161 ordinary,
1162 special,
1163 or indexed character,
1164 .I \%tbl
1165 populates its cell with enough repetitions of the glyph corresponding
1166 .RI to\~ x
1167 to fill the column
1168 without joining its neighbors.
1169 .\" TODO: Bad things happen if there's garbage in the entry after 'x',
1170 .\" which can be a *roff special character escape sequence, so
1171 .\" validation is not trivial.
1172 .
1173 .
1174 .IP \[bu]
1175 On any row but the first,
1176 a table entry of
1177 .B \[rs]\[ha]
1178 causes the entry above it to span down into the current one.
1179 .
1180 .
1181 .P
1182 On occasion,
1183 these special tokens may be required as literal table data.
1184 .
1185 To use either
1186 .B _
1187 or
1188 .B =
1189 literally and alone in an entry,
1190 prefix or suffix it with the
1191 .I roff
1192 dummy character
1193 .BR \[rs]& .
1194 .
1195 To express
1196 .BR \[rs]_ ,
1197 .BR \[rs]= ,
1198 or
1199 .BR \[rs]R ,
1200 use a
1201 .I roff
1202 escape sequence to interpolate the backslash
1203 .RB ( \[rs]e
1204 or
1205 .BR \[rs][rs] ).
1206 .
1207 A reliable way to emplace the
1208 .B \[rs]\[ha]
1209 glyph sequence within a table entry is to use a pair of
1210 .I groff
1211 special character escape sequences
1212 .RB ( \[rs][rs]\[rs][ha] ).
1213 .
1214 .
1215 .P
1216 Rows of table entries can be interleaved with
1217 .I groff
1218 control lines;
1219 these do not count as table data.
1220 .
1221 On such lines the default control character
1222 .RB ( .\& )
1223 must be used
1224 (and not changed);
1225 the no-break control character is not recognized.
1226 .
1227 To start the first table entry in a row with a dot,
1228 precede it with the
1229 .I roff
1230 dummy character
1231 .BR \[rs]& .
1232 .
1233 .
1234 .\" ====================================================================
1235 .SS "Text blocks"
1236 .\" ====================================================================
1237 .
1238 An ordinary table entry's contents can make a column,
1239 and therefore the table,
1240 too wide;
1241 the table then exceeds the line length of the page,
1242 and becomes ugly or is exposed to truncation by the output device.
1243 .
1244 When a table entry requires more conventional typesetting,
1245 breaking across more than one output line
1246 (and thereby increasing the height of its row),
1247 it can be placed within a
1248 .I text block.
1249 .
1250 .
1251 .P
1252 .I \%tbl
1253 interprets a table entry of
1254 .RB \[lq] T{ \[rq]
1255 at the end of an input line specially,
1256 as a token starting a text block.
1257 .
1258 Similarly,
1259 an entry
1260 .RB \[lq] T} \[rq]
1261 at the start of an input line ends a text block.
1262 .
1263 Text block tokens can share an input line with other table data
1264 (preceding
1265 .B T{
1266 and following
1267 .BR T} ).
1268 .
1269 Input lines between these tokens are formatted in a diversion by
1270 .IR troff . \" generic
1271 .
1272 Text blocks cannot be nested.
1273 .
1274 Multiple text blocks can occur in a table row.
1275 .
1276 .
1277 .P
1278 Text blocks are formatted as was the text prior to the table,
1279 modified by applicable column descriptors.
1280 .
1281 Specifically,
1282 the classifiers
1283 .BR A ,
1284 .BR C ,
1285 .BR L ,
1286 .BR N ,
1287 .BR R ,
1288 and
1289 .B S
1290 determine a text block's
1291 .I alignment
1292 within its cell,
1293 but not its
1294 .I adjustment.
1295 .
1296 Add
1297 .B na
1298 or
1299 .B ad
1300 requests to the beginning of a text block to alter its adjustment
1301 distinctly from other text in the document.
1302 .
1303 As with other table entries,
1304 when a text block ends,
1305 any alterations to formatting parameters are discarded.
1306 .
1307 They do not affect subsequent table entries,
1308 not even other text blocks.
1309 .
1310 .
1311 .P
1312 .ne 2v
1313 If
1314 .B w
1315 or
1316 .B x
1317 modifiers are not specified for
1318 .I all
1319 columns of a text block's span,
1320 the default length of the text block
1321 (more precisely,
1322 the line length used to process the text block's diversion)
1323 is computed as
1324 .IR L \[tmu] C /( N +1),
1325 .\" ...and rounded to the horizontal motion quantum of the output device
1326 where
1327 .I L
1328 is the current line length,
1329 .I C
1330 the number of columns spanned by the text block,
1331 and
1332 .I N
1333 the number of columns in the table.
1334 .
1335 If necessary,
1336 you can also control a text block's width by including an
1337 .B ll
1338 (line length)
1339 request in it prior to any text to be formatted.
1340 .
1341 Because
1342 .I \%tbl
1343 uses a diversion to format the text block,
1344 its height and width are subsequently available
1345 in the
1346 .I troff \" generic
1347 registers
1348 .B dn
1349 and
1350 .BR dl ,
1351 respectively.
1352 .
1353 .
1354 .\" ====================================================================
1355 .SS \f[I]roff\f[] interface
1356 .\" ====================================================================
1357 .
1358 The register
1359 .B TW
1360 stores the width of the table region in basic units;
1361 it can't be used within the region itself,
1362 but is defined before the
1363 .B .TE
1364 token is output so that a
1365 .I troff \" generic
1366 macro named
1367 .B TE
1368 can make use of it.
1369 .
1370 .RB \[lq] T.\& \[rq]
1371 is a Boolean-valued register indicating whether the bottom of the table
1372 is being processed.
1373 .
1374 A
1375 .B #T
1376 register
1377 is used internally.
1378 .\" marks the top of the table.
1379 .\" XXX: That claim, from Lesk 1979, is not true of DWB tbl/nroff nor
1380 .\" Heirloom Doctools tbl/nroff. GNU tbl appears to use it to mark the
1381 .\" top of a diverted table row when it's too tall to fit before the
1382 .\" next vertical trap.
1383 .
1384 Avoid using these names for any other purpose.
1385 .
1386 .
1387 .P
1388 .I \%tbl
1389 also defines a macro
1390 .B T#
1391 to produce the bottom and side lines of a boxed table.
1392 .
1393 While
1394 .I \%tbl
1395 itself arranges for the output to include a call of this macro at the
1396 end of such a table,
1397 it can also be used by macro packages to create boxes for multi-page
1398 tables by calling it from a page footer macro that is itself called by
1399 a trap planted near the bottom of the page.
1400 .
1401 See section \[lq]Limitations\[rq] below for more on multi-page tables.
1402 .
1403 .
1404 .P
1405 GNU
1406 .I tbl \" GNU
1407 .\" AT&T tbl used all kinds of registers; many began with "3".
1408 internally employs register,
1409 string,
1410 macro,
1411 and diversion names beginning with the
1412 .RB numeral\~ 3 .
1413 .
1414 A document to be preprocessed with GNU
1415 .I tbl \" GNU
1416 should not use any such identifiers.
1417 .\" XXX: Why are they not named starting with "gtbl*" or something? GNU
1418 .\" tbl turns AT&T troff compatibility mode off anyway.
1419 .
1420 .
1421 .\" ====================================================================
1422 .SS "Interaction with \f[I]\%eqn\f[]"
1423 .\" ====================================================================
1424 .
1425 Process a document with
1426 .I \%tbl
1427 before
1428 .MR \%eqn 1 .
1429 .
1430 (\c
1431 .MR groff 1
1432 automatically arranges preprocessors in the correct order.)
1433 .
1434 Don't call the
1435 .B EQ
1436 and
1437 .B EN
1438 macros within tables;
1439 instead,
1440 set up delimiters in your
1441 .I eqn \" generic
1442 input and use the
1443 .B \%delim
1444 region option so that
1445 .I \%tbl
1446 will recognize them.
1447 .
1448 .
1449 .br
1450 .ne 5v \" Keep enough space for heading, intro sentence, and first item.
1451 .\" ====================================================================
1452 .SS "GNU \f[I]tbl\f[] enhancements"
1453 .\" ====================================================================
1454 .
1455 In addition to extensions noted above,
1456 GNU
1457 .I tbl \" GNU
1458 removes constraints endured by users of AT&T
1459 .IR tbl .\" AT&T
1460 .
1461 .
1462 .IP \[bu] 3n
1463 Region options can be specified in any lettercase.
1464 .
1465 .
1466 .IP \[bu]
1467 There is no limit on the number of columns in a table,
1468 regardless of their classification,
1469 nor any limit on the number of text blocks.
1470 .
1471 .
1472 .IP \[bu]
1473 GNU
1474 .I tbl \" GNU
1475 considers all table rows when computing column widths,
1476 not just those occurring in the first 200 input lines of a region.
1477 .
1478 Similarly,
1479 it recognizes table continuation tokens
1480 .RB ( .T& )
1481 outside a region's first 200 input lines.
1482 .
1483 .
1484 .IP \[bu]
1485 Numeric and alphabetic entries may appear in the same column.
1486 .
1487 .
1488 .IP \[bu]
1489 Numeric and alphabetic entries may span horizontally.
1490 .
1491 .
1492 .\" ====================================================================
1493 .SS "Using GNU \f[I]tbl\f[] within macros"
1494 .\" ====================================================================
1495 .
1496 You can embed a table region inside a macro definition.
1497 .
1498 However,
1499 since
1500 .I \%tbl
1501 writes its own macro definitions at the beginning of each table region,
1502 it is necessary to call end macros instead of ending macro definitions
1503 with
1504 .RB \[lq] ..\& \[rq].
1505 .\" XXX: Why don't we fix that by ending all of tbl's own macro
1506 .\" definitions with a call to a macro in its own reserved name space?
1507 .
1508 Additionally,
1509 the escape character must be disabled. \" XXX: Why?
1510 .
1511 .
1512 .P
1513 Not all
1514 .I \%tbl
1515 features can be exercised from such macros because
1516 .I \%tbl
1517 is a
1518 .I roff
1519 preprocessor:
1520 it sees the input earlier than
1521 .I \%troff
1522 does.
1523 .
1524 For example,
1525 vertically aligning decimal separators fails if the numbers containing
1526 them occur as macro or string parameters;
1527 the alignment is performed by
1528 .I \%tbl
1529 itself,
1530 which sees only
1531 .BR \[rs]$1 ,
1532 .BR \[rs]$2 ,
1533 and so on,
1534 and therefore can't recognize a decimal separator that appears only
1535 later when
1536 .I \%troff
1537 interpolates a macro or string definition.
1538 .
1539 .
1540 .\" XXX: The following is a general caveat about preprocessors; move it.
1541 .P
1542 Using
1543 .I \%tbl
1544 macros within conditional input
1545 (that is,
1546 contingent upon an
1547 .BR if ,
1548 .BR ie ,
1549 .BR el ,
1550 or
1551 .B while
1552 request)
1553 can result in misleading line numbers in subsequent diagnostics.
1554 .
1555 .I \%tbl
1556 unconditionally injects its output into the source document,
1557 but the conditional branch containing it may not be taken,
1558 and if it is not,
1559 the
1560 .B lf
1561 requests that
1562 .I \%tbl
1563 injects to restore the source line number cannot take effect.
1564 .
1565 Consider copying the input line counter register
1566 .RB \[lq] c.\& \[rq]
1567 and restoring its value at a convenient location after applicable
1568 arithmetic.
1569 .
1570 .
1571 .br
1572 .ne 5v
1573 .\" ====================================================================
1574 .SH Options
1575 .\" ====================================================================
1576 .
1577 .B \-\-help
1578 displays a usage message,
1579 while
1580 .B \-v
1581 and
1582 .B \%\-\-version
1583 show version information;
1584 all exit afterward.
1585 .
1586 .
1587 .TP
1588 .B \-C
1589 Enable AT&T compatibility mode:
1590 recognize
1591 .B .TS
1592 and
1593 .B .TE
1594 even when followed by a character other than space or newline,
1595 and
1596 interpret the copy-mode leader escape sequence
1597 .B \[rs]a
1598 as a leader character.
1599 .
1600 .
1601 .\" ====================================================================
1602 .SH "Exit status"
1603 .\" ====================================================================
1604 .
1605 .I \%tbl
1606 exits with
1607 .RB status\~ 0
1608 on successful operation,
1609 .RB status\~ 2
1610 if the program cannot interpret its command-line arguments,
1611 and
1612 .RB status\~ 1
1613 if it encounters an error during operation.
1614 .
1615 .
1616 .\" ====================================================================
1617 .SH Limitations
1618 .\" ====================================================================
1619 .
1620 Within a
1621 .I tbl \" generic
1622 region
1623 (except in text blocks or on
1624 .I roff
1625 control lines),
1626 avoid escape sequences that read the rest of the input line,
1627 as
1628 .B \[rs]\[dq]
1629 and
1630 .B \[rs]!\&
1631 do.
1632 .
1633 .
1634 .P
1635 Multi-page tables,
1636 if boxed and/or if you want their column headings repeated after page
1637 breaks,
1638 require support at the time the document is formatted.
1639 .
1640 A convention for such support has arisen in macro packages such as
1641 .IR ms ,
1642 .IR mm ,
1643 and
1644 .IR me .
1645 .
1646 To use it,
1647 follow the
1648 .B .TS
1649 token with a space and then
1650 .RB \[lq] H \[rq];
1651 this will be interpreted by the formatter
1652 as a
1653 .B TS
1654 macro call with an
1655 .B H
1656 argument.
1657 .
1658 Then,
1659 within the table data,
1660 call the
1661 .B TH
1662 macro;
1663 this informs the macro package where the headings end.
1664 .
1665 If your table has no such heading rows,
1666 or you do not desire their repetition,
1667 call
1668 .B TH
1669 immediately after the table format specification.
1670 .
1671 If a multi-page table is boxed or has repeating column headings,
1672 do not enclose it with keep/release macros,
1673 or divert it in any other way.
1674 .
1675 Further,
1676 the
1677 .B bp
1678 request will not cause a page break in a
1679 .RB \[lq] "TS H" \[rq]
1680 table.
1681 .
1682 Define a macro to wrap
1683 .BR bp :
1684 invoke it normally if there is no current diversion.
1685 .
1686 Otherwise,
1687 pass the macro call to the enclosing diversion using the transparent
1688 line escape sequence
1689 .BR \[rs]!\& ;
1690 this will \[lq]bubble up\[rq] the page break to the output device.
1691 .
1692 See section \[lq]Examples\[rq] below for a demonstration.
1693 .
1694 .
1695 .P
1696 .MR grotty 1
1697 does not support
1698 double horizontal rules;
1699 it uses single rules instead.
1700 .
1701 It also ignores half-line motions,
1702 so the
1703 .B u
1704 column modifier has no effect.
1705 .
1706 On terminal devices
1707 .RI (\[lq] nroff\~ mode\[rq]),
1708 horizontal rules and box borders occupy a full vee of space;
1709 .B doublebox
1710 doubles that for borders.
1711 .
1712 Tables using these features thus require more vertical space in
1713 .I nroff
1714 mode than in
1715 .I troff
1716 mode:
1717 write
1718 .B ne
1719 requests accordingly.
1720 .
1721 Vertical rules between columns are drawn in the space between columns in
1722 .I nroff
1723 mode;
1724 using double vertical rules and/or reducing the column separation below
1725 the default can make them ugly or overstrike them with table data.
1726 .
1727 .
1728 .P
1729 A text block within a table must be able to fit on one page.
1730 .
1731 .
1732 .P
1733 Using
1734 .B \[rs]a
1735 to put leaders in table entries does not work
1736 in GNU
1737 .IR tbl , \" GNU
1738 except in compatibility mode.
1739 .
1740 This is correct behavior:
1741 .B \[rs]a
1742 is an
1743 .I uninterpreted
1744 leader.
1745 .
1746 You can still use the
1747 .I roff
1748 leader character (Control+A) or define a string to use
1749 .B \[rs]a
1750 as it was designed:
1751 to be interpreted only in copy mode.
1752 .
1753 .
1754 .RS
1755 .P
1756 .EX
1757 \&.ds a \[rs]a
1758 \&.TS
1759 \&box center tab(;);
1760 \&Lw(2i)0 L.
1761 \&Population\[rs]*a;6,327,119
1762 \&.TE
1763 .EE
1764 .RE
1765 .
1766 .
1767 .\" We use a real leader to avoid defining a string in a man page.
1768 .P
1769 .TS
1770 box center tab(;);
1771 Lw(2i)0 L.
1772 Population;6,327,119
1773 .TE
1774 .
1775 .
1776 .P
1777 A leading or trailing
1778 .RB \[lq] | \[rq]
1779 in a format specification,
1780 as in
1781 .RB \[lq] |LCR|.\& \[rq],
1782 produces an en space between the rules and the content of adjacent
1783 columns.
1784 .
1785 If such space is undesired
1786 (the rule should abut the content),
1787 you can introduce \[lq]dummy\[rq] columns with zero separation and empty
1788 corresponding table entries before and/or after.
1789 .
1790 .
1791 .RS
1792 .P
1793 .EX
1794 \&.TS
1795 \&center tab(#);
1796 \&R0|L C R0|L.
1797 _
1798 \&#levulose#glucose#dextrose#
1799 _
1800 \&.TE
1801 .EE
1802 .RE
1803 .
1804 .
1805 .br
1806 .ne 2v
1807 .P
1808 These dummy columns have zero width and are therefore invisible;
1809 unfortunately they usually don't work as intended on terminal devices.
1810 .
1811 .
1812 .if t \{\
1813 .TS
1814 center tab(#);
1815 R0|L C R0|L.
1816 _
1817 #levulose#glucose#dextrose#
1818 _
1819 .TE
1820 .\}
1821 .
1822 .
1823 .br
1824 .ne 3v
1825 .\" ====================================================================
1826 .SH Examples
1827 .\" ====================================================================
1828 .
1829 .if t \{\
1830 . \" Unstrand line. What sins we commit for attractive page layout...
1831 . nr old-PD \n[PD]
1832 . nr PD 0.35v
1833 .\}
1834 It can be easier to acquire the language of
1835 .I tbl \" generic
1836 through examples than formal description,
1837 especially at first.
1838 .
1839 .
1840 .\" Note: This example is nearly at the column limit (78n) for nroff
1841 .\" output. Recast with care.
1842 .RS
1843 .P
1844 .\" More sinning to fit the examples on 1 U.S. letter page.
1845 .if t \{\
1846 . ps 9
1847 . vs 11
1848 .\}
1849 .EX
1850 \&.TS
1851 box center tab(#);
1852 Cb Cb
1853 L L.
1854 Ability#Application
1855 Strength#crushes a tomato
1856 Dexterity#dodges a thrown tomato
1857 Constitution#eats a month-old tomato without becoming ill
1858 Intelligence#knows that a tomato is a fruit
1859 Wisdom#chooses \[rs]f[I]not\[rs]f[] to put tomato in a fruit salad
1860 Charisma#sells tomato-based fruit salads to hypercarnivores
1861 \&.TE
1862 .EE
1863 .RE
1864 .if t \{\
1865 . ps
1866 . vs
1867 .\}
1868 .
1869 .
1870 .P
1871 .TS
1872 box center tab(#);
1873 Cb Cb
1874 L L.
1875 Ability#Application
1876 Strength#crushes a tomato
1877 Dexterity#dodges a thrown tomato
1878 Constitution#eats a month-old tomato without becoming ill
1879 Intelligence#knows that a tomato is a fruit
1880 Wisdom#chooses \f[I]not\f[] to put tomato in a fruit salad
1881 Charisma#sells tomato-based fruit salads to hypercarnivores
1882 .TE
1883 .
1884 .
1885 .P
1886 The
1887 .B A
1888 and
1889 .B N
1890 column classifiers can be easier to grasp in visual rendering than in
1891 description.
1892 .
1893 .
1894 .RS
1895 .P
1896 .\" More sinning to fit the examples on 1 U.S. letter page.
1897 .if t \{\
1898 . ps 9
1899 . vs 11
1900 .\}
1901 .EX
1902 \&.TS
1903 center tab(;);
1904 CbS,LN,AN.
1905 Daily energy intake (in MJ)
1906 Macronutrients
1907 \&.\[rs]" assume 3 significant figures of precision
1908 Carbohydrates;4.5
1909 Fats;2.25
1910 Protein;3
1911 \&.T&
1912 LN,AN.
1913 Mineral
1914 Pu\-239;14.6
1915 _
1916 \&.T&
1917 LN.
1918 Total;\[rs][ti]24.4
1919 \&.TE
1920 .EE
1921 .RE
1922 .if t \{\
1923 . ps
1924 . vs
1925 .\}
1926 .
1927 .
1928 .RS
1929 .P
1930 .TS
1931 center tab(;);
1932 CbS,LN,AN.
1933 Daily energy intake (in MJ)
1934 .\" assume 3 significant figures of precision
1935 Macronutrients
1936 Carbohydrates;4.5
1937 Fats;2.25
1938 Protein;3
1939 .T&
1940 LN,AN.
1941 Mineral
1942 Pu-239;14.6
1943 _
1944 .T&
1945 LN.
1946 Total;\[ti]24.4
1947 .TE
1948 .RE
1949 .if t \{\
1950 . \" Undo kludge.
1951 . nr PD \n[old-PD]u
1952 . rr old-PD
1953 .\}
1954 .
1955 .
1956 .br
1957 .ne 12v
1958 .P
1959 Next,
1960 we'll lightly adapt a compact presentation of spanning,
1961 vertical alignment,
1962 and zero-width column modifiers from the
1963 .I mandoc
1964 reference for its
1965 .I tbl \" generic
1966 interpreter.
1967 .
1968 It rewards close study.
1969 .
1970 .
1971 .RS
1972 .P
1973 .EX
1974 \&.TS
1975 box center tab(:);
1976 Lz S | Rt
1977 Ld| Cb| \[ha]
1978 \[ha] | Rz S.
1979 left:r
1980 l:center:
1981 :right
1982 \&.TE
1983 .EE
1984 .RE
1985 .
1986 .
1987 .RS
1988 .P
1989 .TS
1990 box center tab(:);
1991 Lz S | Rt
1992 Ld| Cb| ^
1993 ^ | Rz S.
1994 left:r
1995 l:center:
1996 :right
1997 .TE
1998 .RE
1999 .
2000 .
2001 .P
2002 .ne 2v
2003 Row staggering is not visually achievable on terminal devices,
2004 but a table using it can remain comprehensible nonetheless.
2005 .
2006 .
2007 .RS
2008 .P
2009 .EX
2010 \&.TS
2011 center tab(|);
2012 Cf(BI) Cf(BI) Cf(B), C C Cu.
2013 n|n\[rs]f[B]\[rs][tmu]\[rs]f[]n|difference
2014 1|1
2015 2|4|3
2016 3|9|5
2017 4|16|7
2018 5|25|9
2019 6|36|11
2020 \&.TE
2021 .EE
2022 .RE
2023 .
2024 .
2025 .RS
2026 .P
2027 .TS
2028 center tab(|);
2029 Cf(BI) Cf(BI) Cf(B), C C Cu.
2030 n|n\f[B]\[tmu]\f[]n|difference
2031 1|1
2032 2|4|3
2033 3|9|5
2034 4|16|7
2035 5|25|9
2036 6|36|11
2037 .TE
2038 .RE
2039 .
2040 .
2041 .P
2042 Some
2043 .I \%tbl
2044 features cannot be illustrated in the limited environment of a portable
2045 man page.
2046 .
2047 .
2048 .\" TODO: Find a better example than this.
2049 .\".P
2050 .\"As noted above,
2051 .\"we can embed a table region in a
2052 .\".I groff
2053 .\"macro definition.
2054 .\".
2055 .\".IR \%tbl ,
2056 .\"however,
2057 .\"cannot know what will result from any macro argument interpolations,
2058 .\"so we might confine such interpolations to one column of the table and
2059 .\"apply the
2060 .\".B x
2061 .\"modifier to it.
2062 .\".
2063 .\".
2064 .\".RS
2065 .\".P
2066 .\".EX
2067 .\"\&.de END
2068 .\"\&..
2069 .\"\&.eo
2070 .\"\&.de MYTABLE END
2071 .\"\&.TS
2072 .\"\&allbox tab(;);
2073 .\"\&C Lx.
2074 .\"\&This is table \[rs]$1.;\[rs]$2
2075 .\"\&.TE
2076 .\"\&.END
2077 .\"\&.ec
2078 .\"\&.MYTABLE 1 alpha
2079 .\"\&.MYTABLE 2 beta
2080 .\"\&.MYTABLE 3 "gamma delta"
2081 .\".EE
2082 .\".RE
2083 .\"
2084 .\"
2085 .P
2086 We can define a macro outside of a
2087 .I tbl \" generic
2088 region that we can call from within it to cause a page break inside a
2089 multi-page boxed table.
2090 .
2091 You can choose a different name;
2092 be sure to change both occurrences of \[lq]BP\[rq].
2093 .
2094 .
2095 .RS
2096 .P
2097 .ne 4v
2098 .EX
2099 \&.de BP
2100 \&.\& ie \[aq]\[rs]\[rs]n(.z\[aq]\[aq] \&.bp \[rs]\[rs]$1
2101 \&.\& el \[rs]!.BP \[rs]\[rs]$1
2102 \&..
2103 .EE
2104 .RE
2105 .
2106 .
2107 .\" ====================================================================
2108 .SH "See also"
2109 .\" ====================================================================
2110 .
2111 \[lq]Tbl\[em]A Program to Format Tables\[rq],
2112 by M.\& E.\& Lesk,
2113 1976
2114 (revised 16 January 1979),
2115 AT&T Bell Laboratories Computing Science Technical Report No.\& 49.
2116 .
2117 .
2118 .P
2119 The spanning example above was taken from
2120 .UR https://man.openbsd.org/tbl.7
2121 .IR mandoc 's
2122 man page for its
2123 .I tbl \" mandoc
2124 implementation
2125 .UE .
2126 .
2127 .
2128 .P
2129 .MR groff 1 ,
2130 .MR \%troff 1
2131 .
2132 .
2133 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
2134 .cp \n[*groff_tbl_1_man_C]
2135 .do rr *groff_tbl_1_man_C
2136 .
2137 .
2138 .\" Local Variables:
2139 .\" fill-column: 72
2140 .\" mode: nroff
2141 .\" End:
2142 .\" vim: set filetype=groff textwidth=72: