Debian Codegraph @

upstream/debian-unstable/man7/groff_hdtbl.7

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