1groff_hdtbl(7) Miscellaneous Information Manual groff_hdtbl(7)
2
6 groff_hdtbl - Heidelberger table macros for GNU roff
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(7)'s full macro capabilities are available. On the other hand,
17 table processing with hdtbl is much slower than using the tbl(1) pre‐
18 processor. A further advantage is that the HTML-like syntax of hdtbl
19 will be easily converted to HTML; this is not implemented yet.
20
22 In this and the next section, we present examples to help users under‐
23 stand the basic workflow of hdtbl. First of all, you must load the
24 hdtbl.tmac file. As with nearly all other groff macro packages, there
25 are two possibilities to do so: Either add the line
26 .mso hdtbl.tmac
28 to your roff file before using any macros of the hdtbl package, or add
30 the option
31 -m hdtbl
33 to the command line of groff (before the document file which contains
35 hdtbl macros). Then you can include on or more tables in your docu‐
36 ment, where each one must be started and ended with the .TBL and .ETB
37 macros, respectively.
38 In this man page, we approximate the result of each example as terminal
40 output to be as generic as possible since hdtbl currently only supports
41 the ps and pdf output drivers.
42 The simplest well-formed table consists of just single calls to the
44 four base table macros in the right order. Here we construct a table
45 with only one cell.
46 .TBL
48 .TR
49 .TD
50 contents of the table cell
51 .ETB
52 A terminal representation is
54 +------------------------------------------------------+
56 | contents-of-the-table-cell |
57 +------------------------------------------------------+
58 Equivalent to the above is the following notation.
60 .TBL .TR .TD "contents of the table cell" .ETB
62 By default, the formatted table is inserted into the surrounding text
64 at the place of its definition. If the vertical space isn't suffi‐
65 cient, it is placed at the top of the next page. Tables can also be
66 stored for later insertion.
67 Using ‘row-number*column-number’ as the data for the table cells, a ta‐
69 ble with two rows and two columns can be written as
70 .TBL cols=2
72 . TR .TD 1*1 .TD 1*2
73 . TR .TD 2*1 .TD 2*2
74 .ETB
75 A terminal representation is
77 +--------------------------+---------------------------+
79 | 1*1 | 1*2 |
80 +--------------------------+---------------------------+
81 | 2*1 | 2*2 |
82 +--------------------------+---------------------------+
83 Here we see a difference from HTML tables: The number of columns must
85 be explicitly specified using the ‘cols=m’ argument (or indirectly via
86 the ‘width’ argument, see below).
87 The contents of a table cell is arbitrary; for example, it can be an‐
89 other table, without restriction to the nesting depth. A given table
90 layout can be either constructed with suitably nested tables or with
91 proper arguments to .TD and .TH, controlling column and row spanning.
92 Note, however, that this table
93 .TBL
95 . TR
96 . TD
97 . nop 1*1 1*2
98 . TR
99 . TD
100 . TBL cols=2 border=
101 . TR
102 . TD
103 . nop 2*1
104 . TD
105 . nop 2*2
106 . ETB
107 .ETB
108 and this table
110 .TBL cols=2
112 . TR
113 . TD colspan=2
114 . nop 1*1 1*2
115 . TR
116 . TD
117 . nop 2*1
118 . TD
119 . nop 2*2
120 .ETB
121 are similar but not identical (the use of .nop is purely cosmetic to
123 get proper indentation).
124 The first table looks like
126 +------------------------------------------------------+
128 | 1*1 1*2 |
129 +------------------------------------------------------+
130 | |
131 | 2*1 2*2 |
132 | |
133 +------------------------------------------------------+
134 and the second one like
136 +------------------------------------------------------+
138 | 1*1 1*2 |
139 +---------------------------+--------------------------+
140 | 2*1 | 2*2 |
141 +---------------------------+--------------------------+
142 Here is the latter table in a more compact form.
144 .TBL cols=2 .TR ".TD colspan=2" 1*1 1*2
146 . TR .TD 2*1 .TD 2*2 .ETB
147 If a macro has one or more arguments (see below), and it is not start‐
149 ing a line, everything belonging to this macro including the macro it‐
150 self must be enclosed in double quotes.
151
153 The order of macro calls and other tokens follows the HTML model. In
154 the following list, valid predecessors and successors of all hdtbl
155 macros are given, together with the possible arguments.
156 Macro arguments are separated by blanks. The order of arguments is ar‐
158 bitrary; they are of the form
159 key=value
161 or
163 key='value1 [value2 [...]]'
165 with the only exception of the optional argument of the macro .ETB,
167 which is the string ‘hold’. Another possible form is
168 "key=value1 [value2 [...]]"
170 However, this is limited to the case where the macro is the first one
172 in the line and not already enclosed in double quotes.
173 Argument values specified below as c are colors predefined by groff or
175 colors defined by the user with the .defcolor request. Argument val‐
176 ues d are decimal numbers with or without decimal point. Argument val‐
177 ues m are natural numbers. Argument values n are numerical values with
178 the usual groff scaling indicators. Some of the arguments are specific
179 to one or two macros, but most of them can be specified with .TBL, .TR,
180 .TD, and .TH. These common arguments are explained in the next subsec‐
181 tion.
182 Most of the argument default values can be changed by the user by set‐
184 ting corresponding default registers or strings, as listed below.
185 .TBL [args]
187 Begin a new table.
188 predecessor: .TD, .TH, .ETB, cell contents
190 successor: .CPTN, .TR
191 arguments:
192 border=[n]
193 Thickness of the surrounding box border.
194 ‘border=’ (no value) means neither a surrounding
195 box border nor any horizontal or vertical separa‐
196 tor lines between the table rows and cells.
197 ‘border=0’ suppresses the surrounding box border,
198 but still allows separator lines between cells and
199 rows.
200 Default: ‘border=.1n’ (register ‘t*b’).
201 bc=c Border color.
202 Default: ‘bc=red4’ (string ‘t*bc’).
203 cols=m Number of table columns. This argument is neces‐
204 sary if more than one column is in the table and
205 no ‘width’ arguments are present.
206 Default: ‘cols=1’ (register ‘t*cols’).
207 cpd=n Cell padding, i.e., the extra space between the
208 cell space border and the cell contents.
209 Default: ‘cpd=.5n’ (register ‘t*cpd’).
210 csp=n Cell spacing, i.e., the extra space between the
211 table border or vertical or horizontal lines be‐
212 tween cells and the cellspace.
213 Default: ‘csp=.5n’ (register ‘t*csp’).
214 tal=l|c|r
215 Horizontal alignment of the table, if it is
216 smaller than the line width. ‘tal=l’: left align‐
217 ment. ‘tal=c’: centered alignment. ‘tal=r’:
218 right alignment.
219 Default: ‘tal=l’ (register ‘t*tal’).
220 width='w1 [w2 [...]]'
221 Widths of table cells. w1, w2, ... are either
222 numbers of type n or natural numbers with the
223 pseudo-scaling indicator ‘%’, with the meaning
224 “percent of the actual line length (or column
225 length for inner tables, respectively)”. If there
226 are less width values than table columns, the last
227 width value is used for the remaining cells. The
228 argument
229 width='1.5i 10%'
231 for example indicates that the first column is
233 1.5 inches wide; the remaining columns take 1/10
234 of the column length each.
235 Default: The table width equals the outer line
236 length or column length; the columns have equal
237 widths.
238 height=n
239 Height of the table. If the table with its con‐
240 tents is lower than n, the last row is stretched
241 to this value.
242 .CPTN [args]
244 Text of caption.
245 The (optionally numbered) table caption. .CPTN is optional.
247 predecessor: .TBL
249 successor: .TR
250 arguments:
251 val=t|b
252 Vertical alignment of the table caption. ‘val=t’:
253 The caption is placed above the table. ‘val=b’:
254 The caption is placed below the table.
255 Default: ‘val=t’ (string ‘t*cptn’).
256 .TR [args]
258 Begin a new table row.
259 predecessor: .TBL, .CPTN, .TD, .TH, .ETB, cell contents
261 successor: .TD, .TH
262 arguments:
263 height=n
264 The height of the row. If a cell in the row is
265 higher than n, this value is ignored; otherwise
266 the row height is stretched to n.
267 .TD [args [cell contents]]
269 Begin a table data cell.
270 .TH [args [cell contents]]
271 Begin a table header cell.
272 Arguments and cell contents can be mixed. The macro .TH is not
274 really necessary and differs from .TD only in three default set‐
275 tings, similar to the <TH> and <TD> HTML tags: The contents of
276 .TH is horizontally and vertically centered and typeset in bold‐
277 face.
278 predecessor: .TR, .TD, .TH, .ETB, cell contents
280 successor: .TD, .TH, .TR, .ETB, cell contents
281 arguments:
282 colspan=m
283 The width of this cell is the sum of the widths of
284 the m cells above and below this row.
285 rowspan=m
286 The height of this cell is the sum of the heights
287 of the m cells left and right of this column.
288 Remark: Overlapping of column and row spanning, as
290 in the following table fragment (the overlapping
291 happens in the second cell in the second row), is
292 invalid and causes incorrect results.
293 .TR .TD 1*1 ".TD 1*2 rowspan=2" .TD 1*3
295 .TR ".TD 2*1 colspan=2" .TD 2*3
296 A working example for headers and cells with colspan is
298 .TBL cols=3
300 . TR ".TH colspan=2" header1+2 .TH header3
301 . TR .TD 1*1 .TD 1*2 .TD 1*3
302 . TR .TD 2*1 ".TD colspan=2" 2*2+3
303 .ETB
304 This looks like
306 +------------------------------+---------------+
308 | header1+2 | header3 |
309 +--------------+---------------+---------------+
310 | 1*1 | 1*2 | 1*3 |
311 +--------------+---------------+---------------+
312 | 2*1 | 2*2+3 |
313 +--------------+-------------------------------+
314 A working example with rowspan is
316 .TBL cols=3
318 . TR
319 . TD 1*1
320 . TD rowspan=2 1+2*2
321 . TD 1*3
322 .
323 . TR
324 . TD 2*1
325 . TD 2*3
326 .ETB
327 which looks like
329 +--------------+---------------+---------------+
331 | 1*1 | 1+2*2 | 1*3 |
332 +--------------+ +---------------+
333 | 2*1 | | 2*3 |
334 +--------------+---------------+---------------+
335 .ETB [hold]
337 End of the table.
338 This macro finishes a table. It causes one of the following ac‐
340 tions.
341 • If the argument ‘hold’ is given, the table is held until it
343 is freed by calling the macro .t*free, which in turn prints
344 the table immediately, either at the current position or at
345 the top of the next page if its height is larger than the re‐
346 maining space on the page.
347 • Otherwise, if the table is higher than the remaining space on
349 the page, it is printed at the top of the next page.
350 • If neither of the two above constraints hold, the table is
352 printed immediately at the place of its definition.
353 predecessor: .TD, .TH, .ETB, cell contents
355 successor: .TBL, .TR, .TD, .TH, .ETB, cell contents
356 arguments:
357 hold Prevent the table from being printed until it is
358 freed by calling the macro .t*free. This argument
359 is ignored for inner (nested) tables.
360 .t*free [n]
362 Free the next held table or n held tables. Call this utility
363 macro to print tables which are held by using the ‘hold’ argu‐
364 ment of the .ETB macro.
365 Arguments common to .TBL, .TR, .TD, and .TH
367 The arguments described in this section can be specified with the .TBL
368 and .TR macros, but they are eventually passed on to the table cells.
369 If omitted, the defaults take place, which the user can change by set‐
370 ting the corresponding default registers or strings, as documented be‐
371 low. Setting an argument with the .TBL macro has the same effect as
372 setting it for all rows in the table. Setting an argument with a .TR
373 macro has the same effect as setting it for all the .TH or .TD macro in
374 this row.
375 bgc=[c]
377 The background color of the table cells. This includes the area
378 specified with the ‘csp’ argument. The argument ‘bgc=’ (no
379 value) suppresses a background color; this makes the background
380 transparent.
381 Default: ‘bgc=bisque’ (string ‘t*bgc’).
382 fgc=c The foreground color of the cell contents.
383 Default: ‘fgc=red4’ (string ‘t*fgc’).
384 ff=name
385 The font family for the table. name is a groff font family
386 identifier, such as A for Avant Garde or HN for Helvetica Nar‐
387 row.
388 Default: The font family found before the table (string ‘t*ff’).
389 fst=style
390 The font style for the table. One of R, B, I, or BI for roman,
391 bold, italic, or bold italic, respectively. As with roff's .ft
392 request, the ‘fst’ argument can be used to specify the font fam‐
393 ily and font style together, for example ‘fst=HNBI’ instead of
394 ‘ff=HN’ and ‘fst=BI’.
395 Default: The font style in use right before the table (string
396 ‘t*fst’).
397 fsz='d1 [d2]'
398 A decimal or fractional factor d1, by which the point size for
399 the table is changed, and d2, by which the vertical line spacing
400 is changed. If d2 is omitted, value d1 is taken for both.
401 Default: ‘fsz='1.0 1.0'’ (string ‘t*fsz’).
402 hal=l|c|b|r
403 Horizontal alignment of the cell contents in the table.
404 ‘hal=l’: left alignment. ‘hal=c’: centered alignment. ‘hal=b’:
405 both (left and right) alignment. ‘hal=r’: right alignment.
406 Default: ‘hal=b’ (string ‘t*hal’).
407 val=t|m|b
408 Vertical alignment of the cell contents in the table for cells
409 lower than the current row. ‘val=t’: alignment below the top of
410 the cell. ‘val=m’: alignment in the middle of the cell.
411 ‘val=b’: alignment above the cell bottom.
412 Default: ‘val=t’ (string ‘t*val’).
413 hl=[s|d]
414 Horizontal line between the rows. If specified with .TD or .TH
415 this is a separator line to the cell below. ‘hl=’ (no value):
416 no separator line. ‘hl=s’: a single separator line between the
417 rows. ‘hl=d’: a double separator line.
418 The thickness of the separator lines is the half of the border
420 thickness, but at least 0.1 inches. The distance between the
421 double lines is equal to the line thickness.
422 Remark: Together with ‘border=0’ for proper formatting the value
424 of ‘csp’ must be at least .05 inches for single separator lines
425 and .15 inches for double separator lines.
426 Default: ‘hl=s’ (string ‘t*hl’).
427 vl=[s|d]
428 Vertical separator line between the cells. If specified with
429 .TD or .TH this is a separator line to the cell on the right.
430 ‘vl=s’: a single separator line between the cells. ‘vl=d’: a
431 double separator line. ‘vl=’ (no value): no vertical cell sepa‐
432 rator lines. For more information see the documentation of the
433 ‘hl’ argument above.
434 Default: ‘vl=s’ (string ‘t*vl’).
435
437 Before creating the first table, you should configure default values to
438 minimize the markup needed in each table. The following example sets
439 up defaults suitable for typical papers:
440 .ds t*bgc white\" background color
442 .ds t*fgc black\" foreground color
443 .ds t*bc black\" border color
444 .nr t*cpd 0.1n\" cell padding
445 The file /usr/share/doc/groff/examples/hdtbl/common.roff provides an‐
447 other example setup in the “minimal Page setup” section.
448 A table which does not fit on a partially filled page is printed auto‐
450 matically on the top of the next page if you append the little utility
451 macro t*hm to the page header macro of your document's main macro pack‐
452 age. For example, say
453 .am pg@top
455 . t*hm
456 ..
457 if you use the ms macro package.
459 The macro t*EM checks for held or kept tables, and for missing ETB
461 macros (table not closed). You can call this macro by appending it the
462 to end-of-input macro of the main, or “full-service”, macro package
463 your document uses. For example, try
464 .am pg@end-text
465 . t*EM
466 ..
467 if you use the ms package.
468
470 Please send your comments to the groff mailing list ⟨groff@gnu.org⟩ or
471 directly to the author.
472
474 The hdtbl macro package was written by Joachim Walsdorff ⟨Joachim
475 .Walsdorff@urz.uni-heidelberg.de⟩.
476
478 groff(1)
479 provides an overview of GNU roff and details how to invoke groff
480 at the command line.
481 groff(7)
483 summarizes the roff language and GNU extensions to it.
484 tbl(1) describes the traditional roff preprocessor for tables.
486groff 1.23.0 2 November 2023 groff_hdtbl(7)