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

Annotation of mandoc/tbl.7, Revision 1.22

1.22    ! schwarze    1: .\"    $Id: tbl.7,v 1.21 2014/11/26 17:51:55 schwarze Exp $
1.1       kristaps    2: .\"
1.12      schwarze    3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.19      schwarze    4: .\" Copyright (c) 2014 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.22    ! schwarze   18: .Dd $Mdocdate: November 26 2014 $
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
                    136: The first line of a table consists of space-separated option keys and
                    137: modifiers terminated by a semicolon.
1.21      schwarze  138: For GNU compatibility, option keys can also be separated by commas.
1.1       kristaps  139: If the first line does not have a terminating semicolon, it is assumed
1.2       kristaps  140: that no options are specified and instead a
                    141: .Sx Layout
                    142: is processed.
1.3       kristaps  143: Some options accept arguments enclosed by parenthesis.
1.1       kristaps  144: The following case-insensitive options are available:
                    145: .Bl -tag -width Ds
                    146: .It Cm center
                    147: This option is not supported by
                    148: .Xr mandoc 1 .
                    149: This may also be invoked with
                    150: .Cm centre .
                    151: .It Cm delim
                    152: Accepts a two-character argument.
                    153: This option is not supported by
                    154: .Xr mandoc 1 .
                    155: .It Cm expand
                    156: This option is not supported by
                    157: .Xr mandoc 1 .
                    158: .It Cm box
                    159: Draw a single-line box around the table.
                    160: This may also be invoked with
                    161: .Cm frame .
                    162: .It Cm doublebox
                    163: Draw a double-line box around the table.
                    164: This may also be invoked with
                    165: .Cm doubleframe .
                    166: .It Cm allbox
                    167: This option is not supported by
                    168: .Xr mandoc 1 .
                    169: .It Cm tab
                    170: Accepts a single-character argument.
1.3       kristaps  171: This character is used as a delimiter between data cells, which otherwise
1.1       kristaps  172: defaults to the tab character.
                    173: .It Cm linesize
                    174: Accepts a natural number (all digits).
                    175: This option is not supported by
                    176: .Xr mandoc 1 .
                    177: .It Cm nokeep
                    178: This option is not supported by
                    179: .Xr mandoc 1 .
                    180: .It Cm decimalpoint
                    181: Accepts a single-character argument.
                    182: This character will be used as the decimal point with the
                    183: .Cm n
                    184: layout key.
                    185: .It Cm nospaces
                    186: This option is not supported by
                    187: .Xr mandoc 1 .
                    188: .El
1.2       kristaps  189: .Ss Layout
                    190: The table layout follows
                    191: .Sx Options
                    192: or a
                    193: .Sq \&T&
                    194: macro invocation.
1.1       kristaps  195: Layout specifies how data rows are displayed on output.
                    196: Each layout line corresponds to a line of data; the last layout line
                    197: applies to all remaining data lines.
                    198: Layout lines may also be separated by a comma.
                    199: Each layout cell consists of one of the following case-insensitive keys:
1.19      schwarze  200: .Bl -tag -width 2n
1.1       kristaps  201: .It Cm c
1.22    ! schwarze  202: Center a literal string within its column.
1.1       kristaps  203: .It Cm r
                    204: Right-justify a literal string within its column.
                    205: .It Cm l
                    206: Left-justify a literal string within its column.
                    207: .It Cm n
1.6       kristaps  208: Justify a number around its last decimal point.
1.1       kristaps  209: If the decimal point is not found on the number, it's assumed to trail
                    210: the number.
                    211: .It Cm s
1.12      schwarze  212: Horizontally span columns from the last
                    213: .No non- Ns Cm s
1.9       kristaps  214: data cell.
1.8       kristaps  215: It is an error if spanning columns follow a
                    216: .Cm \-
                    217: or
                    218: .Cm \(ba
                    219: cell, or come first.
1.9       kristaps  220: This option is not supported by
                    221: .Xr mandoc 1 .
1.1       kristaps  222: .It Cm a
1.7       kristaps  223: Left-justify a literal string and pad with one space.
1.1       kristaps  224: .It Cm ^
1.12      schwarze  225: Vertically span rows from the last
                    226: .No non- Ns Cm ^
1.9       kristaps  227: data cell.
                    228: It is an error to invoke a vertical span on the first layout row.
1.10      kristaps  229: Unlike a horizontal spanner, you must specify an empty cell (if it not
                    230: empty, the data is discarded) in the corresponding data cell.
1.1       kristaps  231: .It Cm \-
                    232: Replace the data cell (its contents will be lost) with a single
                    233: horizontal line.
                    234: This may also be invoked with
                    235: .Cm _ .
                    236: .It Cm =
                    237: Replace the data cell (its contents will be lost) with a double
                    238: horizontal line.
                    239: .It Cm \(ba
                    240: Emit a vertical bar instead of data.
                    241: .It Cm \(ba\(ba
                    242: Emit a double-vertical bar instead of data.
                    243: .El
                    244: .Pp
                    245: Keys may be followed by a set of modifiers.
                    246: A modifier is either a modifier key or a natural number for specifying
1.5       kristaps  247: the minimum width of a column.
1.1       kristaps  248: The following case-insensitive modifier keys are available:
1.19      schwarze  249: .Bl -tag -width 2n
                    250: .It Cm b
                    251: Use a bold font for the contents of this column.
1.20      schwarze  252: .It Cm e
                    253: Make this column wider to match the maximum width
                    254: of any other column also having the
                    255: .Cm e
                    256: modifier.
1.19      schwarze  257: .It Cm f
                    258: The next character selects the font to use for this column.
                    259: See the
                    260: .Xr roff 7
                    261: manual for supported one-character font names.
                    262: .It Cm i
                    263: Use an italic font for the contents of this column.
1.20      schwarze  264: .It Cm x
                    265: After determining the width of all other columns, distribute the
                    266: rest of the line length among all columns having the
                    267: .Cm x
                    268: modifier.
                    269: .It Cm z
                    270: Do not use this cell for determining the width of this column.
1.19      schwarze  271: .El
                    272: .Pp
                    273: The modifiers
                    274: .Cm d ,
1.1       kristaps  275: .Cm t ,
1.19      schwarze  276: .Cm u ,
1.16      kristaps  277: and
1.20      schwarze  278: .Cm w
1.19      schwarze  279: are ignored by
1.1       kristaps  280: .Xr mandoc 1 .
1.5       kristaps  281: .Pp
1.22    ! schwarze  282: For example, the following layout specifies a center-justified column of
1.5       kristaps  283: minimum width 10, followed by vertical bar, followed by a left-justified
1.19      schwarze  284: column of minimum width 10, another vertical bar, then a column using
                    285: bold font justified about the decimal point in numbers:
1.5       kristaps  286: .Pp
1.19      schwarze  287: .Dl c10 | l10 | nfB
1.2       kristaps  288: .Ss Data
1.1       kristaps  289: The data section follows the last layout row.
                    290: By default, cells in a data section are delimited by a tab.
                    291: This behaviour may be changed with the
                    292: .Cm tab
                    293: option.
                    294: If
                    295: .Cm _
                    296: or
                    297: .Cm =
                    298: is specified, a single or double line, respectively, is drawn across the
                    299: data field.
                    300: If
                    301: .Cm \e-
                    302: or
                    303: .Cm \e=
1.3       kristaps  304: is specified, a line is drawn within the data field (i.e. terminating
1.1       kristaps  305: within the cell and not draw to the border).
                    306: If the last cell of a line is
                    307: .Cm T{ ,
                    308: all subsequent lines are included as part of the cell until
                    309: .Cm T}
1.4       kristaps  310: is specified as its own data cell.
                    311: It may then be followed by a tab
                    312: .Pq or as designated by Cm tab
                    313: or an end-of-line to terminate the row.
1.1       kristaps  314: .Sh COMPATIBILITY
                    315: This section documents compatibility between mandoc and other
                    316: .Nm
                    317: implementations, at this time limited to GNU tbl.
                    318: .Pp
                    319: .Bl -dash -compact
                    320: .It
                    321: In GNU tbl, comments and macros are disallowed prior to the data block
                    322: of a table.
                    323: The
                    324: .Xr mandoc 1
                    325: implementation allows them.
                    326: .El
                    327: .Sh SEE ALSO
                    328: .Xr mandoc 1 ,
1.3       kristaps  329: .Xr man 7 ,
1.1       kristaps  330: .Xr mandoc_char 7 ,
1.3       kristaps  331: .Xr mdoc 7 ,
                    332: .Xr roff 7
1.1       kristaps  333: .Rs
                    334: .%A M. E. Lesk
                    335: .%T Tbl\(emA Program to Format Tables
                    336: .%D June 11, 1976
                    337: .Re
                    338: .Sh HISTORY
                    339: The tbl utility, a preprocessor for troff, was originally written by M.
                    340: E. Lesk at Bell Labs in 1975.
                    341: The GNU reimplementation of tbl, part of the groff package, was released
                    342: in 1990 by James Clark.
                    343: A standalone tbl implementation was written by Kristaps Dzonsons in
                    344: 2010.
                    345: This formed the basis of the implementation that is part of the
                    346: .Xr mandoc 1
                    347: utility.
                    348: .Sh AUTHORS
1.14      kristaps  349: This
1.1       kristaps  350: .Nm
                    351: reference was written by
1.17      schwarze  352: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .

CVSweb