Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
groff_hdtbl(7)	       Miscellaneous Information Manual		groff_hdtbl(7)

Name
       groff_hdtbl - Heidelberger table	macros for GNU roff

Description
       The  hdtbl  macros consist of four base and three optional macros, con-
       trolled by about	twenty arguments.  The syntax is simple	and similar to
       the HTML	table model and	nearly as flexible: you	can write sequences of
       tokens (macro calls with	their arguments	and content  data),  separated
       by  blanks  and	beginning with a macro call, into the same line	to get
       compact and cleanly arrranged input.  An	advantage of hdtbl is that the
       tables are constructed without calling a	preprocessor; this means  that
       groff(7)'s  full	 macro capabilities are	available.  On the other hand,
       table processing	with hdtbl is much slower than using the  tbl(1)  pre-
       processor.   A  further advantage is that the HTML-like syntax of hdtbl
       will be easily converted	to HTML; this is not implemented yet.

Usage
       In this and the next section, we	present	examples to help users	under-
       stand  the  basic  workflow  of hdtbl.  First of	all, you must load the
       hdtbl.tmac file.	 As with nearly	all other groff	macro packages,	 there
       are two possibilities to	do so: Either add the line

	      .mso hdtbl.tmac

       to  your	roff file before using any macros of the hdtbl package,	or add
       the option

	      -m hdtbl

       to the command line of groff (before the	document file  which  contains
       hdtbl  macros).	 Then  you can include on or more tables in your docu-
       ment, where each	one must be started and	ended with the .TBL  and  .ETB
       macros, respectively.

       In this man page, we approximate	the result of each example as terminal
       output to be as generic as possible since hdtbl currently only supports
       the ps and pdf output drivers.

       The  simplest  well-formed  table  consists of just single calls	to the
       four base table macros in the right order.  Here	we construct  a	 table
       with only one cell.

	      .TBL
	      .TR
	      .TD
	      contents of the table cell
	      .ETB

       A terminal representation is

	      +------------------------------------------------------+
	      |	contents-of-the-table-cell			     |
	      +------------------------------------------------------+

       Equivalent to the above is the following	notation.

	      .TBL .TR .TD "contents of	the table cell"	.ETB

       By  default,  the formatted table is inserted into the surrounding text
       at the place of its definition.	If the	vertical  space	 isn't	suffi-
       cient,  it  is  placed at the top of the	next page.  Tables can also be
       stored for later	insertion.

       Using `row-number*column-number'	as the data for	the table cells, a ta-
       ble with	two rows and two columns can be	written	as

	      .TBL cols=2
	      .	 TR .TD	1*1 .TD	1*2
	      .	 TR .TD	2*1 .TD	2*2
	      .ETB

       A terminal representation is

	      +--------------------------+---------------------------+
	      |	1*1			 | 1*2			     |
	      +--------------------------+---------------------------+
	      |	2*1			 | 2*2			     |
	      +--------------------------+---------------------------+

       Here we see a difference	from HTML tables: The number of	 columns  must
       be  explicitly specified	using the `cols=m' argument (or	indirectly via
       the `width' argument, see below).

       The contents of a table cell is arbitrary; for example, it can  be  an-
       other  table,  without restriction to the nesting depth.	 A given table
       layout can be either constructed	with suitably nested  tables  or  with
       proper  arguments  to .TD and .TH, controlling column and row spanning.
       Note, however, that this	table

	      .TBL
	      .	 TR
	      .	   TD
	      .	     nop 1*1 1*2
	      .	 TR
	      .	   TD
	      .	     TBL cols=2	border=
	      .	       TR
	      .		 TD
	      .		   nop 2*1
	      .		 TD
	      .		   nop 2*2
	      .	     ETB
	      .ETB

       and this	table

	      .TBL cols=2
	      .	 TR
	      .	   TD colspan=2
	      .	     nop 1*1 1*2
	      .	 TR
	      .	   TD
	      .	     nop 2*1
	      .	   TD
	      .	     nop 2*2
	      .ETB

       are similar but not identical (the use of .nop is  purely  cosmetic  to
       get proper indentation).

       The first table looks like

	      +------------------------------------------------------+
	      |	1*1 1*2						     |
	      +------------------------------------------------------+
	      |							     |
	      |	2*1			    2*2			     |
	      |							     |
	      +------------------------------------------------------+

       and the second one like

	      +------------------------------------------------------+
	      |	1*1 1*2						     |
	      +---------------------------+--------------------------+
	      |	2*1			  | 2*2			     |
	      +---------------------------+--------------------------+

       Here is the latter table	in a more compact form.

	      .TBL cols=2 .TR ".TD colspan=2" 1*1 1*2
	      .		   TR .TD 2*1 .TD 2*2 .ETB

       If  a macro has one or more arguments (see below), and it is not	start-
       ing a line, everything belonging	to this	macro including	the macro  it-
       self must be enclosed in	double quotes.

Macros and arguments
       The  order  of macro calls and other tokens follows the HTML model.  In
       the following list, valid predecessors  and  successors	of  all	 hdtbl
       macros are given, together with the possible arguments.

       Macro arguments are separated by	blanks.	 The order of arguments	is ar-
       bitrary;	they are of the	form

	      key=value

       or

	      key='value1 [value2 [...]]'

       with  the  only	exception  of the optional argument of the macro .ETB,
       which is	the string `hold'.  Another possible form is

	      "key=value1 [value2 [...]]"

       However,	this is	limited	to the case where the macro is the  first  one
       in the line and not already enclosed in double quotes.

       Argument	 values	specified below	as c are colors	predefined by groff or
       colors defined by the user with the .defcolor request.	Argument  val-
       ues d are decimal numbers with or without decimal point.	 Argument val-
       ues m are natural numbers.  Argument values n are numerical values with
       the usual groff scaling indicators.  Some of the	arguments are specific
       to one or two macros, but most of them can be specified with .TBL, .TR,
       .TD, and	.TH.  These common arguments are explained in the next subsec-
       tion.

       Most  of	the argument default values can	be changed by the user by set-
       ting corresponding default registers or strings,	as listed below.

       .TBL [args]
	      Begin a new table.

	      predecessor: .TD,	.TH, .ETB, cell	contents
	      successor: .CPTN,	.TR
	      arguments:
		     border=[n]
			    Thickness	of   the   surrounding	 box   border.
			    `border='  (no  value) means neither a surrounding
			    box	border nor any horizontal or vertical  separa-
			    tor	 lines	between	 the  table  rows  and	cells.
			    `border=0' suppresses the surrounding box  border,
			    but	still allows separator lines between cells and
			    rows.
			    Default: `border=.1n' (register `t*b').
		     bc=c   Border color.
			    Default: `bc=red4' (string `t*bc').
		     cols=m Number  of table columns.  This argument is	neces-
			    sary if more than one column is in the  table  and
			    no `width' arguments are present.
			    Default: `cols=1' (register	`t*cols').
		     cpd=n  Cell  padding,  i.e.,  the extra space between the
			    cell space border and the cell contents.
			    Default: `cpd=.5n' (register `t*cpd').
		     csp=n  Cell spacing, i.e.,	the extra  space  between  the
			    table  border  or vertical or horizontal lines be-
			    tween cells	and the	cellspace.
			    Default: `csp=.5n' (register `t*csp').
		     tal=l|c|r
			    Horizontal	alignment  of  the  table,  if	it  is
			    smaller than the line width.  `tal=l': left	align-
			    ment.    `tal=c':  centered	 alignment.   `tal=r':
			    right alignment.
			    Default: `tal=l' (register `t*tal').
		     width='w1 [w2 [...]]'
			    Widths of table cells.  w1,	 w2,  ...  are	either
			    numbers  of	 type  n  or  natural numbers with the
			    pseudo-scaling indicator  `%',  with  the  meaning
			    "percent  of  the  actual  line  length (or	column
			    length for inner tables, respectively)".  If there
			    are	less width values than table columns, the last
			    width value	is used	for the	remaining cells.   The
			    argument

				   width='1.5i 10%'

			    for	 example  indicates  that  the first column is
			    1.5	inches wide; the remaining columns  take  1/10
			    of the column length each.
			    Default:  The  table  width	 equals	the outer line
			    length or column length; the  columns  have	 equal
			    widths.
		     height=n
			    Height  of	the table.  If the table with its con-
			    tents is lower than	n, the last row	 is  stretched
			    to this value.

       .CPTN [args]
	      Text of caption.

	      The (optionally numbered)	table caption.	.CPTN is optional.

	      predecessor: .TBL
	      successor: .TR
	      arguments:
		     val=t|b
			    Vertical alignment of the table caption.  `val=t':
			    The	 caption  is placed above the table.  `val=b':
			    The	caption	is placed below	the table.
			    Default: `val=t' (string `t*cptn').

       .TR [args]
	      Begin a new table	row.

	      predecessor: .TBL, .CPTN,	.TD, .TH, .ETB,	cell contents
	      successor: .TD, .TH
	      arguments:
		     height=n
			    The	height of the row.  If a cell in  the  row  is
			    higher  than  n,  this value is ignored; otherwise
			    the	row height is stretched	to n.

       .TD [args [cell contents]]
	      Begin a table data cell.
       .TH [args [cell contents]]
	      Begin a table header cell.

	      Arguments	and cell contents can be mixed.	 The macro .TH is  not
	      really necessary and differs from	.TD only in three default set-
	      tings,  similar  to the <TH> and <TD> HTML tags: The contents of
	      .TH is horizontally and vertically centered and typeset in bold-
	      face.

	      predecessor: .TR,	.TD, .TH, .ETB,	cell contents
	      successor: .TD, .TH, .TR,	.ETB, cell contents
	      arguments:
		     colspan=m
			    The	width of this cell is the sum of the widths of
			    the	m cells	above and below	this row.
		     rowspan=m
			    The	height of this cell is the sum of the  heights
			    of the m cells left	and right of this column.

			    Remark: Overlapping	of column and row spanning, as
			    in	the  following table fragment (the overlapping
			    happens in the second cell in the second row),  is
			    invalid and	causes incorrect results.

				   .TR .TD 1*1 ".TD 1*2	rowspan=2" .TD 1*3
				   .TR ".TD 2*1	colspan=2"	   .TD 2*3

		     A working example for headers and cells with colspan is

			    .TBL cols=3
			    .  TR ".TH colspan=2" header1+2 .TH	header3
			    .  TR .TD 1*1 .TD 1*2 .TD 1*3
			    .  TR .TD 2*1 ".TD colspan=2" 2*2+3
			    .ETB

		     This looks	like

			    +------------------------------+---------------+
			    |	       header1+2	   |	header3	   |
			    +--------------+---------------+---------------+
			    | 1*1	   | 1*2	   | 1*3	   |
			    +--------------+---------------+---------------+
			    | 2*1	   | 2*2+3			   |
			    +--------------+-------------------------------+

		     A working example with rowspan is

			    .TBL cols=3
			    .  TR
			    .  TD 1*1
			    .  TD rowspan=2 1+2*2
			    .  TD 1*3
			    .
			    .  TR
			    .  TD 2*1
			    .  TD 2*3
			    .ETB

		     which looks like

			    +--------------+---------------+---------------+
			    | 1*1	   | 1+2*2	   | 1*3	   |
			    +--------------+		   +---------------+
			    | 2*1	   |		   | 2*3	   |
			    +--------------+---------------+---------------+

       .ETB [hold]
	      End of the table.

	      This macro finishes a table.  It causes one of the following ac-
	      tions.

	      	 If  the  argument `hold' is given, the	table is held until it
		 is freed by calling the macro .t*free,	which in  turn	prints
		 the  table  immediately, either at the	current	position or at
		 the top of the	next page if its height	is larger than the re-
		 maining space on the page.

	      	 Otherwise, if the table is higher than	the remaining space on
		 the page, it is printed at the	top of the next	page.

	      	 If neither of the two above constraints hold,	the  table  is
		 printed immediately at	the place of its definition.

	      predecessor: .TD,	.TH, .ETB, cell	contents
	      successor: .TBL, .TR, .TD, .TH, .ETB, cell contents
	      arguments:
		     hold   Prevent  the  table	from being printed until it is
			    freed by calling the macro .t*free.	 This argument
			    is ignored for inner (nested) tables.

       .t*free [n]
	      Free the next held table or n held tables.   Call	 this  utility
	      macro  to	 print tables which are	held by	using the `hold' argu-
	      ment of the .ETB macro.

   Arguments common to .TBL, .TR, .TD, and .TH
       The arguments described in this section can be specified	with the  .TBL
       and  .TR	 macros, but they are eventually passed	on to the table	cells.
       If omitted, the defaults	take place, which the user can change by  set-
       ting  the corresponding default registers or strings, as	documented be-
       low.  Setting an	argument with the .TBL macro has the  same  effect  as
       setting	it  for	all rows in the	table.	Setting	an argument with a .TR
       macro has the same effect as setting it for all the .TH or .TD macro in
       this row.

       bgc=[c]
	      The background color of the table	cells.	This includes the area
	      specified	with the `csp'	argument.   The	 argument  `bgc='  (no
	      value)  suppresses a background color; this makes	the background
	      transparent.
	      Default: `bgc=bisque' (string `t*bgc').
       fgc=c  The foreground color of the cell contents.
	      Default: `fgc=red4' (string `t*fgc').
       ff=name
	      The font family for the table.  name  is	a  groff  font	family
	      identifier,  such	 as A for Avant	Garde or HN for	Helvetica Nar-
	      row.
	      Default: The font	family found before the	table (string `t*ff').
       fst=style
	      The font style for the table.  One of R, B, I, or	BI for	roman,
	      bold,  italic, or	bold italic, respectively.  As with roff's .ft
	      request, the `fst' argument can be used to specify the font fam-
	      ily and font style together, for example `fst=HNBI'  instead  of
	      `ff=HN' and `fst=BI'.
	      Default:	The  font  style in use	right before the table (string
	      `t*fst').
       fsz='d1 [d2]'
	      A	decimal	or fractional factor d1, by which the point  size  for
	      the table	is changed, and	d2, by which the vertical line spacing
	      is changed.  If d2 is omitted, value d1 is taken for both.
	      Default: `fsz='1.0 1.0'' (string `t*fsz').
       hal=l|c|b|r
	      Horizontal   alignment  of  the  cell  contents  in  the	table.
	      `hal=l': left alignment.	`hal=c': centered alignment.  `hal=b':
	      both (left and right) alignment.	`hal=r': right alignment.
	      Default: `hal=b' (string `t*hal').
       val=t|m|b
	      Vertical alignment of the	cell contents in the table  for	 cells
	      lower than the current row.  `val=t': alignment below the	top of
	      the  cell.   `val=m':  alignment	in  the	 middle	 of  the cell.
	      `val=b': alignment above the cell	bottom.
	      Default: `val=t' (string `t*val').
       hl=[s|d]
	      Horizontal line between the rows.	 If specified with .TD or  .TH
	      this  is	a separator line to the	cell below.  `hl=' (no value):
	      no separator line.  `hl=s': a single separator line between  the
	      rows.  `hl=d': a double separator	line.

	      The  thickness  of the separator lines is	the half of the	border
	      thickness, but at	least 0.1 inches.  The	distance  between  the
	      double lines is equal to the line	thickness.

	      Remark: Together with `border=0' for proper formatting the value
	      of  `csp'	must be	at least .05 inches for	single separator lines
	      and .15 inches for double	separator lines.
	      Default: `hl=s' (string `t*hl').
       vl=[s|d]
	      Vertical separator line between the cells.   If  specified  with
	      .TD  or  .TH  this is a separator	line to	the cell on the	right.
	      `vl=s': a	single separator line between the  cells.   `vl=d':  a
	      double separator line.  `vl=' (no	value):	no vertical cell sepa-
	      rator  lines.  For more information see the documentation	of the
	      `hl' argument above.
	      Default: `vl=s' (string `t*vl').

hdtbl customization
       Before creating the first table,	you should configure default values to
       minimize	the markup needed in each table.  The following	 example  sets
       up defaults suitable for	typical	papers:

	      .ds t*bgc	white\"	background color
	      .ds t*fgc	black\"	foreground color
	      .ds t*bc black\"	border color
	      .nr t*cpd	0.1n\"	cell padding

       The  file  /usr/local/share/doc/groff-1.23.0/examples/hdtbl/common.roff
       provides	another	example	setup in the "minimal Page setup" section.

       A table which does not fit on a partially filled	page is	printed	 auto-
       matically  on the top of	the next page if you append the	little utility
       macro t*hm to the page header macro of your document's main macro pack-
       age.  For example, say

	      .am pg@top
	      .	 t*hm
	      ..

       if you use the ms macro package.

       The macro t*EM checks for held or kept  tables,	and  for  missing  ETB
       macros (table not closed).  You can call	this macro by appending	it the
       to  end-of-input	 macro	of  the	main, or "full-service", macro package
       your document uses.  For	example, try
	      .am pg@end-text
	      .	 t*EM
	      ..
       if you use the ms package.

Bugs and suggestions
       Please send your	comments to the	groff mailing list <groff@gnu.org>  or
       directly	to the author.

Authors
       The  hdtbl  macro  package  was	written	 by Joachim Walsdorff <Joachim
       .Walsdorff@urz.uni-heidelberg.de>.

See also
       groff(1)
	      provides an overview of GNU roff and details how to invoke groff
	      at the command line.

       groff(7)
	      summarizes the roff language and GNU extensions to it.

       tbl(1) describes	the traditional	roff preprocessor for tables.

groff 1.23.0			  2 July 2023			groff_hdtbl(7)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=groff_hdtbl&sektion=7&manpath=FreeBSD+Ports+14.3.quarterly>

home | help