Provided by: groff_1.21-7_amd64 bug

NAME

       groff_hdtbl - groff `hdtbl' macros for generation of tables

DESCRIPTION

       The  hdtbl  macros  consist  of  four  base and three optional macros, controlled 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's   full   macro
       capabilities are available.  On the other hand, table processing with hdtbl is much slower
       than using the tbl(1) preprocessor.  A further advantage is that the HTML-like  syntax  of
       hdtbl will be easily converted to HTML; this is not implemented yet.

USAGE

       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

       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 sufficient, 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 table  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

       Here  we  see  a  difference  to  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 another  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.

       Here 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, and it is not starting a line, it 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 arbitrary; 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  values  d  are  decimal  numbers  with  or
       without  decimal  point.   Argument  values  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 subsection.

       Most of the argument default values can be changed by the user  by  setting  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
                            separator  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 necessary 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 between 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  alignment.   ‘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.5inches 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 contents 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 settings, similar to the <TH>  and  <TD>
              HTML  tags: The contents of .TH is horizontally and vertically centered and typeset
              in boldface.

              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

       .ETB [hold]
              End of the table.

              This macro finishes a table.  It causes one of the following actions.

              ·  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
                 remaining 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 none 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’ argument 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 setting the corresponding default registers or strings, as
       documented below.  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 one of the groff font families, for example
              A for the AvantGarde fonts or HN for Helvetica-Narrow.
              Default: The font family found before the table (string ‘t*ff’).
       fst=style
              The  font  style  for the table.  One of R, I, B, 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 family 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.1inches.   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  .05inches  for single separator lines and .15inches 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
              separator  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 examples/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 automatically 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 package.  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 append this macro to the ``end'' macro of  your  document's  main  macro
       package.  For example:

              .am pg@end-text
              .  t*EM
              ..

       If you use the ms macro package.

AUTHOR

       Joachim Walsdorff ⟨Joachim.Walsdorff@urz.uni-heidelberg.de

BUGS AND SUGGESTIONS

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