GROFF_HDTBL(7)                                   GROFF_HDTBL(7)



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 syn-
       tax 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 imple-
       mented 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 ta-
       ble  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 con-
       structed 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  possi-
       ble 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 prede-
       fined by groff or colors defined by the  user  with  the
       .defcolor  request.   Argument values d are decimal num-
       bers 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 sep-
                            arator 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  verti-
                            cal  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 ta-
                            ble.
                            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 imme-
                 diately, 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  con-
              tents
              arguments:
                     hold   Prevent   the   table   from  being
                            printed until it is freed by  call-
                            ing  the macro .t*free.  This argu-
                            ment 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 docu-
       mented 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' argu-
              ment.  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': cen-
              tered 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  for-
              matting  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 dou-
              ble  separator line.  `vl=' (no value): no verti-
              cal 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 exam-
       ple, 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.



Groff Version 1.20       5 January 2009          GROFF_HDTBL(7)
