groff_hdtbl man page on AIX

Man page or keyword search:  
man Server   4752 pages
apropos Keyword Search (all sections)
Output format
AIX logo
[printable version]

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, 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's full macro capabilities are available.  On the other hand,  ta‐
       ble  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
       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	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

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

       .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’ 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
       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 Hel‐
	      vetica-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  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.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 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 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 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 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.

Groff Version 1.21	       31 December 2010			GROFF_HDTBL(7)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server AIX

List of man pages available for AIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net