Provided by: groff_1.20.1-10_i386 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(@MAN1EXT) 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

       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.

       hdtbl has built-in page header and page footer macros, HM and  BM.   If
       they  interfere  with  your  own  header  and footer macros, simply say
       .rm HM and .rm BM to remove them.

AUTHOR

       Joachim Walsdorff

BUGS AND SUGGESTIONS

       Please send your commments to the groff mailing list or directly to the
       author.