1GROFF_HDTBL(7)         Miscellaneous Information Manual         GROFF_HDTBL(7)
2
3
4

NAME

6       groff_hdtbl - Heidelberger table macros for GNU roff
7

DESCRIPTION

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(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

USAGE

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
27              .mso hdtbl.tmac
28
29       to your roff file before using any macros of the hdtbl package, or  add
30       the option
31
32              -m hdtbl
33
34       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
39       In this man page, we approximate the result of each example in the  tty
40       format to be as generic as possible since hdtbl currently only supports
41       the PS and PDF output devices.
42
43       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
47              .TBL
48              .TR
49              .TD
50              contents of the table cell
51              .ETB
52
53       A tty representation is
54
55              +------------------------------------------------------+
56              | contents-of-the-table-cell                           |
57              +------------------------------------------------------+
58
59       Equivalent to the above is the following notation.
60
61              .TBL .TR .TD "contents of the table cell" .ETB
62
63       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
68       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
71              .TBL cols=2
72              .  TR .TD 1*1 .TD 1*2
73              .  TR .TD 2*1 .TD 2*2
74              .ETB
75
76       A tty representation is
77
78              +--------------------------+---------------------------+
79              | 1*1                      | 1*2                       |
80              +--------------------------+---------------------------+
81              | 2*1                      | 2*2                       |
82              +--------------------------+---------------------------+
83
84       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
88       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
94              .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
109       and this table
110
111              .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
122       are similar but not identical (the use of .nop is  purely  cosmetic  to
123       get proper indentation).
124
125       The first table looks like
126
127              +------------------------------------------------------+
128              | 1*1 1*2                                              |
129              +------------------------------------------------------+
130              |                                                      |
131              | 2*1                         2*2                      |
132              |                                                      |
133              +------------------------------------------------------+
134
135       and the second one like
136
137              +------------------------------------------------------+
138              | 1*1 1*2                                              |
139              +---------------------------+--------------------------+
140              | 2*1                       | 2*2                      |
141              +---------------------------+--------------------------+
142
143       Here the latter table in a more compact form.
144
145              .TBL cols=2 .TR ".TD colspan=2" 1*1 1*2
146              .            TR .TD 2*1 .TD 2*2 .ETB
147
148       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

MACROS AND ARGUMENTS

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
157       Macro arguments are separated by blanks.  The order of arguments is ar‐
158       bitrary; they are of the form
159
160              key=value
161
162       or
163
164              key='value1 [value2 [...]]'
165
166       with the only exception of the optional argument  of  the  macro  .ETB,
167       which is the string ‘hold’.  Another possible form is
168
169              "key=value1 [value2 [...]]"
170
171       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
174       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
183       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
186       .TBL [args]
187              Begin a new table.
188
189              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 small‐
216                            er than the line width.  ‘tal=l’: left  alignment.
217                            ‘tal=c’:   centered   alignment.   ‘tal=r’:  right
218                            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
230                                   width='1.5i 10%'
231
232                            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
243       .CPTN [args]
244              Text of caption.
245
246              The (optionally numbered) table caption.  .CPTN is optional.
247
248              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
257       .TR [args]
258              Begin a new table row.
259
260              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
268       .TD [args [cell contents]]
269              Begin a table data cell.
270       .TH [args [cell contents]]
271              Begin a table header cell.
272
273              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
279              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
289                            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
294                                   .TR .TD 1*1 ".TD 1*2 rowspan=2" .TD 1*3
295                                   .TR ".TD 2*1 colspan=2"         .TD 2*3
296
297                     A working example for headers and cells with colspan is
298
299                            .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
305                     This looks like
306
307                            +------------------------------+---------------+
308                            |          header1+2           |    header3    |
309                            +--------------+---------------+---------------+
310                            | 1*1          | 1*2           | 1*3           |
311                            +--------------+---------------+---------------+
312                            | 2*1          | 2*2+3                         |
313                            +--------------+-------------------------------+
314
315                     A working example with rowspan is
316
317                            .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
328                     which looks like
329
330                            +--------------+---------------+---------------+
331                            | 1*1          | 1+2*2         | 1*3           |
332                            +--------------+               +---------------+
333                            | 2*1          |               | 2*3           |
334                            +--------------+---------------+---------------+
335
336       .ETB [hold]
337              End of the table.
338
339              This macro finishes a table.  It causes one of the following ac‐
340              tions.
341
342              •  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
348              •  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
351              •  If neither of the two above constraints hold,  the  table  is
352                 printed immediately at the place of its definition.
353
354              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
361       .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
366   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
376       bgc=[c]
377              The background color of the table cells.  This includes the area
378              specified with the ‘csp’ argument.  The argument ‘bgc=’ (no val‐
379              ue) 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 one of the groff font
386              families, for example A for the AvantGarde fonts or HN for  Hel‐
387              vetica-Narrow.
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 fami‐
393              ly 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
419              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
423              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

HDTBL CUSTOMIZATION

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
441              .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
446       The  file  examples/common.roff  provides  another example setup in the
447       “minimal Page setup” section.
448
449       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
454              .am pg@top
455              .  t*hm
456              ..
457
458       if you use the ms macro package.
459
460       The  macro  t*EM  checks  for  held or kept tables, and for missing ETB
461       macros (table not closed).  You can append  this  macro  to  the  “end”
462       macro of your document's main macro package.  For example:
463
464              .am pg@end-text
465              .  t*EM
466              ..
467
468       If you use the ms macro package.
469

BUGS AND SUGGESTIONS

471       Please send your commments to the groff mailing list ⟨groff@gnu.org⟩ or
472       directly to the author.
473

AUTHORS

475       The  hdtbl   macro   package   was   written   by   Joachim   Walsdorff
476       ⟨Joachim.Walsdorff@urz.uni-heidelberg.de⟩.
477

SEE ALSO

479       groff(1)
480              provides an overview of GNU roff and details how to invoke groff
481              at the command line.
482
483       groff(7)
484              summarizes the roff language and GNU extensions to it.
485
486       tbl(1) describes the traditional roff preprocessor for tables.
487
488
489
490groff 1.22.4                    19 January 2023                 GROFF_HDTBL(7)
Impressum