Yodl tables(7) Your Own Document Language Yodl tables(7)

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.

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’.
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’.
Column elements are defined by the `tc, tn, tac,’ and `tnac’ macros. Each of these macros recognizes `attrib’.
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)\  
    )\  
)\
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.
    )\  
)\
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
    )\ 
)\
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:

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 )\ 
)\
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)\ 
    )\ 
)
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.
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.

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).
1996-2021 yodl_4.03.03