YODLTABLES(7)

📦
version 4.05.02 · 6 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay bestie, welcome to the Yodl tables(7) page 💖 this is all about yodltables — literally Yodl's table support. tables!! in Yodl!! iconic.

✨ SYNOPSIS ✨

so here's the tea 🫖 tables are preferably defined using the tbl macro, although the table macro remains available (it's still around, bestie, it's just not the main character anymore). 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. iykyk.

🌸 DESCRIPTION 🌸

  • To start a table you use the tbl macro, periodt. It is currently available for html, man/ms, latex and txt conversions. When you specify tbl as an argument of the center macro, the resulting table will be centered on the page or the html screen — main character energy fr fr. In text mode, centering is simulated by starting each row with eight blank space characters (yes, literally eight).

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). no cap, this one bites people.

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 💅

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

🎀 SUPPORT MACROS 🎀

Okay so there are two support macros and they're both little helpers: twrap wraps the contents of a cell in a text block when you're converting to man, and tao (table alignment override) overrides a cell's alignment specification for one specific conversion type. Cute, right? 💅

🌸 The twrap macro 🌸

Bestie, listen: the twrap macro is only interpreted when converting to man. It expects one numeric argument. If it's zero then the table's cells are used as specified; if it's non-zero then the table's cells get 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, that long line will continue on one physical line, disproportionally widening that cell's column. And when newlines are used in cell contents, and horizontal lines are used, the resulting table may set the horizontal lines at unexpected rows. 🙈

When you do request 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. So it's giving "sticky setting", fr fr. 💀

👑 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 expects 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. Periodt. 💅

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. Iconic.
  • 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. No freebies, bestie. 😭

🔥 SEE ALSO 🔥

yodl(1), yodlbuiltins(7), yodlconverters(1), yodlletter(7), yodlmacros(7), yodlmanpage(7), yodlpost(1), yodlstriproff(1), yodlverbinsert(1).

💀 BUGS 💀

  • -

Like… nothing? The bug list is empty and honestly? Slay. 🫶

🫶 AUTHOR 🫶

Frank B. Brokken (f.b.brokken@rug.nl).

And that's a wrap on the tables page, bestie! 💖 This whole thing is from yodl_4.05.02, dated 1996-2025, and the page itself is Yodl tables(7) — go forth and align your cells, you absolute legend. 🌸✨

📦 where this page comes from