[BACK]Return to tbl.7 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/tbl.7, Revision 1.38

1.38    ! schwarze    1: .\" $Id: tbl.7,v 1.37 2021/09/18 12:34:27 schwarze Exp $
1.1       kristaps    2: .\"
1.12      schwarze    3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.33      schwarze    4: .\" Copyright (c) 2014,2015,2017,2018,2019 Ingo Schwarze <schwarze@openbsd.org>
1.1       kristaps    5: .\"
                      6: .\" Permission to use, copy, modify, and distribute this software for any
                      7: .\" purpose with or without fee is hereby granted, provided that the above
                      8: .\" copyright notice and this permission notice appear in all copies.
                      9: .\"
                     10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     12: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     16: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
                     17: .\"
1.38    ! schwarze   18: .Dd $Mdocdate: September 18 2021 $
1.1       kristaps   19: .Dt TBL 7
                     20: .Os
                     21: .Sh NAME
                     22: .Nm tbl
                     23: .Nd tbl language reference for mandoc
                     24: .Sh DESCRIPTION
                     25: The
                     26: .Nm tbl
1.28      schwarze   27: language formats tables.
1.1       kristaps   28: It is used within
                     29: .Xr mdoc 7
                     30: and
                     31: .Xr man 7
1.28      schwarze   32: pages.
1.1       kristaps   33: This manual describes the subset of the
                     34: .Nm
                     35: language accepted by the
                     36: .Xr mandoc 1
                     37: utility.
                     38: .Pp
1.28      schwarze   39: Each table is started with a
1.1       kristaps   40: .Xr roff 7
1.28      schwarze   41: .Ic \&TS
                     42: macro, consist of at most one line of
                     43: .Sx Options ,
                     44: one or more
1.2       kristaps   45: .Sx Layout
1.28      schwarze   46: lines, one or more
                     47: .Sx Data
                     48: lines, and ends with a
                     49: .Ic \&TE
                     50: macro.
1.1       kristaps   51: All input must be 7-bit ASCII.
1.2       kristaps   52: .Ss Options
1.28      schwarze   53: If the first input line of a table ends with a semicolon, it contains
                     54: case-insensitive options separated by spaces, tabs, or commas.
                     55: Otherwise, it is interpreted as the first
1.2       kristaps   56: .Sx Layout
1.28      schwarze   57: line.
                     58: .Pp
                     59: The following options are available.
                     60: Some of them require arguments enclosed in parentheses:
1.1       kristaps   61: .Bl -tag -width Ds
1.23      schwarze   62: .It Cm allbox
                     63: Draw a single-line box around each table cell.
                     64: .It Cm box
                     65: Draw a single-line box around the table.
                     66: For GNU compatibility, this may also be invoked with
                     67: .Cm frame .
1.1       kristaps   68: .It Cm center
1.23      schwarze   69: Center the table instead of left-adjusting it.
                     70: For GNU compatibility, this may also be invoked with
1.1       kristaps   71: .Cm centre .
1.23      schwarze   72: .It Cm decimalpoint
                     73: Use the single-character argument as the decimal point with the
                     74: .Cm n
                     75: layout key.
                     76: This is a GNU extension.
1.1       kristaps   77: .It Cm delim
1.23      schwarze   78: Use the two characters of the argument as
                     79: .Xr eqn 7
                     80: delimiters.
                     81: Currently unsupported.
1.1       kristaps   82: .It Cm doublebox
                     83: Draw a double-line box around the table.
1.23      schwarze   84: For GNU compatibility, this may also be invoked with
1.1       kristaps   85: .Cm doubleframe .
1.23      schwarze   86: .It Cm expand
                     87: Increase the width of the table to the current line length.
                     88: Currently ignored.
1.1       kristaps   89: .It Cm linesize
1.23      schwarze   90: Draw lines with the point size given by the unsigned integer argument.
                     91: Currently ignored.
1.1       kristaps   92: .It Cm nokeep
1.23      schwarze   93: Allow page breaks within the table.
                     94: This is a GNU extension and currently ignored.
1.1       kristaps   95: .It Cm nospaces
1.23      schwarze   96: Ignore leading and trailing spaces in data cells.
1.36      schwarze   97: This is a GNU extension.
1.23      schwarze   98: .It Cm nowarn
                     99: Suppress warnings about tables exceeding the current line length.
                    100: This is a GNU extension and currently ignored.
                    101: .It Cm tab
                    102: Use the single-character argument as a delimiter between data cells.
1.28      schwarze  103: By default, the horizontal tabulator character is used.
1.1       kristaps  104: .El
1.2       kristaps  105: .Ss Layout
1.28      schwarze  106: The table layout follows an
1.2       kristaps  107: .Sx Options
1.28      schwarze  108: line or a
                    109: .Xr roff 7
                    110: .Ic \&TS
                    111: or
                    112: .Ic \&T&
                    113: macro.
                    114: Each layout line specifies how one line of
                    115: .Sx Data
                    116: is formatted.
                    117: The last layout line ends with a full stop.
                    118: It also applies to all remaining data lines.
                    119: Multiple layout lines can be joined by commas on a single physical
                    120: input line.
                    121: .Pp
                    122: Each layout line consists of one or more layout cell specifications,
                    123: optionally separated by whitespace.
                    124: The following case-insensitive key characters start a new cell
                    125: specification:
1.19      schwarze  126: .Bl -tag -width 2n
1.1       kristaps  127: .It Cm c
1.28      schwarze  128: Center the string in this cell.
1.1       kristaps  129: .It Cm r
1.28      schwarze  130: Right-justify the string in this cell.
1.1       kristaps  131: .It Cm l
1.28      schwarze  132: Left-justify the string in this cell.
1.1       kristaps  133: .It Cm n
1.6       kristaps  134: Justify a number around its last decimal point.
1.28      schwarze  135: If no decimal point is found in the number,
                    136: it is assumed to trail the number.
1.1       kristaps  137: .It Cm s
1.12      schwarze  138: Horizontally span columns from the last
1.28      schwarze  139: .Pf non- Cm s
                    140: layout cell.
                    141: It is an error if a column span follows a
                    142: .Cm _
1.8       kristaps  143: or
1.28      schwarze  144: .Cm =
                    145: cell, or comes first on a layout line.
                    146: The combined cell as a whole consumes only one cell
                    147: of the corresponding data line.
1.1       kristaps  148: .It Cm a
1.28      schwarze  149: Left-justify a string and pad with one space.
1.30      schwarze  150: .It Cm \(ha
1.12      schwarze  151: Vertically span rows from the last
1.30      schwarze  152: .Pf non- Cm \(ha
1.28      schwarze  153: layout cell.
                    154: It is an error to invoke a vertical span on the first layout line.
                    155: Unlike a horizontal span, a vertical span consumes a data cell
                    156: and discards the content.
                    157: .It Cm _
                    158: Draw a single horizontal line in this cell.
                    159: This consumes a data cell and discards the content.
                    160: It may also be invoked with
                    161: .Cm \- .
1.1       kristaps  162: .It Cm =
1.28      schwarze  163: Draw a double horizontal line in this cell.
                    164: This consumes a data cell and discards the content.
1.1       kristaps  165: .El
                    166: .Pp
1.28      schwarze  167: Each cell key may be followed by zero or more of the following
                    168: case-insensitive modifiers:
1.19      schwarze  169: .Bl -tag -width 2n
                    170: .It Cm b
1.28      schwarze  171: Use a bold font for the contents of this cell.
1.24      schwarze  172: .It Cm d
1.28      schwarze  173: Move content down to the last row of this vertical span.
1.24      schwarze  174: Currently ignored.
1.20      schwarze  175: .It Cm e
                    176: Make this column wider to match the maximum width
                    177: of any other column also having the
                    178: .Cm e
                    179: modifier.
1.19      schwarze  180: .It Cm f
1.35      schwarze  181: The next one or two characters select the font to use for this cell.
                    182: One-character font names must be followed by a blank or period.
1.19      schwarze  183: See the
                    184: .Xr roff 7
1.35      schwarze  185: manual for supported font names.
1.19      schwarze  186: .It Cm i
1.28      schwarze  187: Use an italic font for the contents of this cell.
1.24      schwarze  188: .It Cm m
                    189: Specify a cell start macro.
                    190: This is a GNU extension and currently unsupported.
                    191: .It Cm p
                    192: Set the point size to the following unsigned argument,
                    193: or change it by the following signed argument.
                    194: Currently ignored.
                    195: .It Cm v
                    196: Set the vertical line spacing to the following unsigned argument,
                    197: or change it by the following signed argument.
                    198: Currently ignored.
                    199: .It Cm t
1.28      schwarze  200: Do not vertically center content in this vertical span,
                    201: leave it in the top row.
1.24      schwarze  202: Currently ignored.
                    203: .It Cm u
1.28      schwarze  204: Move cell content up by half a table row.
1.24      schwarze  205: Currently ignored.
                    206: .It Cm w
1.28      schwarze  207: Specify a minimum column width.
1.20      schwarze  208: .It Cm x
                    209: After determining the width of all other columns, distribute the
                    210: rest of the line length among all columns having the
                    211: .Cm x
                    212: modifier.
                    213: .It Cm z
                    214: Do not use this cell for determining the width of this column.
1.28      schwarze  215: .It Cm \&|
                    216: Draw a single vertical line to the right of this cell.
                    217: .It Cm ||
                    218: Draw a double vertical line to the right of this cell.
1.19      schwarze  219: .El
1.5       kristaps  220: .Pp
1.28      schwarze  221: If a modifier consists of decimal digits,
                    222: it specifies a minimum spacing in units of
                    223: .Cm n
                    224: between this column and the next column to the right.
                    225: The default is 3.
                    226: If there is a vertical line, it is drawn inside the spacing.
1.2       kristaps  227: .Ss Data
1.28      schwarze  228: The data section follows the last
                    229: .Sx Layout
                    230: line.
                    231: Each data line consists of one or more data cells, delimited by
1.1       kristaps  232: .Cm tab
1.28      schwarze  233: characters.
                    234: .Pp
1.30      schwarze  235: If a data cell contains only the two bytes
                    236: .Ql \e\(ha ,
                    237: the cell above spans to this row, as if the layout specification
                    238: of this cell were
                    239: .Cm \(ha .
                    240: .Pp
                    241: If a data cell contains only the single character
1.28      schwarze  242: .Ql _
                    243: or
                    244: .Ql = ,
                    245: a single or double horizontal line is drawn across the cell,
                    246: joining its neighbours.
1.32      schwarze  247: If a data cell contains only the two character sequence
1.28      schwarze  248: .Ql \e_
                    249: or
                    250: .Ql \e= ,
                    251: a single or double horizontal line is drawn inside the cell,
                    252: not joining its neighbours.
                    253: If a data line contains nothing but the single character
                    254: .Ql _
1.1       kristaps  255: or
1.28      schwarze  256: .Ql = ,
                    257: a horizontal line across the whole table is inserted
                    258: without consuming a layout row.
                    259: .Pp
                    260: In place of any data cell, a text block can be used.
                    261: It starts with
                    262: .Ic \&T{
                    263: at the end of a physical input line.
                    264: Input line breaks inside the text block
                    265: neither end the text block nor its data cell.
                    266: It only ends if
                    267: .Ic \&T}
                    268: occurs at the beginning of a physical input line and is followed
                    269: by an end-of-cell indicator.
                    270: If the
                    271: .Ic \&T}
                    272: is followed by the end of the physical input line, the text block,
                    273: the data cell, and the data line ends at this point.
                    274: If the
                    275: .Ic \&T}
                    276: is followed by the
                    277: .Cm tab
                    278: character, only the text block and the data cell end,
                    279: but the data line continues with the data cell following the
                    280: .Cm tab
                    281: character.
1.1       kristaps  282: If
1.28      schwarze  283: .Ic \&T}
                    284: is followed by any other character, it does not end the text block,
                    285: which instead continues to the following physical input line.
                    286: .Sh EXAMPLES
                    287: String justification and font selection:
                    288: .Bd -literal -offset indent
                    289: \&.TS
                    290: rb c  lb
                    291: r  ci l.
                    292: r      center  l
                    293: ri     ce      le
                    294: right  c       left
                    295: \&.TE
                    296: .Ed
                    297: .Bd -filled -offset indent
                    298: .TS
                    299: rb c  lb
                    300: r  ci l.
                    301: r      center  l
                    302: ri     ce      le
                    303: right  c       left
                    304: .TE
                    305: .Ed
                    306: .Pp
                    307: Some ports in
                    308: .Ox 6.1
                    309: to show number alignment and line drawing:
                    310: .Bd -literal -offset indent
                    311: \&.TS
                    312: box tab(:);
                    313: r| l
                    314: r  n.
                    315: software:version
                    316: _
                    317: AFL:2.39b
                    318: Mutt:1.8.0
                    319: Ruby:1.8.7.374
                    320: TeX Live:2015
                    321: \&.TE
                    322: .Ed
                    323: .Bd -filled -offset indent
                    324: .TS
                    325: box tab(:);
                    326: r| l
                    327: r  n.
                    328: software:version
                    329: _
                    330: AFL:2.39b
                    331: Mutt:1.8.0
                    332: Ruby:1.8.7.374
1.31      schwarze  333: TeX Live:2015
1.28      schwarze  334: .TE
                    335: .Ed
                    336: .sp 2v
                    337: Spans and skipping width calculations:
                    338: .Bd -literal -offset indent
                    339: \&.TS
                    340: box tab(:);
                    341: lz  s | rt
1.30      schwarze  342: lt| cb| \(ha
                    343: \(ha | rz  s.
1.28      schwarze  344: left:r
                    345: l:center:
                    346: :right
                    347: \&.TE
                    348: .Ed
                    349: .Bd -filled -offset indent
                    350: .TS
                    351: box tab(:);
                    352: lz  s | rt
                    353: lt| cb| ^
                    354: ^ | rz  s.
                    355: left:r
                    356: l:center:
                    357: :right
                    358: .TE
                    359: .Ed
                    360: .sp 2v
                    361: Text blocks, specifying spacings and specifying and equalizing
                    362: column widths, putting lines into individual cells, and overriding
                    363: .Cm allbox :
                    364: .Bd -literal -offset indent
                    365: \&.TS
                    366: allbox tab(:);
                    367: le le||7 lw10.
                    368: The fourth line:_:line 1
                    369: of this column:=:line 2
1.38    ! schwarze  370: determines:\e_:line 3
1.28      schwarze  371: the column width.:T{
                    372: This text is too wide to fit into a column of width 17.
                    373: T}:line 4
                    374: T{
                    375: No break here.
                    376: T}::line 5
                    377: \&.TE
                    378: .Ed
                    379: .Bd -filled -offset indent
                    380: .TS
                    381: allbox tab(:);
                    382: le le||7 lw10.
                    383: The fourth line:_:line 1
                    384: of this column:=:line 2
                    385: determines:\_:line 3
                    386: the column width.:T{
                    387: This text is too wide to fit into a column of width 17.
                    388: T}:line 4
                    389: T{
                    390: No break here.
                    391: T}::line 5
                    392: .TE
                    393: .Ed
                    394: .sp 2v
                    395: These examples were constructed to demonstrate many
                    396: .Nm
                    397: features in a compact way.
1.34      schwarze  398: In real manual pages, keep tables as simple as possible.
                    399: They usually look better, are less fragile, and are more portable.
1.1       kristaps  400: .Sh COMPATIBILITY
                    401: The
                    402: .Xr mandoc 1
1.26      schwarze  403: implementation of
                    404: .Nm
                    405: doesn't support
                    406: .Xr mdoc 7
                    407: and
                    408: .Xr man 7
                    409: macros and
                    410: .Xr eqn 7
                    411: equations inside tables.
1.1       kristaps  412: .Sh SEE ALSO
                    413: .Xr mandoc 1 ,
1.3       kristaps  414: .Xr man 7 ,
1.1       kristaps  415: .Xr mandoc_char 7 ,
1.3       kristaps  416: .Xr mdoc 7 ,
                    417: .Xr roff 7
1.1       kristaps  418: .Rs
                    419: .%A M. E. Lesk
1.37      schwarze  420: .%T Tbl \(em A Program to Format Tables
1.1       kristaps  421: .%D June 11, 1976
                    422: .Re
                    423: .Sh HISTORY
                    424: The tbl utility, a preprocessor for troff, was originally written by M.
                    425: E. Lesk at Bell Labs in 1975.
                    426: The GNU reimplementation of tbl, part of the groff package, was released
                    427: in 1990 by James Clark.
                    428: A standalone tbl implementation was written by Kristaps Dzonsons in
                    429: 2010.
1.29      schwarze  430: This formed the basis of the implementation that first appeared in
                    431: .Ox 4.9
                    432: as a part of the
1.1       kristaps  433: .Xr mandoc 1
                    434: utility.
                    435: .Sh AUTHORS
1.14      kristaps  436: This
1.1       kristaps  437: .Nm
                    438: reference was written by
1.28      schwarze  439: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
                    440: and
                    441: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
1.33      schwarze  442: .Sh BUGS
                    443: In
                    444: .Fl T
                    445: .Cm utf8
                    446: output mode, heavy lines are drawn instead of double lines.
                    447: This cannot be improved because the Unicode standard only provides
                    448: an incomplete set of box drawing characters with double lines,
                    449: whereas it provides a full set of box drawing characters
                    450: with heavy lines.
                    451: It is unlikely this can be improved in the future because the box
                    452: drawing characters are already marked in Unicode as characters
                    453: intended only for backward compatibility with legacy systems,
                    454: and their use is not encouraged.
                    455: So it seems unlikely that the missing ones might get added in the future.

CVSweb