1GROFF_HDTBL(7) Miscellaneous Information Manual GROFF_HDTBL(7)
2
6 groff_hdtbl - groff `hdtbl' macros for generation of tables
7
9 The hdtbl macros consist of four base and three optional macros, con‐
10 trolled by about twenty arguments. The syntax is simple and similar to
11 the HTML table model and nearly as flexible: You can write sequences of
12 tokens (macro calls with their arguments and content data), separated
13 by blanks and beginning with a macro call, into the same line to get
14 compact and cleanly arrranged input. An advantage of hdtbl is that the
15 tables are constructed without calling a preprocessor; this means that
16 groff's full macro capabilities are available. On the other hand, ta‐
17 ble processing with hdtbl is much slower than using the tbl(@MAN1EXT)
18 preprocessor. A further advantage is that the HTML-like syntax of
19 hdtbl will be easily converted to HTML; this is not implemented yet.
20
22 The simplest well-formed table consists of just single calls to the
23 four base table macros in the right order. Here we construct a table
24 with only one cell.
25 .TBL
27 .TR
28 .TD
29 contents of the table cell
30 .ETB
31 Equivalent to the above is the following notation.
33 .TBL .TR .TD contents of the table cell .ETB
35 By default, the formatted table is inserted into the surrounding text
37 at the place of its definition. If the vertical space isn't suffi‐
38 cient, it is placed at the top of the next page. Tables can also be
39 stored for later insertion.
40 Using ‘row-number*column-number’ as the data for the table cells, a ta‐
42 ble with two rows and two columns can be written as
43 .TBL cols=2
45 . TR .TD 1*1 .TD 1*2
46 . TR .TD 2*1 .TD 2*2
47 .ETB
48 Here we see a difference to HTML tables: The number of columns must be
50 explicitly specified using the ‘cols=m’ argument (or indirectly via the
51 ‘width’ argument, see below).
52 The contents of a table cell is arbitrary; for example, it can be
54 another table, without restriction to the nesting depth. A given table
55 layout can be either constructed with suitably nested tables or with
56 proper arguments to .TD and .TH, controlling column and row spanning.
57 Note, however, that this table
58 .TBL
60 . TR
61 . TD
62 . nop 1*1 1*2
63 . TR
64 . TD
65 . TBL cols=2 border=
66 . TR
67 . TD
68 . nop 2*1
69 . TD
70 . nop 2*2
71 . ETB
72 .ETB
73 and this table
75 .TBL cols=2
77 . TR
78 . TD colspan=2
79 . nop 1*1 1*2
80 . TR
81 . TD
82 . nop 2*1
83 . TD
84 . nop 2*2
85 .ETB
86 are similar but not identical.
88 Here the latter table in a more compact form.
90 .TBL cols=2 .TR ".TD colspan=2" 1*1 1*2
92 . TR .TD 2*1 .TD 2*2 .ETB
93 If a macro has one or more arguments, and it is not starting a line, it
95 must be enclosed in double quotes.
96
98 The order of macro calls and other tokens follows the HTML model. In
99 the following list, valid predecessors and successors of all hdtbl
100 macros are given, together with the possible arguments.
101 Macro arguments are separated by blanks. The order of arguments is
103 arbitrary; they are of the form
104 key=value
106 or
108 key='value1 [value2 [...]]'
110 with the only exception of the optional argument of the macro .ETB,
112 which is the string ‘hold’. Another possible form is
113 "key=value1 [value2 [...]]"
115 However, this is limited to the case where the macro is the first one
117 in the line and not already enclosed in double quotes.
118 Argument values specified below as c are colors predefined by groff or
120 colors defined by the user with the .defcolor request. Argument val‐
121 ues d are decimal numbers with or without decimal point. Argument val‐
122 ues m are natural numbers. Argument values n are numerical values with
123 the usual groff scaling indicators. Some of the arguments are specific
124 to one or two macros, but most of them can be specified with .TBL, .TR,
125 .TD, and .TH. These common arguments are explained in the next subsec‐
126 tion.
127 Most of the argument default values can be changed by the user by set‐
129 ting corresponding default registers or strings, as listed below.
130 .TBL [args]
132 Begin a new table.
133 predecessor: .TD, .TH, .ETB, cell contents
135 successor: .CPTN, .TR
136 arguments:
137 border=[n]
138 Thickness of the surrounding box border.
139 ‘border=’ (no value) means neither a surrounding
140 box border nor any horizontal or vertical separa‐
141 tor lines between the table rows and cells.
142 ‘border=0’ suppresses the surrounding box border,
143 but still allows separator lines between cells and
144 rows.
145 Default: ‘border=.1n’ (register ‘t*b’).
146 bc=c Border color.
147 Default: ‘bc=red4’ (string ‘t*bc’).
148 cols=m Number of table columns. This argument is neces‐
149 sary if more than one column is in the table and
150 no ‘width’ arguments are present.
151 Default: ‘cols=1’ (register ‘t*cols’).
152 cpd=n Cell padding, i.e., the extra space between the
153 cell space border and the cell contents.
154 Default: ‘cpd=.5n’ (register ‘t*cpd’).
155 csp=n Cell spacing, i.e., the extra space between the
156 table border or vertical or horizontal lines
157 between cells and the cellspace.
158 Default: ‘csp=.5n’ (register ‘t*csp’).
159 tal=l|c|r
160 Horizontal alignment of the table, if it is
161 smaller than the line width. ‘tal=l’: left align‐
162 ment. ‘tal=c’: centered alignment. ‘tal=r’:
163 right alignment.
164 Default: ‘tal=l’ (register ‘t*tal’).
165 width='w1 [w2 [...]]'
166 Widths of table cells. w1, w2, ... are either
167 numbers of type n or natural numbers with the
168 pseudo-scaling indicator ‘%’, with the meaning
169 “percent of the actual line length (or column
170 length for inner tables, respectively)”. If there
171 are less width values than table columns, the last
172 width value is used for the remaining cells. The
173 argument
174 width='1.5i 10%'
176 for example indicates that the first column is
178 1.5inches wide; the remaining columns take 1/10 of
179 the column length each.
180 Default: The table width equals the outer line
181 length or column length; the columns have equal
182 widths.
183 height=n
184 Height of the table. If the table with its con‐
185 tents is lower than n, the last row is stretched
186 to this value.
187 .CPTN [args]
189 Text of caption.
190 The (optionally numbered) table caption. .CPTN is optional.
192 predecessor: .TBL
194 successor: .TR
195 arguments:
196 val=t|b
197 Vertical alignment of the table caption. ‘val=t’:
198 The caption is placed above the table. ‘val=b’:
199 The caption is placed below the table.
200 Default: ‘val=t’ (string ‘t*cptn’).
201 .TR [args]
203 Begin a new table row.
204 predecessor: .TBL, .CPTN, .TD, .TH, .ETB, cell contents
206 successor: .TD, .TH
207 arguments:
208 height=n
209 The height of the row. If a cell in the row is
210 higher than n this value is ignored; otherwise the
211 row height is stretched to n.
212 .TD [args [cell contents]]
214 Begin a table data cell.
215 .TH [args [cell contents]]
216 Begin a table header cell.
217 Arguments and cell contents can be mixed. The macro .TH is not
219 really necessary and differs from .TD only in three default set‐
220 tings, similar to the <TH> and <TD> HTML tags: The contents of
221 .TH is horizontally and vertically centered and typeset in bold‐
222 face.
223 predecessor: .TR, .TD, .TH, .ETB, cell contents
225 successor: .TD, .TH, .TR, .ETB, cell contents
226 arguments:
227 colspan=m
228 The width of this cell is the sum of the widths of
229 the m cells above and below this row.
230 rowspan=m
231 The height of this cell is the sum of the heights
232 of the m cells left and right of this column.
233 Remark: Overlapping of column and row spanning, as
235 in the following table fragment (the overlapping
236 happens in the second cell in the second row), is
237 invalid and causes incorrect results.
238 .TR .TD 1*1 ".TD 1*2 rowspan=2" .TD 1*3
240 .TR ".TD 2*1 colspan=2" .TD 2*3
241 .ETB [hold]
243 End of the table.
244 This macro finishes a table. It causes one of the following
246 actions.
247 · If the argument ‘hold’ is given, the table is held until it
249 is freed by calling the macro .t*free, which in turn prints
250 the table immediately, either at the current position or at
251 the top of the next page if its height is larger than the
252 remaining space on the page.
253 · Otherwise, if the table is higher than the remaining space on
255 the page, it is printed at the top of the next page.
256 · If none of the two above constraints hold, the table is
258 printed immediately at the place of its definition.
259 predecessor: .TD, .TH, .ETB, cell contents
261 successor: .TBL, .TR, .TD, .TH, .ETB, cell contents
262 arguments:
263 hold Prevent the table from being printed until it is
264 freed by calling the macro .t*free. This argument
265 is ignored for inner (nested) tables.
266 .t*free [n]
268 Free the next held table or n held tables. Call this utility
269 macro to print tables which are held by using the ‘hold’ argu‐
270 ment of the .ETB macro.
271 Arguments common to .TBL, .TR, .TD, and .TH
273 The arguments described in this section can be specified with the .TBL
274 and .TR macros, but they are eventually passed on to the table cells.
275 If omitted, the defaults take place, which the user can change by set‐
276 ting the corresponding default registers or strings, as documented
277 below. Setting an argument with the .TBL macro has the same effect as
278 setting it for all rows in the table. Setting an argument with a .TR
279 macro has the same effect as setting it for all the .TH or .TD macro in
280 this row.
281 bgc=[c]
283 The background color of the table cells. This includes the area
284 specified with the ‘csp’ argument. The argument ‘bgc=’ (no
285 value) suppresses a background color; this makes the background
286 transparent.
287 Default: ‘bgc=bisque’ (string ‘t*bgc’).
288 fgc=c The foreground color of the cell contents.
289 Default: ‘fgc=red4’ (string ‘t*fgc’).
290 ff=name
291 The font family for the table. name is one of the groff font
292 families, for example A for the AvantGarde fonts or HN for Hel‐
293 vetica-Narrow.
294 Default: The font family found before the table (string ‘t*ff’).
295 fst=style
296 The font style for the table. One of R, I, B, or BI for roman,
297 bold, italic, or bold italic, respectively. As with roff's .ft
298 request the ‘fst’ argument can be used to specify the font fam‐
299 ily and font style together, for example ‘fst=HNBI’ instead of
300 ‘ff=HN’ and ‘fst=BI’.
301 Default: The font style in use right before the table (string
302 ‘t*fst’).
303 fsz='d1 [d2]'
304 A decimal or fractional factor d1, by which the point size for
305 the table is changed, and d2, by which the vertical line spacing
306 is changed. If d2 is omitted, value d1 is taken for both.
307 Default: ‘fsz='1.0 1.0'’ (string ‘t*fsz’).
308 hal=l|c|b|r
309 Horizontal alignment of the cell contents in the table.
310 ‘hal=l’: left alignment. ‘hal=c’: centered alignment. ‘hal=b’:
311 both (left and right) alignment. ‘hal=r’: right alignment.
312 Default: ‘hal=b’ (string ‘t*hal’).
313 val=t|m|b
314 Vertical alignment of the cell contents in the table for cells
315 lower than the current row. ‘val=t’: alignment below the top of
316 the cell. ‘val=m’: alignment in the middle of the cell.
317 ‘val=b’: alignment above the cell bottom.
318 Default: ‘val=t’ (string ‘t*val’).
319 hl=[s|d]
320 Horizontal line between the rows. If specified with .TD or .TH
321 this is a separator line to the cell below. ‘hl=’ (no value):
322 no separator line. ‘hl=s’: a single separator line between the
323 rows. ‘hl=d’: a double separator line.
324 The thickness of the separator lines is the half of the border
326 thickness, but at least 0.1inches. The distance between the
327 double lines is equal to the line thickness.
328 Remark: Together with ‘border=0’ for proper formatting the value
330 of ‘csp’ must be at least .05inches for single separator lines
331 and .15inches for double separator lines.
332 Default: ‘hl=s’ (string ‘t*hl’).
333 vl=[s|d]
334 Vertical separator line between the cells. If specified with
335 .TD or .TH this is a separator line to the cell on the right.
336 ‘vl=s’: a single separator line between the cells. ‘vl=d’: a
337 double separator line. ‘vl=’ (no value): no vertical cell sepa‐
338 rator lines. For more information see the documentation of the
339 ‘hl’ argument above.
340 Default: ‘vl=s’ (string ‘t*vl’).
341
343 A table which does not fit on a partially filled page is printed auto‐
344 matically on the top of the next page if you append the little utility
345 macro t*hm to the page header macro of your document's main macro pack‐
346 age. For example, say
347 .am pg@top
349 . t*hm
350 ..
351 if you use the ms macro package.
353 hdtbl has built-in page header and page footer macros, HM and BM. If
355 they interfere with your own header and footer macros, simply say
356 .rm HM and .rm BM to remove them.
357
359 Joachim Walsdorff ⟨Joachim.Walsdorff@urz.uni-heidelberg.de⟩
360
362 Please send your commments to the groff mailing list ⟨groff@gnu.org⟩ or
363 directly to the author.
364Groff Version 1.20.1 9 January 2009 GROFF_HDTBL(7)