1 .TH GROFF_HDTBL @MAN7EXT@ "@MDATE@" "groff @VERSION@"
3 groff_hdtbl \- Heidelberger table macros for GNU roff
6 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
7 .do nr groff_hdtbl_C \n[.C]
11 .\" ====================================================================
13 .\" ====================================================================
15 .\" Copyright (C) 2005-2018 Free Software Foundation, Inc.
17 .\" This file is part of groff, the GNU roff type-setting system.
19 .\" Permission is granted to copy, distribute and/or modify this
20 .\" document under the terms of the GNU Free Documentation License,
21 .\" Version 1.3 or any later version published by the Free Software
22 .\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
23 .\" and with no Back-Cover Texts.
25 .\" A copy of the Free Documentation License is included as a file
26 .\" called FDL in the main directory of the groff source package.
30 Some simple formatting macros. Note that we use '.ig' here and not a
31 comment to make 'mandb' 2.4.1 (and probably more recent versions also)
32 happy; otherwise the '.char' lines and the stuff which follows is included
33 in the 'whatis' database.
37 .char \[lB] \F[\n[.fam]]\f[R][
38 .char \[rB] \F[\n[.fam]]\f[R]]
40 .char \[or] \F[\n[.fam]]\f[R]\||\|
41 .char \[ell] \F[\n[.fam]]\f[R].\|.\|.
43 .char \[oq] \F[\n[.fam]]\f[R]\[oq]
44 .char \[cq] \F[\n[.fam]]\f[R]\[cq]
49 . \" We have to solve the following problem. In this code
55 . \" the space immediately after 'bar' should not be taken from the 'C'
56 . \" family. At the same time, this
62 . \" should work also. To fulfill both constraints we emit the
63 . \" family changing commands both as escapes and macro calls.
67 . ds old-fam \\\\n[.fam]
69 . \\$2 \&\\\\$*\F[]\F[\\\\*[old-fam]]
80 . ds old-fam \\\\n[.fam]
82 . \\$1 \\\\$@ \F[]\F[\\\\*[old-fam]]
148 . CR "\[oq]\\$1\[cq]"
150 . CR "\[oq]\\$2\[cq]\c"
158 . CR "\[oq]\\$1\[cq]"
160 . CR "\[oq]\\$2\[cq]\c"
164 .\" ====================================================================
166 .\" ====================================================================
170 macros consist of four base and three optional macros, controlled by about
173 The syntax is simple and similar to the
175 table model and nearly as flexible: You can write sequences of tokens (macro
176 calls with their arguments and content data), separated by blanks and
177 beginning with a macro call, into the same line to get compact and cleanly
182 is that the tables are constructed without calling a preprocessor; this
185 full macro capabilities are available.
187 On the other hand, table processing with
189 is much slower than using the
193 A further advantage is that the HTML-like syntax of
195 will be easily converted to HTML; this is not implemented yet.
198 .\" ====================================================================
200 .\" ====================================================================
202 In this and the next section, we present examples to help users
203 understand the basic workflow of
206 First of all, you must load the
210 As with nearly all other groff macro packages, there are two possibilities
227 file before using any macros of the
229 package, or add the option
241 to the command line of groff (before the document file which contains
245 Then you can include on or more tables in your document, where each one
246 must be started and ended with the
250 macros, respectively.
254 In this man page, we approximate the result of each example in the
256 format to be as generic as possible since
258 currently only supports the PS and PDF output devices.
262 The simplest well-formed table consists of just single calls to the
263 four base table macros in the right order.
265 Here we construct a table with only one cell.
274 .CI contents of the table cell
291 +------------------------------------------------------+
292 | contents-of-the-table-cell |
293 +------------------------------------------------------+
301 Equivalent to the above is the following notation.
307 .CRI ".TBL .TR .TD \[dq]" "contents of the table cell" "\[dq] .ETB"
314 By default, the formatted table is inserted into the surrounding text
315 at the place of its definition.
317 If the vertical space isn't sufficient, it is placed at the top of
320 Tables can also be stored for later insertion.
325 .CIR \[oq]row-number * column-number\[cq]
326 as the data for the table cells, a table with two rows and two columns
335 .CR ". TR .TD 1*1 .TD 1*2"
336 .CR ". TR .TD 2*1 .TD 2*2"
354 +--------------------------+---------------------------+
356 +--------------------------+---------------------------+
358 +--------------------------+---------------------------+
366 Here we see a difference from HTML tables: The number of columns must be
367 explicitly specified using the
368 .CRI \[oq]cols= m\[cq]
369 argument (or indirectly via the
371 argument, see below).
375 The contents of a table cell is arbitrary; for example, it can be another
376 table, without restriction to the nesting depth.
378 A given table layout can be either constructed with suitably nested tables
379 or with proper arguments to
383 , controlling column and row spanning.
385 Note, however, that this table
397 .CR ". TBL cols=2 border="
431 are similar but not identical (the use of
433 is purely cosmetic to get proper indentation).
437 The first table looks like
444 +------------------------------------------------------+
446 +------------------------------------------------------+
450 +------------------------------------------------------+
457 and the second one like
464 +------------------------------------------------------+
466 +---------------------------+--------------------------+
468 +---------------------------+--------------------------+
475 Here the latter table in a more compact form.
481 .CR ".TBL cols=2 .TR \[dq].TD colspan=2\[dq] 1*1 1*2"
482 .CR ". TR .TD 2*1 .TD 2*2 .ETB"
489 If a macro has one or more arguments (see below), and it is not starting a
490 line, everything belonging to this macro including the macro itself must be
491 enclosed in double quotes.
494 .\" ====================================================================
495 .SH MACROS AND ARGUMENTS
496 .\" ====================================================================
498 The order of macro calls and other tokens follows the HTML model.
500 In the following list, valid predecessors and successors of all
502 macros are given, together with the possible arguments.
505 Macro arguments are separated by blanks.
507 The order of arguments is arbitrary; they are of the form
519 .CRI key=\[aq] "value1 \[lB]value2 \[lB]\[ell]\[rB]\[rB]" \[aq]
523 with the only exception of the optional argument of the macro
525 , which is the string
529 Another possible form is
533 .CRI \[dq]key= "value1 \[lB]value2 \[lB]\[ell]\[rB]\[rB]" \[dq]
538 However, this is limited to the case where the macro is the first one in the
539 line and not already enclosed in double quotes.
543 Argument values specified below as\~\c
545 are colors predefined by
547 or colors defined by the user with the
553 are decimal numbers with or without decimal point.
561 are numerical values with the usual
565 Some of the arguments are specific to one or two macros, but most of
566 them can be specified with
576 These common arguments are explained in the next subsection.
580 Most of the argument default values can be changed by the user by
581 setting corresponding default registers or strings, as listed below.
583 .\"==================================================================
586 .CBI ".TBL " \[lB]args\[rB]
591 .XB predecessor: .TD .TH .ETB "cell contents"
592 .XB successor: .CPTN .TR
596 .XAA border= \[lB]n\[rB]
597 Thickness of the surrounding box border.
599 .CR \%\[oq]border=\[cq]
600 (no value) means neither a surrounding box border nor any horizontal or
601 vertical separator lines between the table rows and cells.
603 .CR \%\[oq]border=0\[cq]
604 suppresses the surrounding box border, but still allows separator lines
605 between cells and rows.
607 .XDEFR border=.1n t*b
615 Number of table columns.
617 This argument is necessary if more than one column is in the table and no
619 arguments are present.
624 Cell padding, i.e., the extra space between the cell space border and
630 Cell spacing, i.e., the extra space between the table border or
631 vertical or horizontal lines between cells and the cellspace.
635 .XAA tal=l\[or]c\[or]r
636 Horizontal alignment of the table, if it is smaller than the line width.
638 .CR \[oq]tal=l\[cq]\c
641 .CR \[oq]tal=c\[cq]\c
642 : centered alignment.
644 .CR \[oq]tal=r\[cq]\c
649 .XAA "width=\[aq]" "w1 \[lB]w2 \[lB]\[ell]\[rB]\[rB]" \[aq]
650 Widths of table cells.
656 \[ell] are either numbers of type\~\c
658 or natural numbers with the pseudo-scaling indicator
660 , with the meaning \[lq]percent of the actual line length (or column length
661 for inner tables, respectively)\[rq].
663 If there are less width values than table columns, the last width value is
664 used for the remaining cells.
670 .CR width=\[aq]1.5i 10%\[aq]
674 for example indicates that the first column is 1.5\~inches wide; the
675 remaining columns take 1/10 of the column length each.
678 The table width equals the outer line length or column length; the columns
684 If the table with its contents is lower than\~\c
687 the last row is stretched to this value.
691 .\"==================================================================
694 .CBI ".CPTN " \[lB]args\[rB]
698 The (optionally numbered) table caption.
705 .XB predecessor: .TBL
711 Vertical alignment of the table caption.
713 .CR \[oq]val=t\[cq]\c
714 : The caption is placed above the table.
716 .CR \[oq]val=b\[cq]\c
717 : The caption is placed below the table.
723 .\"==================================================================
726 .CBI ".TR " \[lB]args\[rB]
727 Begin a new table row.
731 .XB predecessor: .TBL .CPTN .TD .TH .ETB "cell contents"
732 .XB successor: .TD .TH
737 The height of the row.
739 If a cell in the row is higher than\~\c
742 this value is ignored;
743 otherwise the row height is stretched to\~\c
749 .\"==================================================================
752 .CBI ".TD " "\[lB]args \[lB]cell contents\[rB]\[rB]"
753 Begin a table data cell.
755 .CBI ".TH " "\[lB]args \[lB]cell contents\[rB]\[rB]"
756 Begin a table header cell.
759 Arguments and cell contents can be mixed.
763 is not really necessary and differs from
765 only in three default settings, similar to the
769 HTML tags: The contents of
771 is horizontally and vertically centered and typeset in boldface.
775 .XB predecessor: .TR .TD .TH .ETB "cell contents"
776 .XB successor: .TD .TH .TR .ETB "cell contents"
781 The width of this cell is the sum of the widths of the\~\c
783 cells above and below this row.
786 The height of this cell is the sum of the heights of the
788 cells left and right of this column.
792 Overlapping of column and row spanning, as in the following table fragment
793 (the overlapping happens in the second cell in the second row), is invalid
794 and causes incorrect results.
800 .CR ".TR .TD 1*1 \[dq].TD 1*2 rowspan=2\[dq] .TD 1*3"
801 .CR ".TR \[dq].TD 2*1 colspan=2\[dq] .TD 2*3"
807 A working example for headers and cells with
816 .CR ". TR" \[dq].TH colspan=2\[dq] header1+2 .TH header3
817 .CR ". TR" .TD 1*1 .TD 1*2 .TD 1*3
818 .CR ". TR" .TD 2*1 \[dq].TD colspan=2\[dq] 2*2+3
835 +------------------------------+---------------+
836 | header1+2 | header3 |
837 +--------------+---------------+---------------+
839 +--------------+---------------+---------------+
841 +--------------+-------------------------------+
848 A working example with
859 .CR ". TD" rowspan=2 1+2*2
878 +--------------+---------------+---------------+
879 | 1*1 | 1+2*2 | 1*3 |
880 +--------------+ +---------------+
882 +--------------+---------------+---------------+
891 .\"==================================================================
894 .CB ".ETB \[lB]hold\[rB]"
898 This macro finishes a table.
900 It causes one of the following actions.
906 is given, the table is held until it is freed by calling the macro
908 , which in turn prints the table immediately, either at the current position
909 or at the top of the next page if its height is larger than the remaining
913 Otherwise, if the table is higher than the remaining space on the page,
914 it is printed at the top of the next page.
917 If neither of the two above constraints hold, the table is printed
918 immediately at the place of its definition.
923 .XB predecessor: .TD .TH .ETB "cell contents"
924 .XB successor: .TBL .TR .TD .TH .ETB "cell contents"
929 Prevent the table from being printed until it is freed by calling the
934 This argument is ignored for inner (nested) tables.
938 .\"==================================================================
941 .CBI ".t*free " \[lB]n\[rB]
942 Free the next held table or
947 Call this utility macro to print tables which are held by using the
954 .\" ====================================================================
955 .SS "Arguments common to \f[CB].TBL\f[], \f[CB].TR\f[], \f[CB].TD\f[], and \f[CB].TH\f[]"
956 .\" ====================================================================
958 The arguments described in this section can be specified with the
962 macros, but they are eventually passed on to the table cells.
964 If omitted, the defaults take place, which the user can change by setting
965 the corresponding default registers or strings, as documented below.
967 Setting an argument with the
969 macro has the same effect as setting it for all rows in the table.
971 Setting an argument with a
973 macro has the same effect as setting it for all the
980 .XAA bgc= \[lB]c\[rB]
981 The background color of the table cells.
983 This includes the area specified with the
989 (no value) suppresses a background color; this makes the background
992 .XDEFS bgc=bisque t*bgc
995 The foreground color of the cell contents.
997 .XDEFS fgc=red4 t*fgc
1000 The font family for the table.
1003 is one of the groff font families, for example
1005 for the AvantGarde fonts or
1007 for Helvetica-Narrow.
1010 The font family found before the table (string
1011 .CR \[oq]t*ff\[cq]\c
1015 The font style for the table.
1028 or \f[BI]bold italic\f[], respectively.
1035 argument can be used to specify the font family and font style together, for
1037 .CR \[oq]fst=HNBI\[cq]
1041 .CR \[oq]fst=BI\[cq]\c
1045 The font style in use right before the table (string
1046 .CR \[oq]t*fst\[cq]\c
1049 .XAA "fsz=\[aq]" "d1 \[lB]d2\[rB]" \[aq]
1050 A decimal or fractional factor
1053 by which the point size for the table is changed, and
1056 by which the vertical line spacing is changed.
1064 .XDEFS "fsz=\[aq]1.0 1.0\[aq]" t*fsz
1066 .XAA hal=l\[or]c\[or]b\[or]r
1067 Horizontal alignment of the cell contents in the table.
1069 .CR \[oq]hal=l\[cq]\c
1072 .CR \[oq]hal=c\[cq]\c
1073 : centered alignment.
1075 .CR \[oq]hal=b\[cq]\c
1076 : both (left and right) alignment.
1078 .CR \[oq]hal=r\[cq]\c
1083 .XAA val=t\[or]m\[or]b
1084 Vertical alignment of the cell contents in the table for cells lower
1085 than the current row.
1087 .CR \[oq]val=t\[cq]\c
1088 : alignment below the top of the cell.
1090 .CR \[oq]val=m\[cq]\c
1091 : alignment in the middle of the cell.
1093 .CR \[oq]val=b\[cq]\c
1094 : alignment above the cell bottom.
1098 .XAA hl=\[lB]s\[or]d\[rB]
1099 Horizontal line between the rows.
1105 this is a separator line to the cell below.
1108 (no value): no separator line.
1110 .CR \[oq]hl=s\[cq]\c
1111 : a single separator line between the rows.
1113 .CR \[oq]hl=d\[cq]\c
1114 : a double separator line.
1117 The thickness of the separator lines is the half of the border thickness,
1118 but at least 0.1\~inches.
1120 The distance between the double lines is equal to the line thickness.
1125 .CR \[oq]border=0\[cq]
1126 for proper formatting the value of
1128 must be at least .05\~inches for single separator lines and .15\~inches for
1129 double separator lines.
1133 .XAA vl=\[lB]s\[or]d\[rB]
1134 Vertical separator line between the cells.
1140 this is a separator line to the cell on the right.
1142 .CR \[oq]vl=s\[cq]\c
1143 : a single separator line between the cells.
1145 .CR \[oq]vl=d\[cq]\c
1146 : a double separator line.
1149 (no value): no vertical cell separator lines.
1151 For more information see the documentation of the
1158 .\" ====================================================================
1159 .SH HDTBL CUSTOMIZATION
1160 .\" ====================================================================
1163 Before creating the first table, you should configure default values
1164 to minimize the markup needed in each table.
1166 The following example sets up defaults suitable for typical papers:
1170 .CR ".ds t*bgc white\e\[dq] background color
1171 .CR ".ds t*fgc black\e\[dq] foreground color
1172 .CR ".ds t*bc black\e\[dq] border color
1173 .CR ".nr t*cpd 0.1n\e\[dq] cell padding
1180 .B examples/common.roff
1181 provides another example setup
1182 in the \[lq]minimal Page setup\[rq] section.
1186 A table which does not fit on a partially filled page is printed
1187 automatically on the top of the next page if you append the little
1190 to the page header macro of your document's main macro package.
1213 checks for held or kept tables,
1216 macros (table not closed).
1218 You can append this macro
1219 to the \[lq]end\[rq] macro of your document's main macro package.
1227 .CR ".am pg@end-text"
1240 .\" ====================================================================
1241 .SH BUGS AND SUGGESTIONS
1242 .\" ====================================================================
1244 Please send your commments to the
1248 or directly to the author.
1251 .\" ====================================================================
1253 .\" ====================================================================
1256 macro package was written by
1257 .MT Joachim.Walsdorff@\:urz.uni\-heidelberg.de
1262 .\" ====================================================================
1264 .\" ====================================================================
1267 provides an overview of GNU
1269 and details how to invoke
1271 at the command line.
1276 language and GNU extensions to it.
1279 describes the traditional
1281 preprocessor for tables.
1284 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
1285 .cp \n[groff_hdtbl_C]
1288 .\" ====================================================================
1290 .\" ====================================================================
1292 .\" Local Variables:
1295 .\" vim: filetype=groff:
projects / platform / upstream / groff.git / blob