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.
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
.
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
.
tc, tn, tac,
and tnac
macros. Each of these macros recognizes attrib
.
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)\ )\ )\
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. )\ )\
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 )\ )\
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 (partially) spanning the width of tables defined by the
tbl
macro are defined using the tline
macro. The tline
macro
expects two arguments:
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 )\ )\
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 )\
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)\ )\ )
Thet
andb
specifications can be used to respectively top- and bottom-align cells in a table row. Usuallytao
doesn't have to be used, as thetac
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.
To request a top-aligned table element of a specified width (e.g., 4 cm.) the followingtao
specification can be used:tao(latex)(NOTRANS(t{p{4cm}}))Similarly, for a center-aligned element usec{p{4cm}}
. But to align the bottom-line of a multi-line element with its neighboring cells usetao(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.
yodl(1), yodlbuiltins(7), yodlconverters(1), yodlletter(7), yodlmacros(7), yodlmanpage(7), yodlpost(1), yodlstriproff(1), yodlverbinsert(1).
-
Frank B. Brokken (f.b.brokken@rug.nl).