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

Annotation of mandoc/tbl.7, Revision 1.25

1.25    ! schwarze    1: .\"    $Id: tbl.7,v 1.24 2015/01/26 18:42:30 schwarze Exp $
1.1       kristaps    2: .\"
1.12      schwarze    3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.23      schwarze    4: .\" Copyright (c) 2014, 2015 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.24      schwarze   18: .Dd $Mdocdate: January 26 2015 $
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
                     27: language is a table-formatting language.
                     28: It is used within
                     29: .Xr mdoc 7
                     30: and
                     31: .Xr man 7
                     32: .Ux
                     33: manual pages.
                     34: This manual describes the subset of the
                     35: .Nm
                     36: language accepted by the
                     37: .Xr mandoc 1
                     38: utility.
                     39: .Pp
                     40: Tables within
                     41: .Xr mdoc 7
                     42: or
                     43: .Xr man 7
                     44: are enclosed by the
                     45: .Sq TS
                     46: and
                     47: .Sq TE
                     48: macro tags, whose precise syntax is documented in
                     49: .Xr roff 7 .
                     50: Tables consist of a series of options on a single line, followed by the
                     51: table layout, followed by data.
                     52: .Pp
1.22      schwarze   53: For example, the following creates a boxed table with digits centered in
1.1       kristaps   54: the cells.
                     55: .Bd -literal -offset indent
                     56: \&.TS
                     57: tab(:) box;
                     58: c5 c5 c5.
                     59: 1:2:3
                     60: 4:5:6
                     61: \&.TE
                     62: .Ed
                     63: .Pp
                     64: When formatted, the following output is produced:
                     65: .Bd -filled -offset indent -compact
                     66: .TS
                     67: tab(:) box;
                     68: c5 c5 c5.
                     69: 1:2:3
                     70: 4:5:6
                     71: .TE
                     72: .Ed
                     73: .Sh TABLE STRUCTURE
                     74: Tables are enclosed by the
                     75: .Sq TS
                     76: and
                     77: .Sq TE
                     78: .Xr roff 7
                     79: macros.
1.2       kristaps   80: A table consists of an optional single line of table
                     81: .Sx Options
                     82: terminated by a semicolon, followed by one or more lines of
                     83: .Sx Layout
                     84: specifications terminated by a period, then
                     85: .Sx Data .
1.1       kristaps   86: All input must be 7-bit ASCII.
                     87: Example:
                     88: .Bd -literal -offset indent
                     89: \&.TS
                     90: box tab(:);
                     91: c | c
                     92: | c | c.
                     93: 1:2
                     94: 3:4
                     95: \&.TE
                     96: .Ed
                     97: .Pp
                     98: Table data is
                     99: .Em pre-processed ,
                    100: that is, data rows are parsed then inserted into the underlying stream
                    101: of input data.
1.3       kristaps  102: This allows data rows to be interspersed by arbitrary
1.1       kristaps  103: .Xr roff 7 ,
                    104: .Xr mdoc 7 ,
                    105: and
                    106: .Xr man 7
                    107: macros such as
                    108: .Bd -literal -offset indent
                    109: \&.TS
                    110: tab(:);
                    111: c c c.
                    112: 1:2:3
                    113: \&.Ao
                    114: 3:2:1
                    115: \&.Ac
                    116: \&.TE
                    117: .Ed
                    118: .Pp
                    119: in the case of
                    120: .Xr mdoc 7
                    121: or
                    122: .Bd -literal -offset indent
                    123: \&.TS
                    124: tab(:);
                    125: c c c.
                    126: \&.ds ab 2
                    127: 1:\e*(ab:3
                    128: \&.I
                    129: 3:2:1
                    130: \&.TE
                    131: .Ed
                    132: .Pp
                    133: in the case of
                    134: .Xr man 7 .
1.2       kristaps  135: .Ss Options
1.23      schwarze  136: The first line of a table may contain options separated by spaces, tabs,
                    137: or commas and terminated by a semicolon.
1.1       kristaps  138: If the first line does not have a terminating semicolon, it is assumed
1.2       kristaps  139: that no options are specified and instead a
                    140: .Sx Layout
                    141: is processed.
1.23      schwarze  142: Some options require arguments enclosed by parentheses.
1.1       kristaps  143: The following case-insensitive options are available:
                    144: .Bl -tag -width Ds
1.23      schwarze  145: .It Cm allbox
                    146: Draw a single-line box around each table cell.
                    147: Currently treated as a synonym for
                    148: .Cm box .
                    149: .It Cm box
                    150: Draw a single-line box around the table.
                    151: For GNU compatibility, this may also be invoked with
                    152: .Cm frame .
1.1       kristaps  153: .It Cm center
1.23      schwarze  154: Center the table instead of left-adjusting it.
                    155: For GNU compatibility, this may also be invoked with
1.1       kristaps  156: .Cm centre .
1.23      schwarze  157: .It Cm decimalpoint
                    158: Use the single-character argument as the decimal point with the
                    159: .Cm n
                    160: layout key.
                    161: This is a GNU extension.
1.1       kristaps  162: .It Cm delim
1.23      schwarze  163: Use the two characters of the argument as
                    164: .Xr eqn 7
                    165: delimiters.
                    166: Currently unsupported.
1.1       kristaps  167: .It Cm doublebox
                    168: Draw a double-line box around the table.
1.23      schwarze  169: For GNU compatibility, this may also be invoked with
1.1       kristaps  170: .Cm doubleframe .
1.23      schwarze  171: .It Cm expand
                    172: Increase the width of the table to the current line length.
                    173: Currently ignored.
1.1       kristaps  174: .It Cm linesize
1.23      schwarze  175: Draw lines with the point size given by the unsigned integer argument.
                    176: Currently ignored.
1.1       kristaps  177: .It Cm nokeep
1.23      schwarze  178: Allow page breaks within the table.
                    179: This is a GNU extension and currently ignored.
1.1       kristaps  180: .It Cm nospaces
1.23      schwarze  181: Ignore leading and trailing spaces in data cells.
                    182: This is a GNU extension and currently ignored.
                    183: .It Cm nowarn
                    184: Suppress warnings about tables exceeding the current line length.
                    185: This is a GNU extension and currently ignored.
                    186: .It Cm tab
                    187: Use the single-character argument as a delimiter between data cells.
                    188: By default, the tab character is used.
1.1       kristaps  189: .El
1.2       kristaps  190: .Ss Layout
                    191: The table layout follows
                    192: .Sx Options
                    193: or a
                    194: .Sq \&T&
                    195: macro invocation.
1.1       kristaps  196: Layout specifies how data rows are displayed on output.
                    197: Each layout line corresponds to a line of data; the last layout line
                    198: applies to all remaining data lines.
                    199: Layout lines may also be separated by a comma.
                    200: Each layout cell consists of one of the following case-insensitive keys:
1.19      schwarze  201: .Bl -tag -width 2n
1.1       kristaps  202: .It Cm c
1.22      schwarze  203: Center a literal string within its column.
1.1       kristaps  204: .It Cm r
                    205: Right-justify a literal string within its column.
                    206: .It Cm l
                    207: Left-justify a literal string within its column.
                    208: .It Cm n
1.6       kristaps  209: Justify a number around its last decimal point.
1.1       kristaps  210: If the decimal point is not found on the number, it's assumed to trail
                    211: the number.
                    212: .It Cm s
1.12      schwarze  213: Horizontally span columns from the last
                    214: .No non- Ns Cm s
1.9       kristaps  215: data cell.
1.8       kristaps  216: It is an error if spanning columns follow a
                    217: .Cm \-
                    218: or
                    219: .Cm \(ba
                    220: cell, or come first.
1.9       kristaps  221: This option is not supported by
                    222: .Xr mandoc 1 .
1.1       kristaps  223: .It Cm a
1.7       kristaps  224: Left-justify a literal string and pad with one space.
1.1       kristaps  225: .It Cm ^
1.12      schwarze  226: Vertically span rows from the last
                    227: .No non- Ns Cm ^
1.9       kristaps  228: data cell.
                    229: It is an error to invoke a vertical span on the first layout row.
1.10      kristaps  230: Unlike a horizontal spanner, you must specify an empty cell (if it not
                    231: empty, the data is discarded) in the corresponding data cell.
1.1       kristaps  232: .It Cm \-
                    233: Replace the data cell (its contents will be lost) with a single
                    234: horizontal line.
                    235: This may also be invoked with
                    236: .Cm _ .
                    237: .It Cm =
                    238: Replace the data cell (its contents will be lost) with a double
                    239: horizontal line.
                    240: .It Cm \(ba
                    241: Emit a vertical bar instead of data.
                    242: .It Cm \(ba\(ba
                    243: Emit a double-vertical bar instead of data.
                    244: .El
                    245: .Pp
                    246: Keys may be followed by a set of modifiers.
                    247: A modifier is either a modifier key or a natural number for specifying
1.5       kristaps  248: the minimum width of a column.
1.1       kristaps  249: The following case-insensitive modifier keys are available:
1.19      schwarze  250: .Bl -tag -width 2n
                    251: .It Cm b
                    252: Use a bold font for the contents of this column.
1.24      schwarze  253: .It Cm d
                    254: Move cell content down to the last cell of a vertical span.
                    255: Currently ignored.
1.20      schwarze  256: .It Cm e
                    257: Make this column wider to match the maximum width
                    258: of any other column also having the
                    259: .Cm e
                    260: modifier.
1.19      schwarze  261: .It Cm f
                    262: The next character selects the font to use for this column.
                    263: See the
                    264: .Xr roff 7
                    265: manual for supported one-character font names.
                    266: .It Cm i
                    267: Use an italic font for the contents of this column.
1.24      schwarze  268: .It Cm m
                    269: Specify a cell start macro.
                    270: This is a GNU extension and currently unsupported.
                    271: .It Cm p
                    272: Set the point size to the following unsigned argument,
                    273: or change it by the following signed argument.
                    274: Currently ignored.
                    275: .It Cm v
                    276: Set the vertical line spacing to the following unsigned argument,
                    277: or change it by the following signed argument.
                    278: Currently ignored.
                    279: .It Cm t
                    280: Do not vertically center cell content in the vertical span,
                    281: leave it at the top.
                    282: Currently ignored.
                    283: .It Cm u
                    284: Move cell content up by half a table line.
                    285: Currently ignored.
                    286: .It Cm w
                    287: Specify minimum column width.
                    288: Currently ignored.
1.20      schwarze  289: .It Cm x
                    290: After determining the width of all other columns, distribute the
                    291: rest of the line length among all columns having the
                    292: .Cm x
                    293: modifier.
                    294: .It Cm z
                    295: Do not use this cell for determining the width of this column.
1.19      schwarze  296: .El
1.5       kristaps  297: .Pp
1.22      schwarze  298: For example, the following layout specifies a center-justified column of
1.5       kristaps  299: minimum width 10, followed by vertical bar, followed by a left-justified
1.19      schwarze  300: column of minimum width 10, another vertical bar, then a column using
                    301: bold font justified about the decimal point in numbers:
1.5       kristaps  302: .Pp
1.19      schwarze  303: .Dl c10 | l10 | nfB
1.2       kristaps  304: .Ss Data
1.1       kristaps  305: The data section follows the last layout row.
                    306: By default, cells in a data section are delimited by a tab.
                    307: This behaviour may be changed with the
                    308: .Cm tab
                    309: option.
                    310: If
                    311: .Cm _
                    312: or
                    313: .Cm =
                    314: is specified, a single or double line, respectively, is drawn across the
                    315: data field.
                    316: If
                    317: .Cm \e-
                    318: or
                    319: .Cm \e=
1.3       kristaps  320: is specified, a line is drawn within the data field (i.e. terminating
1.1       kristaps  321: within the cell and not draw to the border).
                    322: If the last cell of a line is
                    323: .Cm T{ ,
                    324: all subsequent lines are included as part of the cell until
                    325: .Cm T}
1.4       kristaps  326: is specified as its own data cell.
                    327: It may then be followed by a tab
                    328: .Pq or as designated by Cm tab
                    329: or an end-of-line to terminate the row.
1.1       kristaps  330: .Sh COMPATIBILITY
                    331: This section documents compatibility between mandoc and other
                    332: .Nm
                    333: implementations, at this time limited to GNU tbl.
                    334: .Pp
                    335: .Bl -dash -compact
                    336: .It
                    337: In GNU tbl, comments and macros are disallowed prior to the data block
                    338: of a table.
                    339: The
                    340: .Xr mandoc 1
                    341: implementation allows them.
                    342: .El
                    343: .Sh SEE ALSO
                    344: .Xr mandoc 1 ,
1.3       kristaps  345: .Xr man 7 ,
1.1       kristaps  346: .Xr mandoc_char 7 ,
1.3       kristaps  347: .Xr mdoc 7 ,
                    348: .Xr roff 7
1.1       kristaps  349: .Rs
                    350: .%A M. E. Lesk
                    351: .%T Tbl\(emA Program to Format Tables
                    352: .%D June 11, 1976
                    353: .Re
                    354: .Sh HISTORY
                    355: The tbl utility, a preprocessor for troff, was originally written by M.
                    356: E. Lesk at Bell Labs in 1975.
                    357: The GNU reimplementation of tbl, part of the groff package, was released
                    358: in 1990 by James Clark.
                    359: A standalone tbl implementation was written by Kristaps Dzonsons in
                    360: 2010.
                    361: This formed the basis of the implementation that is part of the
                    362: .Xr mandoc 1
                    363: utility.
                    364: .Sh AUTHORS
1.14      kristaps  365: This
1.1       kristaps  366: .Nm
                    367: reference was written by
1.17      schwarze  368: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .

CVSweb