yodltables - Yodl’s table support
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.
- 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 (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
)\
- 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.
- Frank B. Brokken (f.b.brokken@rug.nl).