Provided by: yodl_4.02.02-2_amd64 
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).