Debian Codegraph @

upstream/debian-trixie/man7/groff_hdtbl.7

raw
1 .TH groff_hdtbl 7 "3 June 2025" "groff 1.23.0"
2 .SH Name
3 groff_hdtbl \- Heidelberger table macros for GNU
4 .I roff
5 .
6 .
7 .\" ====================================================================
8 .\" Legal Terms
9 .\" ====================================================================
10 .\"
11 .\" Copyright (C) 2005-2020 Free Software Foundation, Inc.
12 .\"
13 .\" This file is part of groff, the GNU roff type-setting system.
14 .\"
15 .\" Permission is granted to copy, distribute and/or modify this
16 .\" document under the terms of the GNU Free Documentation License,
17 .\" Version 1.3 or any later version published by the Free Software
18 .\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
19 .\" and with no Back-Cover Texts.
20 .\"
21 .\" A copy of the Free Documentation License is included as a file
22 .\" called FDL in the main directory of the groff source package.
23 .\"
24 .\" A copy of the GNU Free Documentation License is also available in this
25 .\" Debian package as /usr/share/doc/groff/copyright.
26 .
27 .
28 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
29 .do nr *groff_groff_hdtbl_7_man_C \n[.cp]
30 .cp 0
31 .
32 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
33 .nr do-fallback 0
34 .if !\n(.f .nr do-fallback 1 \" mandoc
35 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
36 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
37 .if \n[do-fallback] \{\
38 . de MR
39 . ie \\n(.$=1 \
40 . I \%\\$1
41 . el \
42 . IR \%\\$1 (\\$2)\\$3
43 . .
44 .\}
45 .rr do-fallback
46 .
47 .
48 .ig
49 Some simple formatting macros. Note that we use '.ig' here and not a
50 comment to make 'mandb' 2.4.1 (and probably more recent versions also)
51 happy; otherwise the '.char' lines and the stuff which follows is
52 included in the 'whatis' database.
53 ..
54 .
55 .
56 .char \[lB] \F[\n[.fam]]\f[R][
57 .char \[rB] \F[\n[.fam]]\f[R]]
58 .
59 .char \[or] \F[\n[.fam]]\f[R]\||\|
60 .char \[ell] \F[\n[.fam]]\f[R].\|.\|.
61 .
62 .char \[oq] \F[\n[.fam]]\f[R]\[oq]
63 .char \[cq] \F[\n[.fam]]\f[R]\[cq]
64 .
65 .
66 .ie F CR \{\
67 .
68 . \" We have to solve the following problem. In this code
69 . \"
70 . \" foo
71 . \" .CR bar
72 . \" foo
73 . \"
74 . \" the space immediately after 'bar' should not be taken from the 'C'
75 . \" family. At the same time, this
76 . \"
77 . \" foo
78 . \" .CR bar\c
79 . \" foo
80 . \"
81 . \" should work also. To fulfill both constraints we emit the
82 . \" family changing commands both as escapes and macro calls.
83 .
84 . de make-C-macro
85 . de C\\$1
86 . ds old-fam \\\\n[.fam]
87 . fam C
88 . \\$2 \&\\\\$*\F[]\F[\\\\*[old-fam]]
89 . fam
90 . rm old-fam
91 \\..
92 . .
93 .
94 . make-C-macro R nop
95 . make-C-macro B B
96 . make-C-macro I I
97 .
98 . de make-C-macro
99 . de C\\$1
100 . ds old-fam \\\\n[.fam]
101 . fam C
102 . \\$1 \\\\$@ \F[]\F[\\\\*[old-fam]]
103 . fam
104 . rm old-fam
105 \\..
106 . .
107 .
108 . make-C-macro BI
109 . make-C-macro IB
110 . make-C-macro RI
111 . make-C-macro IR
112 . make-C-macro BR
113 . make-C-macro RB
114 .\}
115 .el \{\
116 . ftr CR R
117 . ftr CI I
118 . ftr CB B
119 . ftr CBI BI
120 .
121 . de CR
122 . nop \&\\$*
123 . .
124 . als CB B
125 . als CI I
126 .
127 . als CBI BI
128 . als CIB IB
129 . als CRI RI
130 . als CIR IR
131 . als CBR BR
132 . als CRB RB
133 .\}
134 .
135 .
136 .
137 .de XB
138 . B "\\$1"
139 . shift
140 . CR "\\$1\c"
141 . shift
142 . while \\n[.$] \{\
143 . nop ,
144 . CR "\\$1\c"
145 . shift
146 . \}
147 . br
148 ..
149 .
150 .
151 .de XAA
152 . TQ
153 . ie (\\n[.$] < 2) \
154 . CR \\$@
155 . el \
156 . CRI \\$@
157 ..
158 .
159 .
160 .de XDEF
161 . br
162 . B Default:
163 . if !\\n[.$] \
164 . return
165 . CRI "\\$1" "\\$2"
166 ..
167 .
168 .
169 .de XDEFR
170 . br
171 . B Default:
172 . CR "\[oq]\\$1\[cq]"
173 . nop (register
174 . CR "\[oq]\\$2\[cq]\c"
175 . nop ).
176 ..
177 .
178 .
179 .de XDEFS
180 . br
181 . B Default:
182 . CR "\[oq]\\$1\[cq]"
183 . nop (string
184 . CR "\[oq]\\$2\[cq]\c"
185 . nop ).
186 ..
187 .
188 .\" ====================================================================
189 .SH Description
190 .\" ====================================================================
191 .
192 The
193 .I hdtbl
194 macros consist of four base and three optional macros,
195 controlled by about twenty arguments.
196 .
197 The syntax is simple and similar to the HTML table model and nearly as
198 flexible:
199 you can write sequences of tokens
200 (macro calls with their arguments and content data),
201 separated by blanks and beginning with a macro call,
202 into the same line to get compact and cleanly arrranged input.
203 .
204 An advantage of
205 .I hdtbl
206 is that the tables are constructed without calling a preprocessor;
207 this means that
208 .MR groff 7 's
209 full macro capabilities are available.
210 .
211 On the other hand,
212 table processing with
213 .I hdtbl
214 is much slower than using the
215 .MR \%tbl 1
216 preprocessor.
217 .
218 A further advantage is that the HTML-like syntax of
219 .I hdtbl
220 will be easily converted to HTML;
221 this is not implemented yet.
222 .
223 .
224 .\" ====================================================================
225 .SH Usage
226 .\" ====================================================================
227 .
228 In this and the next section, we present examples to help users
229 understand the basic workflow of
230 .IR hdtbl .
231 .
232 First of all, you must load the
233 .I hdtbl.tmac
234 file.
235 .
236 As with nearly all other
237 .I groff
238 macro packages,
239 there are two possibilities to do so:
240 .
241 Either add the line
242 .
243 .
244 .PP
245 .RS
246 .EX
247 \&.mso hdtbl.tmac
248 .EE
249 .RE
250 .
251 .
252 .PP
253 to your
254 .I roff
255 file before using any macros of the
256 .I hdtbl
257 package, or add the option
258 .
259 .PP
260 .RS
261 .EX
262 \-m hdtbl
263 .EE
264 .RE
265 .
266 .
267 .PP
268 to the command line of groff (before the document file which contains
269 .I hdtbl
270 macros).
271 .
272 Then you can include on or more tables in your document, where each one
273 must be started and ended with the
274 .CR .TBL
275 and
276 .CR .ETB
277 macros, respectively.
278 .
279 .
280 .PP
281 In this man page,
282 we approximate the result of each example as terminal output to be as
283 generic as possible since
284 .I hdtbl
285 currently only supports the
286 .B ps
287 and
288 .B pdf
289 output drivers.
290 .
291 .
292 .PP
293 The simplest well-formed table consists of just single calls to the
294 four base table macros in the right order.
295 .
296 Here we construct a table with only one cell.
297 .
298 .
299 .PP
300 .RS
301 .EX
302 \&.TBL
303 \&.TR
304 \&.TD
305 .I contents of the table cell
306 \&.ETB
307 .EE
308 .RE
309 .
310 .
311 .PP
312 A terminal representation is
313 .
314 .
315 .PP
316 .if t .ne 3v
317 .RS
318 .EX
319 .tr -\-
320 +------------------------------------------------------+
321 .\" That's 27 spaces below.
322 .RI "| " contents-of-the-table-cell " |"
323 +------------------------------------------------------+
324 .tr --
325 .EE
326 .RE
327 .
328 .
329 .PP
330 Equivalent to the above is the following notation.
331 .
332 .
333 .PP
334 .RS
335 .EX
336 .RI ".TBL .TR .TD \[dq]" "contents of the table cell" "\[dq] .ETB"
337 .EE
338 .RE
339 .
340 .
341 .PP
342 By default, the formatted table is inserted into the surrounding text
343 at the place of its definition.
344 .
345 If the vertical space isn't sufficient, it is placed at the top of
346 the next page.
347 .
348 Tables can also be stored for later insertion.
349 .
350 .
351 .PP
352 Using
353 .CIR \[oq]row-number * column-number\[cq]
354 as the data for the table cells, a table with two rows and two columns
355 can be written as
356 .
357 .
358 .PP
359 .RS
360 .EX
361 \&.TBL cols=2
362 \&.\& TR .TD 1*1 .TD 1*2
363 \&.\& TR .TD 2*1 .TD 2*2
364 \&.ETB
365 .EE
366 .RE
367 .
368 .
369 .PP
370 A terminal representation is
371 .
372 .
373 .PP
374 .if t .ne 5v
375 .RS
376 .EX
377 .tr -\-
378 +--------------------------+---------------------------+
379 | 1*1 | 1*2 |
380 +--------------------------+---------------------------+
381 | 2*1 | 2*2 |
382 +--------------------------+---------------------------+
383 .tr --
384 .EE
385 .RE
386 .
387 .
388 .PP
389 Here we see a difference from HTML tables: The number of columns must be
390 explicitly specified using the
391 .CRI \[oq]cols= m\[cq]
392 argument (or indirectly via the
393 .CR \[oq]width\[cq]
394 argument, see below).
395 .
396 .
397 .PP
398 The contents of a table cell is arbitrary;
399 for example,
400 it can be another table,
401 without restriction to the nesting depth.
402 .
403 A given table layout can be either constructed with suitably nested
404 tables or with proper arguments to
405 .CR .TD
406 and
407 .CR .TH\c
408 , controlling column and row spanning.
409 .
410 Note, however, that this table
411 .
412 .
413 .PP
414 .RS
415 .EX
416 \&.TBL
417 \&.\& TR
418 \&.\& TD
419 \&.\& nop 1*1 1*2
420 \&.\& TR
421 \&.\& TD
422 \&.\& TBL cols=2 border=
423 \&.\& TR
424 \&.\& TD
425 \&.\& nop 2*1
426 \&.\& TD
427 \&.\& nop 2*2
428 \&.\& ETB
429 \&.ETB
430 .EE
431 .RE
432 .
433 .
434 .PP
435 and this table
436 .
437 .
438 .PP
439 .RS
440 .EX
441 \&.TBL cols=2
442 \&.\& TR
443 \&.\& TD colspan=2
444 \&.\& nop 1*1 1*2
445 \&.\& TR
446 \&.\& TD
447 \&.\& nop 2*1
448 \&.\& TD
449 \&.\& nop 2*2
450 \&.ETB
451 .EE
452 .RE
453 .
454 .
455 .PP
456 are similar but not identical (the use of
457 .CR .nop
458 is purely cosmetic to get proper indentation).
459 .
460 .
461 .PP
462 The first table looks like
463 .
464 .PP
465 .if t .ne 7v
466 .RS
467 .EX
468 .tr -\-
469 +------------------------------------------------------+
470 | 1*1 1*2 |
471 +------------------------------------------------------+
472 | |
473 | 2*1 2*2 |
474 | |
475 +------------------------------------------------------+
476 .tr --
477 .EE
478 .RE
479 .
480 .
481 .PP
482 and the second one like
483 .
484 .
485 .PP
486 .if t .ne 5v
487 .RS
488 .EX
489 .tr -\-
490 +------------------------------------------------------+
491 | 1*1 1*2 |
492 +---------------------------+--------------------------+
493 | 2*1 | 2*2 |
494 +---------------------------+--------------------------+
495 .tr --
496 .EE
497 .RE
498 .
499 .
500 .PP
501 Here is the latter table in a more compact form.
502 .
503 .PP
504 .RS
505 .EX
506 \&.TBL cols=2 .TR \[dq].TD colspan=2\[dq] 1*1 1*2
507 \&.\& TR .TD 2*1 .TD 2*2 .ETB
508 .EE
509 .RE
510 .
511 .
512 .PP
513 If a macro has one or more arguments
514 (see below),
515 and it is not starting a line,
516 everything belonging to this macro including the macro itself must be
517 enclosed in double quotes.
518 .
519 .
520 .\" ====================================================================
521 .SH "Macros and arguments"
522 .\" ====================================================================
523 .
524 The order of macro calls and other tokens follows the HTML model.
525 .
526 In the following list, valid predecessors and successors of all
527 .I hdtbl
528 macros are given, together with the possible arguments.
529 .
530 .PP
531 Macro arguments are separated by blanks.
532 .
533 The order of arguments is arbitrary; they are of the form
534 .
535 .PP
536 .RS
537 .CRI key= value
538 .RE
539 .
540 .PP
541 or
542 .
543 .PP
544 .RS
545 .CRI key=\[aq] "value1 \[lB]value2 \[lB]\[ell]\[rB]\[rB]" \[aq]
546 .RE
547 .
548 .PP
549 with the only exception of the optional argument of the macro
550 .CR .ETB\c
551 , which is the string
552 .CR \[oq]hold\[cq]\c
553 \&.
554 .
555 Another possible form is
556 .
557 .PP
558 .RS
559 .CRI \[dq]key= "value1 \[lB]value2 \[lB]\[ell]\[rB]\[rB]" \[dq]
560 .RE
561 .
562 .
563 .PP
564 However,
565 this is limited to the case where the macro is the first one in the line
566 and not already enclosed in double quotes.
567 .
568 .
569 .PP
570 Argument values specified below as\~\c
571 .CI c
572 are colors predefined by
573 .I groff
574 or colors defined by the user with the
575 .CR .defcolor
576 request.
577 .
578 Argument values\~\c
579 .CI d
580 are decimal numbers with or without decimal point.
581 .
582 Argument values\~\c
583 .CI m
584 are natural numbers.
585 .
586 Argument values\~\c
587 .CI n
588 are numerical values with the usual
589 .I groff
590 scaling indicators.
591 .
592 Some of the arguments are specific to one or two macros, but most of
593 them can be specified with
594 .CR .TBL\c
595 ,
596 .CR .TR\c
597 ,
598 .CR .TD\c
599 , and
600 .CR .TH\
601 \&.
602 .
603 These common arguments are explained in the next subsection.
604 .
605 .
606 .PP
607 Most of the argument default values can be changed by the user by
608 setting corresponding default registers or strings, as listed below.
609 .
610 .\"==================================================================
611 .
612 .TP
613 .CBI ".TBL " \[lB]args\[rB]
614 Begin a new table.
615 .
616 .IP
617 .RS
618 .XB predecessor: .TD .TH .ETB "cell contents"
619 .XB successor: .CPTN .TR
620 .XB arguments:
621 .
622 .RS
623 .XAA border= \[lB]n\[rB]
624 Thickness of the surrounding box border.
625 .
626 .CR \%\[oq]border=\[cq]
627 (no value) means neither a surrounding box border nor any horizontal or
628 vertical separator lines between the table rows and cells.
629 .
630 .CR \%\[oq]border=0\[cq]
631 suppresses the surrounding box border, but still allows separator lines
632 between cells and rows.
633 .
634 .XDEFR border=.1n t*b
635 .
636 .XAA bc= c
637 Border color.
638 .
639 .XDEFS bc=red4 t*bc
640 .
641 .XAA cols= m
642 Number of table columns.
643 .
644 This argument is necessary if more than one column is in the table and
645 no
646 .CR \[oq]width\[cq]
647 arguments are present.
648 .
649 .XDEFR cols=1 t*cols
650 .
651 .XAA cpd= n
652 Cell padding, i.e., the extra space between the cell space border and
653 the cell contents.
654 .
655 .XDEFR cpd=.5n t*cpd
656 .
657 .XAA csp= n
658 Cell spacing, i.e., the extra space between the table border or
659 vertical or horizontal lines between cells and the cellspace.
660 .
661 .XDEFR csp=.5n t*csp
662 .
663 .XAA tal=l\[or]c\[or]r
664 Horizontal alignment of the table, if it is smaller than the line width.
665 .
666 .CR \[oq]tal=l\[cq]\c
667 : left alignment.
668 .
669 .CR \[oq]tal=c\[cq]\c
670 : centered alignment.
671 .
672 .CR \[oq]tal=r\[cq]\c
673 : right alignment.
674 .
675 .XDEFR tal=l t*tal
676 .
677 .XAA "width=\[aq]" "w1 \[lB]w2 \[lB]\[ell]\[rB]\[rB]" \[aq]
678 Widths of table cells.
679 .
680 .CI w1\c
681 .RI , ""
682 .CI w2\c
683 .RI , ""
684 \[ell] are either numbers of type\~\c
685 .CI n
686 or natural numbers with the pseudo-scaling indicator
687 .CR \[oq]%\[cq]\c
688 , with the meaning \[lq]percent of the actual line length
689 (or column length for inner tables,
690 respectively)\[rq].
691 .
692 If there are less width values than table columns,
693 the last width value is used for the remaining cells.
694 .
695 The argument
696 .
697 .RS
698 .IP
699 .CR width=\[aq]1.5i 10%\[aq]
700 .RE
701 .
702 .IP
703 for example indicates that the first column is 1.5\~inches wide; the
704 remaining columns take 1/10 of the column length each.
705 .
706 .XDEF
707 The table width equals the outer line length or column length;
708 the columns have equal widths.
709 .
710 .XAA height= n
711 Height of the table.
712 .
713 If the table with its contents is lower than\~\c
714 .CI n\c
715 .RI , ""
716 the last row is stretched to this value.
717 .RE
718 .RE
719 .
720 .\"==================================================================
721 .
722 .TP
723 .CBI ".CPTN " \[lB]args\[rB]
724 Text of caption.
725 .
726 .IP
727 The (optionally numbered) table caption.
728 .
729 .CR .CPTN
730 is optional.
731 .
732 .IP
733 .RS
734 .XB predecessor: .TBL
735 .XB successor: .TR
736 .XB arguments:
737 .
738 .RS
739 .XAA val=t\[or]b
740 Vertical alignment of the table caption.
741 .
742 .CR \[oq]val=t\[cq]\c
743 : The caption is placed above the table.
744 .
745 .CR \[oq]val=b\[cq]\c
746 : The caption is placed below the table.
747 .
748 .XDEFS val=t t*cptn
749 .RE
750 .RE
751 .
752 .\"==================================================================
753 .
754 .TP
755 .CBI ".TR " \[lB]args\[rB]
756 Begin a new table row.
757 .
758 .IP
759 .RS
760 .XB predecessor: .TBL .CPTN .TD .TH .ETB "cell contents"
761 .XB successor: .TD .TH
762 .XB arguments:
763 .
764 .RS
765 .XAA height= n
766 The height of the row.
767 .
768 If a cell in the row is higher than\~\c
769 .CI n\c
770 .RI , ""
771 this value is ignored;
772 otherwise the row height is stretched to\~\c
773 .CI n\c
774 .RI . ""
775 .RE
776 .RE
777 .
778 .\"==================================================================
779 .
780 .TP
781 .CBI ".TD " "\[lB]args \[lB]cell contents\[rB]\[rB]"
782 Begin a table data cell.
783 .TQ
784 .CBI ".TH " "\[lB]args \[lB]cell contents\[rB]\[rB]"
785 Begin a table header cell.
786 .
787 .IP
788 Arguments and cell contents can be mixed.
789 .
790 The macro
791 .CR .TH
792 is not really necessary and differs from
793 .CR .TD
794 only in three default settings, similar to the
795 .CR <TH>
796 and
797 .CR <TD>
798 HTML tags: The contents of
799 .CR .TH
800 is horizontally and vertically centered and typeset in boldface.
801 .
802 .IP
803 .RS
804 .XB predecessor: .TR .TD .TH .ETB "cell contents"
805 .XB successor: .TD .TH .TR .ETB "cell contents"
806 .XB arguments:
807 .
808 .RS
809 .XAA colspan= m
810 The width of this cell is the sum of the widths of the\~\c
811 .CI m
812 cells above and below this row.
813 .
814 .XAA rowspan= m
815 The height of this cell is the sum of the heights of the
816 .CI m
817 cells left and right of this column.
818 .
819 .IP
820 .B Remark:
821 Overlapping of column and row spanning,
822 as in the following table fragment
823 (the overlapping happens in the second cell in the second row),
824 is invalid and causes incorrect results.
825 .
826 .
827 .RS
828 .IP
829 .EX
830 \&.TR .TD 1*1 \[dq].TD 1*2 rowspan=2\[dq] .TD 1*3
831 \&.TR \[dq].TD 2*1 colspan=2\[dq] .TD 2*3
832 .EE
833 .RE
834 .
835 .
836 .PP
837 A working example for headers and cells with
838 .B colspan
839 is
840 .
841 .
842 .PP
843 .RS
844 .EX
845 \&.TBL cols=3
846 \&.\& TR \[dq].TH colspan=2\[dq] header1+2 .TH header3
847 \&.\& TR .TD 1*1 .TD 1*2 .TD 1*3
848 \&.\& TR .TD 2*1 \[dq].TD colspan=2\[dq] 2*2+3
849 \&.ETB
850 .EE
851 .RE
852 .
853 .
854 .PP
855 This looks like
856 .
857 .
858 .PP
859 .if t .ne 7v
860 .RS
861 .EX
862 .tr -\-
863 +------------------------------+---------------+
864 | header1+2 | header3 |
865 +--------------+---------------+---------------+
866 | 1*1 | 1*2 | 1*3 |
867 +--------------+---------------+---------------+
868 | 2*1 | 2*2+3 |
869 +--------------+-------------------------------+
870 .tr --
871 .EE
872 .RE
873 .
874 .
875 .PP
876 A working example with
877 .B rowspan
878 is
879 .
880 .
881 .PP
882 .RS
883 .EX
884 \&.TBL cols=3
885 \&.\& TR
886 \&.\& TD 1*1
887 \&.\& TD rowspan=2 1+2*2
888 \&.\& TD 1*3
889 \&.\&
890 \&.\& TR
891 \&.\& TD 2*1
892 \&.\& TD 2*3
893 \&.ETB
894 .EE
895 .RE
896 .
897 .
898 .PP
899 which looks like
900 .
901 .
902 .PP
903 .if t .ne 5v
904 .RS
905 .EX
906 .tr -\-
907 +--------------+---------------+---------------+
908 | 1*1 | 1+2*2 | 1*3 |
909 +--------------+ +---------------+
910 | 2*1 | | 2*3 |
911 +--------------+---------------+---------------+
912 .tr --
913 .EE
914 .RE
915 .RE
916 .RE
917 .
918 .\"==================================================================
919 .
920 .
921 .TP
922 .CB ".ETB \[lB]hold\[rB]"
923 End of the table.
924 .
925 .IP
926 This macro finishes a table.
927 .
928 It causes one of the following actions.
929 .
930 .RS
931 .IP \[bu] 3
932 If the argument
933 .CR \[oq]hold\[cq]
934 is given, the table is held until it is freed by calling the macro
935 .CR .t*free\c
936 , which in turn prints the table immediately,
937 either at the current position or at the top of the next page if its
938 height is larger than the remaining space on the page.
939 .
940 .IP \[bu] 3
941 Otherwise, if the table is higher than the remaining space on the page,
942 it is printed at the top of the next page.
943 .
944 .IP \[bu] 3
945 If neither of the two above constraints hold, the table is printed
946 immediately at the place of its definition.
947 .RE
948 .
949 .IP
950 .RS
951 .XB predecessor: .TD .TH .ETB "cell contents"
952 .XB successor: .TBL .TR .TD .TH .ETB "cell contents"
953 .XB arguments:
954 .
955 .RS
956 .XAA hold
957 Prevent the table from being printed until it is freed by calling the
958 macro
959 .CR .t*free\c
960 \&.
961 .
962 This argument is ignored for inner (nested) tables.
963 .RE
964 .RE
965 .
966 .\"==================================================================
967 .
968 .TP
969 .CBI ".t*free " \[lB]n\[rB]
970 Free the next held table or
971 .CI n\~\c
972 .RI held ""
973 tables.
974 .
975 Call this utility macro to print tables which are held by using the
976 .CR \[oq]hold\[cq]
977 argument of the
978 .CR .ETB
979 macro.
980 .
981 .
982 .\" ====================================================================
983 .SS "Arguments common to \f[CB].TBL\f[], \f[CB].TR\f[], \f[CB].TD\f[], \
984 and \f[CB].TH\f[]"
985 .\" ====================================================================
986 .
987 The arguments described in this section can be specified with the
988 .CR .TBL
989 and
990 .CR .TR
991 macros, but they are eventually passed on to the table cells.
992 .
993 If omitted,
994 the defaults take place,
995 which the user can change by setting the corresponding default registers
996 or strings,
997 as documented below.
998 .
999 Setting an argument with the
1000 .CR .TBL
1001 macro has the same effect as setting it for all rows in the table.
1002 .
1003 Setting an argument with a
1004 .CR .TR
1005 macro has the same effect as setting it for all the
1006 .CR .TH
1007 or
1008 .CR .TD
1009 macro in this row.
1010 .
1011 .IP
1012 .XAA bgc= \[lB]c\[rB]
1013 The background color of the table cells.
1014 .
1015 This includes the area specified with the
1016 .CR \[oq]csp\[cq]
1017 argument.
1018 .
1019 The argument
1020 .CR \[oq]bgc=\[cq]
1021 (no value) suppresses a background color; this makes the background
1022 transparent.
1023 .
1024 .XDEFS bgc=bisque t*bgc
1025 .
1026 .XAA fgc= c
1027 The foreground color of the cell contents.
1028 .
1029 .XDEFS fgc=red4 t*fgc
1030 .
1031 .XAA ff= name
1032 The font family for the table.
1033 .
1034 .CI name
1035 is a
1036 .I groff
1037 font family identifier,
1038 such as
1039 .CR A
1040 for Avant Garde or
1041 .CR HN
1042 for Helvetica Narrow.
1043 .
1044 .XDEF
1045 The font family found before the table (string
1046 .CR \[oq]t*ff\[cq]\c
1047 ).
1048 .
1049 .XAA fst= style
1050 The font style for the table.
1051 .
1052 One of
1053 .CR R\c
1054 ,
1055 .CR B\c
1056 ,
1057 .CR I\c
1058 , or
1059 .CR BI
1060 for roman,
1061 .BR bold ,
1062 .IR italic ,
1063 or \f[BI]bold italic\f[], \" \f[BI] is not portable man(7)
1064 respectively.
1065 .
1066 As with
1067 .IR roff 's
1068 .B .ft
1069 request,
1070 the
1071 .CR \[oq]fst\[cq]
1072 argument can be used to specify the font family and font style together,
1073 for example
1074 .CR \[oq]fst=HNBI\[cq]
1075 instead of
1076 .CR \[oq]ff=HN\[cq]
1077 and
1078 .CR \[oq]fst=BI\[cq]\c
1079 \&.
1080 .
1081 .XDEF
1082 The font style in use right before the table (string
1083 .CR \[oq]t*fst\[cq]\c
1084 ).
1085 .
1086 .XAA "fsz=\[aq]" "d1 \[lB]d2\[rB]" \[aq]
1087 A decimal or fractional factor
1088 .CI d1\c
1089 .RI , ""
1090 by which the point size for the table is changed, and
1091 .CI d2\c
1092 .RI , ""
1093 by which the vertical line spacing is changed.
1094 .
1095 If
1096 .CI d2
1097 is omitted, value
1098 .CI d1
1099 is taken for both.
1100 .
1101 .XDEFS "fsz=\[aq]1.0 1.0\[aq]" t*fsz
1102 .
1103 .XAA hal=l\[or]c\[or]b\[or]r
1104 Horizontal alignment of the cell contents in the table.
1105 .
1106 .CR \[oq]hal=l\[cq]\c
1107 : left alignment.
1108 .
1109 .CR \[oq]hal=c\[cq]\c
1110 : centered alignment.
1111 .
1112 .CR \[oq]hal=b\[cq]\c
1113 : both (left and right) alignment.
1114 .
1115 .CR \[oq]hal=r\[cq]\c
1116 : right alignment.
1117 .
1118 .XDEFS hal=b t*hal
1119 .
1120 .XAA val=t\[or]m\[or]b
1121 Vertical alignment of the cell contents in the table for cells lower
1122 than the current row.
1123 .
1124 .CR \[oq]val=t\[cq]\c
1125 : alignment below the top of the cell.
1126 .
1127 .CR \[oq]val=m\[cq]\c
1128 : alignment in the middle of the cell.
1129 .
1130 .CR \[oq]val=b\[cq]\c
1131 : alignment above the cell bottom.
1132 .
1133 .XDEFS val=t t*val
1134 .
1135 .XAA hl=\[lB]s\[or]d\[rB]
1136 Horizontal line between the rows.
1137 .
1138 If specified with
1139 .CR .TD
1140 or
1141 .CR .TH
1142 this is a separator line to the cell below.
1143 .
1144 .CR \[oq]hl=\[cq]
1145 (no value): no separator line.
1146 .
1147 .CR \[oq]hl=s\[cq]\c
1148 : a single separator line between the rows.
1149 .
1150 .CR \[oq]hl=d\[cq]\c
1151 : a double separator line.
1152 .
1153 .IP
1154 The thickness of the separator lines is the half of the border
1155 thickness,
1156 but at least 0.1\~inches.
1157 .
1158 The distance between the double lines is equal to the line thickness.
1159 .
1160 .IP
1161 .B Remark:
1162 Together with
1163 .CR \[oq]border=0\[cq]
1164 for proper formatting the value of
1165 .CR \[oq]csp\[cq]
1166 must be at least \&.05\~inches for single separator lines and
1167 \&.15\~inches for double separator lines.
1168 .
1169 .XDEFS hl=s t*hl
1170 .
1171 .XAA vl=\[lB]s\[or]d\[rB]
1172 Vertical separator line between the cells.
1173 .
1174 If specified with
1175 .CR .TD
1176 or
1177 .CR .TH
1178 this is a separator line to the cell on the right.
1179 .
1180 .CR \[oq]vl=s\[cq]\c
1181 : a single separator line between the cells.
1182 .
1183 .CR \[oq]vl=d\[cq]\c
1184 : a double separator line.
1185 .
1186 .CR \[oq]vl=\[cq]
1187 (no value): no vertical cell separator lines.
1188 .
1189 For more information see the documentation of the
1190 .CR \[oq]hl\[cq]
1191 argument above.
1192 .
1193 .XDEFS vl=s t*vl
1194 .
1195 .
1196 .\" ====================================================================
1197 .SH "\f[I]hdtbl\f[] customization"
1198 .\" ====================================================================
1199 .
1200 .PP
1201 Before creating the first table, you should configure default values
1202 to minimize the markup needed in each table.
1203 .
1204 The following example sets up defaults suitable for typical papers:
1205 .
1206 .
1207 .PP
1208 .RS
1209 .EX
1210 \&.ds t*bgc white\[rs]\[dq] background color
1211 \&.ds t*fgc black\[rs]\[dq] foreground color
1212 \&.ds t*bc black\[rs]\[dq] border color
1213 \&.nr t*cpd 0.1n\[rs]\[dq] cell padding
1214 .EE
1215 .RE
1216 .
1217 .
1218 .PP
1219 The file
1220 .I /usr/\:\%share/\:\%doc/\:\%groff\-base/\:\%examples/\:hdtbl/\:\%common\:.roff
1221 provides another example setup
1222 in the \[lq]minimal Page setup\[rq] section.
1223 .
1224 .
1225 .PP
1226 A table which does not fit on a partially filled page is printed
1227 automatically on the top of the next page if you append the little
1228 utility macro
1229 .CR t*hm
1230 to the page header macro of your document's main macro package.
1231 .
1232 For example, say
1233 .
1234 .
1235 .PP
1236 .RS
1237 .EX
1238 \&.am pg@top
1239 \&.\& t*hm
1240 \&..
1241 .EE
1242 .RE
1243 .
1244 .
1245 .PP
1246 if you use the
1247 .I ms
1248 macro package.
1249 .
1250 .
1251 .PP
1252 The macro
1253 .CR t*EM
1254 checks for held or kept tables,
1255 and for missing
1256 .CR ETB
1257 macros (table not closed).
1258 .
1259 You can call this macro by appending it the to end-of-input macro of
1260 the main,
1261 or \[lq]full-service\[rq],
1262 macro package your document uses.
1263 .
1264 For example,
1265 try
1266 .
1267 .
1268 .RS
1269 .EX
1270 \&.am pg@end\-text
1271 \&.\& t*EM
1272 \&..
1273 .EE
1274 .RE
1275 .
1276 if you use the
1277 .I ms
1278 package.
1279 .
1280 .
1281 .\" ====================================================================
1282 .SH "Bugs and suggestions"
1283 .\" ====================================================================
1284 .
1285 Please send your comments to the
1286 .MT groff@\:gnu\:.org
1287 .I groff
1288 mailing list
1289 .ME
1290 or directly to the author.
1291 .
1292 .
1293 .\" ====================================================================
1294 .SH Authors
1295 .\" ====================================================================
1296 .
1297 The
1298 .I hdtbl
1299 macro package was written by
1300 .MT Joachim\:.Walsdorff@\:urz\:.uni\-heidelberg\:.de
1301 Joachim Walsdorff
1302 .ME .
1303 .
1304 .
1305 .\" ====================================================================
1306 .SH "See also"
1307 .\" ====================================================================
1308 .
1309 .TP
1310 .MR groff 1
1311 provides an overview of GNU
1312 .I roff
1313 and details how to invoke
1314 .I groff
1315 at the command line.
1316 .
1317 .
1318 .TP
1319 .MR groff 7
1320 summarizes the
1321 .I roff
1322 language and GNU extensions to it.
1323 .
1324 .
1325 .TP
1326 .MR \%tbl 1
1327 describes the traditional
1328 .I roff
1329 preprocessor for tables.
1330 .
1331 .
1332 .\" Unwind (some of) the stuff we've done.
1333 .rchar \[lB]
1334 .rchar \[rB]
1335 .rchar \[or]
1336 .rchar \[ell]
1337 .rchar \[oq]
1338 .rchar \[cq]
1339 .
1340 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
1341 .cp \n[*groff_groff_hdtbl_7_man_C]
1342 .do rr *groff_groff_hdtbl_7_man_C
1343 .
1344 .
1345 .\" Local Variables:
1346 .\" fill-column: 72
1347 .\" mode: nroff
1348 .\" End:
1349 .\" vim: set filetype=groff textwidth=72: