Provided by: yodl_4.03.02-2_amd64 bug

NAME

       yodltables - Yodl’s table support

SYNOPSIS

       Tables  are  preferably  defined using the `tbl’ macro, although the `table’ macro remains
       available. The macros that are used in  combination  with  `tbl’  are  described  in  this
       man-page  and  also in the yodlmacros(7) man-page. The macros that are used in combination
       with the `table’ macros are described in the yodlmacros(7) man-page only.

DESCRIPTION

       o      To start a table the `tbl’ macro is used. It  is  currently  available  for  `html,
              man/ms,  latex’  and `txt’ conversions. When specifying `tbl’ as an argument of the
              `center’ macro, the resulting table will be centered on the page or html screen. In
              text  mode  centering  is  simulated  by  starting  each row with eight blank space
              characters.

              Its first argument defines the alignment of the information in the table’s columns,
              and  is  used  by all conversions except `txt’. Use `l’ for left-alignment, `c’ for
              centered-alignment and `r’ for right-alignment. Individual cells of the  table  may
              override these default settings using the macros `tac’ and `tnac’.

              Its  second  argument  defines  the contents of the table consisting of rows (using
              `tr’), and horizontal lines (using `tline’), which may extend over the  full  table
              width  or  may  cover  one  or more individual columns. With `txt’ conversion rough
              approximations of horizontal lines are used.

              When defining tables it is advised to clearly layout the  table  specification.  To
              avoid  inadvertently  introducing  new  lines  lines  should end in a backslash (or
              comment).

              Example:

              tbl(lcr)(\// 3 columns, resp. left, center and right aligned
                  \// contents go here
              )\

              The macro `tbl’ recognizes `attrib’.

       o      Rows of a table are defined  by  the  `tr’-macro.  It  expects  one  argument:  the
              contents  of the row, defining the row’s column elements.  Instead of rows defining
              column elements (partial) horizontal lines may be inserted. The  `tline’  macro  is
              used for that (see below).

              Example:

              tbl(lcr)(\
                  tr(\//              1st row
                      \// row elements go here
                  )\
                  tr(\//              2nd row
                      \// row elements go here
                  )\
              )\

              The macro `tr’ recognizes `attrib’.

       o      Column  elements are defined by the `tc, tn, tac,’ and `tnac’ macros. Each of these
              macros recognizes `attrib’.

       o      The `tc’ macro defines the contents of column element: its order number in a row is
              aligned as specified by the corresponding letter in `tbl’s’ first argument. E.g.,

              tbl(lcr)(\
                  tr(\
                     tc(left aligned)\
                     tc(centered)\
                     tc(right aligned)\
                  )\
              )\

       o      The  `tnc’  macro defines the contents of column element. It expects two arguments:
              the number of columns covered by this macro, and the contents  of  those  elements.
              The contents are centered in the rows covered by the `tnc’ macro. E.g.,

              tbl(lcr)(\
                  tr(\
                     tc(left aligned)\
                     tnc(2)(centered)\//    spans columns 2 and 3.
                  )\
              )\

       o      The  `tac’  macro  defines  the  contents  of  column  element, defining a specific
              alignment for its contents. It expects two arguments: the alignment to be used  for
              this element and the element’s contents.

              At  most  two  alignment specification characters are used: a specification for the
              horizontal alignment (one of c, l, r (centered, left-aligned, right-aligned)) and a
              specification  for  the  vertical  alignment  (one  of  t,  b  (vertical  top-  and
              bottom-alignment)) (not all conversion types  may  support  all  alignment  types).
              Specifications  other  than  c,  l,  r,  b,  and  t are ignored. If only a vertical
              alignment type is specified, then usually  the  horizontal  centered  alignment  is
              used.  As  a  rule  of  thumb  always also specify a horizontal alignment type if a
              vertical  alignment  type  is  specified.  The  result  of  specifying  conflicting
              alignment types (e.g., `lr’ or `tb’) is not defined.

              Vertical alignment is handled differently by different conversion types. E.g., when
              table  cells  span  multiple  lines  then  LaTeX  uses   the   vertical   alignment
              specification  for that cell to align the neighboring cells: with LaTeX conversions
              the following aligns `rows’ and `second’:

              tac(b)(two+nl()rows)
              tc(second)

              but with html-conversions `second’ is vertically center-aligned: in  between  `two’
              and  `rows’.  Bottom line: provide each column element in a row that you want to be
              top- or bottom-aligned with a `t’ or `b’ specification.

              When using man-conversions the situation is complex in that bottom  alignment  does
              not  appear  to  be  supported.  Moreover,  unless  long lines are wrapped in `text
              blocks’ (see below at `twrap’) there won’t be any wrapping of long lines. The  same
              holds  true  for  LaTeX  conversions,  but  with  LaTeX  columns may be given fixed
              physical widths, resulting in  automatically  wrapping  long  lines.  Also,  bottom
              alignment  appears not to be supported when converting to man. At this point bottom
              alignment when converting to man is realized  by  defining  a  separate  table  row
              containing  the last contents of a long line. This may require some iterations. The
              specification could then look somewhat like this (again: for `twrap’ see below):

              tbl(lr)(\
                  tr(\
                      twrap(1)\
                      tac(lb)(Lorem ipsum dolor sit amet,
                              consectetur adipiscing elit, sed
                              do eiusmod tempor incididunt ut
                              labore et dolore magna aliqua.)\
                      twrap(0)\
                      tc()\//           empty cell
                  )\
                  tr(\//                simulated bottom alignment,
                      tac(l)(Ut enim ad minim veniam)\
                      tac(rb)(left)\
                  )\
              )\

              In some cases  (e.g.,  using  LaTeX  conversions  where  a  column  width  must  be
              specified) more elaborate alignment specifications are required. For that the `tao’
              (table alignment override) and `twrap’ macros are available (see below).

              E.g.,

              tbl(lcr)(\
                  tr(\
                     tc(left aligned)\
                     tac(l)(left aligned)\// left alignment instead
                                         \// of centered
                     tac(rb)(left+nl()aligned)\// right-bottom
                                         \// alignment
                  )\
              )\

       o      The `tnac’ macro defines the  contents  of  column  element,  defining  a  specific
              alignment  for  its  contents.  It  expects  three arguments: the number of columns
              spanned by the contents of this macro, the alignment to be used and  the  element’s
              contents.

              The  alignment  specifications  and  considerations  are the same as with the `tac’
              macro: see `tac’s’ description for the details.

HORIZONTAL LINES

       Horizontal lines (partially) spanning the width of tables defined by the `tbl’  macro  are
       defined using the `tline’ macro. The `tline’ macro expects two arguments:

       o      If  both arguments are specified, then the first argument defines the column number
              (so, not the column offset!) where a horizontal line must  start,  and  the  second
              argument  defines  the  column  number  through  where  the  horizontal line should
              continue. If a series of `tline’ macros is specified then the first argument of the
              first  `tline’  macro  call  must  be  at  least 1; the second argument of the last
              `tline’ macro call must be at most equal to  the  table’s  number  of  columns.  In
              addition  the  second  arguments  of  `tline’ calls must at least be equal to their
              first arguments, and the first arguments of subsequent `tline’  calls  must  exceed
              the  value  of the second argument of the preceding `tline’ macro call. A series of
              (at least one) `line’ calls in which both arguments are specified must be  followed
              by a `tline’ call with two empty arguments. For example:

              tbl(ccccc)(\
                  tr(... row contents )\
                  tline(1)(1)\//    horizontal line at column 1
                  tline(3)(4)\//    horizontal line at columns 3 and 4
                  tline()()\//      now defined.
                  tr(... row contents )\
              )\

       o      Except  for ending a series of `tline’ calls in which both arguments are specified,
              a `tline’ call not specifying its second argument sets a line over the  full  width
              of  the  table.  In  that  case,  when  converting  to txt a line of 60 minus (`-’)
              characters is written. If another number  of  minus  characters  is  required  then
              specify  the  required  number  as  `tline’s’  first  argument.  When  using  other
              conversion types `tline’s’ first argument is ignored  if  its  second  argument  is
              empty.  Here  is  the  previous  example again, this time setting a horizontal line
              before and after the table’s contents:

              tbl(ccccc)(\
                  tline()()\//      horizontal line spanning the full width
                  tr(... row contents )\
                  tline(1)(1)\//    horizontal line at column 1
                  tline(3)(4)\//    horizontal line at columns 3 and 4
                  tline()()\//      now defined.
                  tr(... row contents )\
                  tline()()\//      horizontal line spanning the full width
              )\

SUPPORT MACROS

              Two support macros are available: `twrap’ for wrapping the contents of a cell in  a
              `text  block’  when  converting  to  man,  and `tao’ (table alignment override) for
              overriding a cell’s alignment specification for a specific conversion type.

              The twrap macro

              The `twrap’ macro is only interpreted  when  converting  to  man.  It  expects  one
              numeric argument. If zero then the table’s cells are used as specified; if non-zero
              then the table’s cells are wrapped in groff/troff text blocks.

              If no text block is specified (i.e., `twrap(0)’ (the default) is in effect)  and  a
              cell  contains  a  long  line  the  long  line  will continue on one physical line,
              disproportionally widening that cell’s column; when using newlines are used in cell
              contents,  and horizontal lines are used the resulting table may set the horizontal
              lines at unexpected rows.

              When requesting text  blocks  (i.e.,  `twrap(1)’  was  specified)  long  lines  are
              automatically split up in lines of reasonable widths, and they will be left-aligned
              in their columns. Those long  lines  may  also  contain  explicit  newline  macros,
              forcing new lines at user-defined positions.

              Once a `twrap’ has been called, it remains in effect until the next `twrap’ call is
              encountered.

              The tao macro

              The `tao’ macro (table alignment  override)  is  used  to  override  the  alignment
              specification  that  would otherwise be used for the next table element. It is only
              active for the next `tc, tnc, tac,’ or `tnac’ call. It expect  two  arguments:  its
              first  argument  defines the conversion type for which the override should be used,
              its second argument defines the alignment specification to use.

              Here are some examples:

              tbl(lr)(\
                  tr(\
                      tc(left aligned)\
                      tc(right aligned)\
                  )\
                  tr(\
                      tao(html)(c)\
                        tc(left aligned, except with html: then centered)\
                      tao(latex)(l)tao(man)(l)\
                        tac(c)(centered, but left aligned for latex and man)\
                  )\
              )

       o      Details when converting to html:
              The `t’ and `b’ specifications can be used to respectively  top-  and  bottom-align
              cells  in  a  table  row. Usually `tao’ doesn’t have to be used, as the `tac’ macro
              already provides  facilities  for  aligning  cell  contents.  E.g.,  `tac(cb)(...)’
              centers  the  contents,  and aligns its bottom line with the remaining cells on its
              line.

       o      Details when converting to LaTeX:
              To request a top-aligned table element of a  specified  width  (e.g.,  4  cm.)  the
              following `tao’ specification can be used:

              tao(latex)(NOTRANS(t{p{4cm}}))

              Similarly,  for  a  center-aligned  element  use  `c{p{4cm}}’.  But  to  align  the
              bottom-line of a multi-line element with its neighboring cells use

              tao(latex)(NOTRANS(b{b{4cm}}))

              (combinations are also possible: if one cell uses top alignment, and another bottom
              alignment,  then  the top line of the former cell and the bottom line of the latter
              cell appear on the same physical line).

                     Alternatively, instead of using fixed widths explicit newlines can be  used.
                     In  that  case,  a specification like `tao(latex)(rb)’ will align its bottom
                     line with the other cells in its row, while right-aligning its contents.

                     When a fixed width is specified for a cell, then other cells in  its  column
                     not  automatically  also  use  that  width. If other cells should also use a
                     fixed width they must explicitly specify their widths.

SEE ALSO

              yodl(1),   yodlbuiltins(7),   yodlconverters(1),   yodlletter(7),    yodlmacros(7),
              yodlmanpage(7), yodlpost(1), yodlstriproff(1), yodlverbinsert(1).

BUGS

              -

AUTHOR

              Frank B. Brokken (f.b.brokken@rug.nl).