Provided by: yodl_4.03.03-1_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).