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

Annotation of mandoc/tbl.7, Revision 1.29

1.29    ! schwarze    1: .\"    $Id: tbl.7,v 1.28 2017/06/28 00:59:57 schwarze Exp $
1.1       kristaps    2: .\"
1.12      schwarze    3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.27      schwarze    4: .\" Copyright (c) 2014, 2015, 2017 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.29    ! schwarze   18: .Dd $Mdocdate: June 28 2017 $
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.
                     97: This is a GNU extension and currently ignored.
                     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.1       kristaps  150: .It Cm ^
1.12      schwarze  151: Vertically span rows from the last
1.28      schwarze  152: .Pf non- Cm ^
                    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.28      schwarze  181: The next character selects the font to use for this cell.
1.19      schwarze  182: See the
                    183: .Xr roff 7
                    184: manual for supported one-character font names.
                    185: .It Cm i
1.28      schwarze  186: Use an italic font for the contents of this cell.
1.24      schwarze  187: .It Cm m
                    188: Specify a cell start macro.
                    189: This is a GNU extension and currently unsupported.
                    190: .It Cm p
                    191: Set the point size to the following unsigned argument,
                    192: or change it by the following signed argument.
                    193: Currently ignored.
                    194: .It Cm v
                    195: Set the vertical line spacing to the following unsigned argument,
                    196: or change it by the following signed argument.
                    197: Currently ignored.
                    198: .It Cm t
1.28      schwarze  199: Do not vertically center content in this vertical span,
                    200: leave it in the top row.
1.24      schwarze  201: Currently ignored.
                    202: .It Cm u
1.28      schwarze  203: Move cell content up by half a table row.
1.24      schwarze  204: Currently ignored.
                    205: .It Cm w
1.28      schwarze  206: Specify a minimum column width.
1.20      schwarze  207: .It Cm x
                    208: After determining the width of all other columns, distribute the
                    209: rest of the line length among all columns having the
                    210: .Cm x
                    211: modifier.
                    212: .It Cm z
                    213: Do not use this cell for determining the width of this column.
1.28      schwarze  214: .It Cm \&|
                    215: Draw a single vertical line to the right of this cell.
                    216: .It Cm ||
                    217: Draw a double vertical line to the right of this cell.
1.19      schwarze  218: .El
1.5       kristaps  219: .Pp
1.28      schwarze  220: If a modifier consists of decimal digits,
                    221: it specifies a minimum spacing in units of
                    222: .Cm n
                    223: between this column and the next column to the right.
                    224: The default is 3.
                    225: If there is a vertical line, it is drawn inside the spacing.
1.2       kristaps  226: .Ss Data
1.28      schwarze  227: The data section follows the last
                    228: .Sx Layout
                    229: line.
                    230: Each data line consists of one or more data cells, delimited by
1.1       kristaps  231: .Cm tab
1.28      schwarze  232: characters.
                    233: .Pp
                    234: If a data cells contains only the single character
                    235: .Ql _
                    236: or
                    237: .Ql = ,
                    238: a single or double horizontal line is drawn across the cell,
                    239: joining its neighbours.
                    240: If a data cells contains only the two character sequence
                    241: .Ql \e_
                    242: or
                    243: .Ql \e= ,
                    244: a single or double horizontal line is drawn inside the cell,
                    245: not joining its neighbours.
                    246: If a data line contains nothing but the single character
                    247: .Ql _
1.1       kristaps  248: or
1.28      schwarze  249: .Ql = ,
                    250: a horizontal line across the whole table is inserted
                    251: without consuming a layout row.
                    252: .Pp
                    253: In place of any data cell, a text block can be used.
                    254: It starts with
                    255: .Ic \&T{
                    256: at the end of a physical input line.
                    257: Input line breaks inside the text block
                    258: neither end the text block nor its data cell.
                    259: It only ends if
                    260: .Ic \&T}
                    261: occurs at the beginning of a physical input line and is followed
                    262: by an end-of-cell indicator.
                    263: If the
                    264: .Ic \&T}
                    265: is followed by the end of the physical input line, the text block,
                    266: the data cell, and the data line ends at this point.
                    267: If the
                    268: .Ic \&T}
                    269: is followed by the
                    270: .Cm tab
                    271: character, only the text block and the data cell end,
                    272: but the data line continues with the data cell following the
                    273: .Cm tab
                    274: character.
1.1       kristaps  275: If
1.28      schwarze  276: .Ic \&T}
                    277: is followed by any other character, it does not end the text block,
                    278: which instead continues to the following physical input line.
                    279: .Sh EXAMPLES
                    280: String justification and font selection:
                    281: .Bd -literal -offset indent
                    282: \&.TS
                    283: rb c  lb
                    284: r  ci l.
                    285: r      center  l
                    286: ri     ce      le
                    287: right  c       left
                    288: \&.TE
                    289: .Ed
                    290: .Bd -filled -offset indent
                    291: .TS
                    292: rb c  lb
                    293: r  ci l.
                    294: r      center  l
                    295: ri     ce      le
                    296: right  c       left
                    297: .TE
                    298: .Ed
                    299: .Pp
                    300: Some ports in
                    301: .Ox 6.1
                    302: to show number alignment and line drawing:
                    303: .Bd -literal -offset indent
                    304: \&.TS
                    305: box tab(:);
                    306: r| l
                    307: r  n.
                    308: software:version
                    309: _
                    310: AFL:2.39b
                    311: Mutt:1.8.0
                    312: Ruby:1.8.7.374
                    313: TeX Live:2015
                    314: \&.TE
                    315: .Ed
                    316: .Bd -filled -offset indent
                    317: .TS
                    318: box tab(:);
                    319: r| l
                    320: r  n.
                    321: software:version
                    322: _
                    323: AFL:2.39b
                    324: Mutt:1.8.0
                    325: Ruby:1.8.7.374
                    326: TeX Live:2015
                    327: .TE
                    328: .Ed
                    329: .sp 2v
                    330: Spans and skipping width calculations:
                    331: .Bd -literal -offset indent
                    332: \&.TS
                    333: box tab(:);
                    334: lz  s | rt
                    335: lt| cb| ^
                    336: ^ | rz  s.
                    337: left:r
                    338: l:center:
                    339: :right
                    340: \&.TE
                    341: .Ed
                    342: .Bd -filled -offset indent
                    343: .TS
                    344: box tab(:);
                    345: lz  s | rt
                    346: lt| cb| ^
                    347: ^ | rz  s.
                    348: left:r
                    349: l:center:
                    350: :right
                    351: .TE
                    352: .Ed
                    353: .sp 2v
                    354: Text blocks, specifying spacings and specifying and equalizing
                    355: column widths, putting lines into individual cells, and overriding
                    356: .Cm allbox :
                    357: .Bd -literal -offset indent
                    358: \&.TS
                    359: allbox tab(:);
                    360: le le||7 lw10.
                    361: The fourth line:_:line 1
                    362: of this column:=:line 2
                    363: determines:\_:line 3
                    364: the column width.:T{
                    365: This text is too wide to fit into a column of width 17.
                    366: T}:line 4
                    367: T{
                    368: No break here.
                    369: T}::line 5
                    370: \&.TE
                    371: .Ed
                    372: .Bd -filled -offset indent
                    373: .TS
                    374: allbox tab(:);
                    375: le le||7 lw10.
                    376: The fourth line:_:line 1
                    377: of this column:=:line 2
                    378: determines:\_:line 3
                    379: the column width.:T{
                    380: This text is too wide to fit into a column of width 17.
                    381: T}:line 4
                    382: T{
                    383: No break here.
                    384: T}::line 5
                    385: .TE
                    386: .Ed
                    387: .sp 2v
                    388: These examples were constructed to demonstrate many
                    389: .Nm
                    390: features in a compact way.
                    391: In real manual pages, keep tables as simple as possible:
                    392: Like that, they usually look better, are less fragile, and more portable.
1.1       kristaps  393: .Sh COMPATIBILITY
                    394: The
                    395: .Xr mandoc 1
1.26      schwarze  396: implementation of
                    397: .Nm
                    398: doesn't support
                    399: .Xr mdoc 7
                    400: and
                    401: .Xr man 7
                    402: macros and
                    403: .Xr eqn 7
                    404: equations inside tables.
1.1       kristaps  405: .Sh SEE ALSO
                    406: .Xr mandoc 1 ,
1.3       kristaps  407: .Xr man 7 ,
1.1       kristaps  408: .Xr mandoc_char 7 ,
1.3       kristaps  409: .Xr mdoc 7 ,
                    410: .Xr roff 7
1.1       kristaps  411: .Rs
                    412: .%A M. E. Lesk
                    413: .%T Tbl\(emA Program to Format Tables
                    414: .%D June 11, 1976
                    415: .Re
                    416: .Sh HISTORY
                    417: The tbl utility, a preprocessor for troff, was originally written by M.
                    418: E. Lesk at Bell Labs in 1975.
                    419: The GNU reimplementation of tbl, part of the groff package, was released
                    420: in 1990 by James Clark.
                    421: A standalone tbl implementation was written by Kristaps Dzonsons in
                    422: 2010.
1.29    ! schwarze  423: This formed the basis of the implementation that first appeared in
        !           424: .Ox 4.9
        !           425: as a part of the
1.1       kristaps  426: .Xr mandoc 1
                    427: utility.
                    428: .Sh AUTHORS
1.14      kristaps  429: This
1.1       kristaps  430: .Nm
                    431: reference was written by
1.28      schwarze  432: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
                    433: and
                    434: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .

CVSweb