Debian Codegraph @

upstream/opensuse-tumbleweed/man7/groff_hdtbl.7

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