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

Annotation of mandoc/tbl.7, Revision 1.12

1.12    ! schwarze    1: .\"    $Id: tbl.7,v 1.11 2011/01/17 21:29:04 kristaps Exp $
1.1       kristaps    2: .\"
1.12    ! schwarze    3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.1       kristaps    4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
                      6: .\" purpose with or without fee is hereby granted, provided that the above
                      7: .\" copyright notice and this permission notice appear in all copies.
                      8: .\"
                      9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
                     16: .\"
1.12    ! schwarze   17: .Dd $Mdocdate: January 17 2011 $
1.1       kristaps   18: .Dt TBL 7
                     19: .Os
                     20: .Sh NAME
                     21: .Nm tbl
                     22: .Nd tbl language reference for mandoc
                     23: .Sh DESCRIPTION
                     24: The
                     25: .Nm tbl
                     26: language is a table-formatting language.
                     27: It is used within
                     28: .Xr mdoc 7
                     29: and
                     30: .Xr man 7
                     31: .Ux
                     32: manual pages.
                     33: This manual describes the subset of the
                     34: .Nm
                     35: language accepted by the
                     36: .Xr mandoc 1
                     37: utility.
                     38: .Pp
                     39: Tables within
                     40: .Xr mdoc 7
                     41: or
                     42: .Xr man 7
                     43: are enclosed by the
                     44: .Sq TS
                     45: and
                     46: .Sq TE
                     47: macro tags, whose precise syntax is documented in
                     48: .Xr roff 7 .
                     49: Tables consist of a series of options on a single line, followed by the
                     50: table layout, followed by data.
                     51: .Pp
                     52: For example, the following creates a boxed table with digits centered in
                     53: the cells.
                     54: .Bd -literal -offset indent
                     55: \&.TS
                     56: tab(:) box;
                     57: c5 c5 c5.
                     58: 1:2:3
                     59: 4:5:6
                     60: \&.TE
                     61: .Ed
                     62: .Pp
                     63: When formatted, the following output is produced:
                     64: .Bd -filled -offset indent -compact
                     65: .TS
                     66: tab(:) box;
                     67: c5 c5 c5.
                     68: 1:2:3
                     69: 4:5:6
                     70: .TE
                     71: .Ed
                     72: .Sh TABLE STRUCTURE
                     73: Tables are enclosed by the
                     74: .Sq TS
                     75: and
                     76: .Sq TE
                     77: .Xr roff 7
                     78: macros.
1.2       kristaps   79: A table consists of an optional single line of table
                     80: .Sx Options
                     81: terminated by a semicolon, followed by one or more lines of
                     82: .Sx Layout
                     83: specifications terminated by a period, then
                     84: .Sx Data .
1.1       kristaps   85: All input must be 7-bit ASCII.
                     86: Example:
                     87: .Bd -literal -offset indent
                     88: \&.TS
                     89: box tab(:);
                     90: c | c
                     91: | c | c.
                     92: 1:2
                     93: 3:4
                     94: \&.TE
                     95: .Ed
                     96: .Pp
                     97: Table data is
                     98: .Em pre-processed ,
                     99: that is, data rows are parsed then inserted into the underlying stream
                    100: of input data.
1.3       kristaps  101: This allows data rows to be interspersed by arbitrary
1.1       kristaps  102: .Xr roff 7 ,
                    103: .Xr mdoc 7 ,
                    104: and
                    105: .Xr man 7
                    106: macros such as
                    107: .Bd -literal -offset indent
                    108: \&.TS
                    109: tab(:);
                    110: c c c.
                    111: 1:2:3
                    112: \&.Ao
                    113: 3:2:1
                    114: \&.Ac
                    115: \&.TE
                    116: .Ed
                    117: .Pp
                    118: in the case of
                    119: .Xr mdoc 7
                    120: or
                    121: .Bd -literal -offset indent
                    122: \&.TS
                    123: tab(:);
                    124: c c c.
                    125: \&.ds ab 2
                    126: 1:\e*(ab:3
                    127: \&.I
                    128: 3:2:1
                    129: \&.TE
                    130: .Ed
                    131: .Pp
                    132: in the case of
                    133: .Xr man 7 .
1.2       kristaps  134: .Ss Options
                    135: The first line of a table consists of space-separated option keys and
                    136: modifiers terminated by a semicolon.
1.1       kristaps  137: If the first line does not have a terminating semicolon, it is assumed
1.2       kristaps  138: that no options are specified and instead a
                    139: .Sx Layout
                    140: is processed.
1.3       kristaps  141: Some options accept arguments enclosed by parenthesis.
1.1       kristaps  142: The following case-insensitive options are available:
                    143: .Bl -tag -width Ds
                    144: .It Cm center
                    145: This option is not supported by
                    146: .Xr mandoc 1 .
                    147: This may also be invoked with
                    148: .Cm centre .
                    149: .It Cm delim
                    150: Accepts a two-character argument.
                    151: This option is not supported by
                    152: .Xr mandoc 1 .
                    153: .It Cm expand
                    154: This option is not supported by
                    155: .Xr mandoc 1 .
                    156: .It Cm box
                    157: Draw a single-line box around the table.
                    158: This may also be invoked with
                    159: .Cm frame .
                    160: .It Cm doublebox
                    161: Draw a double-line box around the table.
                    162: This may also be invoked with
                    163: .Cm doubleframe .
                    164: .It Cm allbox
                    165: This option is not supported by
                    166: .Xr mandoc 1 .
                    167: .It Cm tab
                    168: Accepts a single-character argument.
1.3       kristaps  169: This character is used as a delimiter between data cells, which otherwise
1.1       kristaps  170: defaults to the tab character.
                    171: .It Cm linesize
                    172: Accepts a natural number (all digits).
                    173: This option is not supported by
                    174: .Xr mandoc 1 .
                    175: .It Cm nokeep
                    176: This option is not supported by
                    177: .Xr mandoc 1 .
                    178: .It Cm decimalpoint
                    179: Accepts a single-character argument.
                    180: This character will be used as the decimal point with the
                    181: .Cm n
                    182: layout key.
                    183: .It Cm nospaces
                    184: This option is not supported by
                    185: .Xr mandoc 1 .
                    186: .El
1.2       kristaps  187: .Ss Layout
                    188: The table layout follows
                    189: .Sx Options
                    190: or a
                    191: .Sq \&T&
                    192: macro invocation.
1.1       kristaps  193: Layout specifies how data rows are displayed on output.
                    194: Each layout line corresponds to a line of data; the last layout line
                    195: applies to all remaining data lines.
                    196: Layout lines may also be separated by a comma.
                    197: Each layout cell consists of one of the following case-insensitive keys:
                    198: .Bl -tag -width Ds
                    199: .It Cm c
                    200: Centre a literal string within its column.
                    201: .It Cm r
                    202: Right-justify a literal string within its column.
                    203: .It Cm l
                    204: Left-justify a literal string within its column.
                    205: .It Cm n
1.6       kristaps  206: Justify a number around its last decimal point.
1.1       kristaps  207: If the decimal point is not found on the number, it's assumed to trail
                    208: the number.
                    209: .It Cm s
1.12    ! schwarze  210: Horizontally span columns from the last
        !           211: .No non- Ns Cm s
1.9       kristaps  212: data cell.
1.8       kristaps  213: It is an error if spanning columns follow a
                    214: .Cm \-
                    215: or
                    216: .Cm \(ba
                    217: cell, or come first.
1.9       kristaps  218: This option is not supported by
                    219: .Xr mandoc 1 .
1.1       kristaps  220: .It Cm a
1.7       kristaps  221: Left-justify a literal string and pad with one space.
1.1       kristaps  222: .It Cm ^
1.12    ! schwarze  223: Vertically span rows from the last
        !           224: .No non- Ns Cm ^
1.9       kristaps  225: data cell.
                    226: It is an error to invoke a vertical span on the first layout row.
1.10      kristaps  227: Unlike a horizontal spanner, you must specify an empty cell (if it not
                    228: empty, the data is discarded) in the corresponding data cell.
1.1       kristaps  229: .It Cm \-
                    230: Replace the data cell (its contents will be lost) with a single
                    231: horizontal line.
                    232: This may also be invoked with
                    233: .Cm _ .
                    234: .It Cm =
                    235: Replace the data cell (its contents will be lost) with a double
                    236: horizontal line.
                    237: .It Cm \(ba
                    238: Emit a vertical bar instead of data.
                    239: .It Cm \(ba\(ba
                    240: Emit a double-vertical bar instead of data.
                    241: .El
                    242: .Pp
                    243: Keys may be followed by a set of modifiers.
                    244: A modifier is either a modifier key or a natural number for specifying
1.5       kristaps  245: the minimum width of a column.
1.1       kristaps  246: The following case-insensitive modifier keys are available:
                    247: .Cm z ,
                    248: .Cm u ,
                    249: .Cm e ,
                    250: .Cm t ,
                    251: .Cm d ,
                    252: .Cm f ,
                    253: .Cm b ,
                    254: .Cm i ,
                    255: .Cm b ,
                    256: and
                    257: .Cm i .
                    258: All of these are ignored by
                    259: .Xr mandoc 1 .
1.5       kristaps  260: .Pp
                    261: For example, the following layout specifies a centre-justified column of
                    262: minimum width 10, followed by vertical bar, followed by a left-justified
                    263: column of minimum width 10, another vertical bar, then a column
                    264: justified about the decimal point in numbers:
                    265: .Pp
                    266: .Dl c10 | l10 | n
1.2       kristaps  267: .Ss Data
1.1       kristaps  268: The data section follows the last layout row.
                    269: By default, cells in a data section are delimited by a tab.
                    270: This behaviour may be changed with the
                    271: .Cm tab
                    272: option.
                    273: If
                    274: .Cm _
                    275: or
                    276: .Cm =
                    277: is specified, a single or double line, respectively, is drawn across the
                    278: data field.
                    279: If
                    280: .Cm \e-
                    281: or
                    282: .Cm \e=
1.3       kristaps  283: is specified, a line is drawn within the data field (i.e. terminating
1.1       kristaps  284: within the cell and not draw to the border).
                    285: If the last cell of a line is
                    286: .Cm T{ ,
                    287: all subsequent lines are included as part of the cell until
                    288: .Cm T}
1.4       kristaps  289: is specified as its own data cell.
                    290: It may then be followed by a tab
                    291: .Pq or as designated by Cm tab
                    292: or an end-of-line to terminate the row.
1.1       kristaps  293: .Sh COMPATIBILITY
                    294: This section documents compatibility between mandoc and other
                    295: .Nm
                    296: implementations, at this time limited to GNU tbl.
                    297: .Pp
                    298: .Bl -dash -compact
                    299: .It
                    300: In GNU tbl, comments and macros are disallowed prior to the data block
                    301: of a table.
                    302: The
                    303: .Xr mandoc 1
                    304: implementation allows them.
                    305: .El
                    306: .Sh SEE ALSO
                    307: .Xr mandoc 1 ,
1.3       kristaps  308: .Xr man 7 ,
1.1       kristaps  309: .Xr mandoc_char 7 ,
1.3       kristaps  310: .Xr mdoc 7 ,
                    311: .Xr roff 7
1.1       kristaps  312: .Rs
                    313: .%A M. E. Lesk
                    314: .%T Tbl\(emA Program to Format Tables
                    315: .%D June 11, 1976
                    316: .Re
                    317: .Sh HISTORY
                    318: The tbl utility, a preprocessor for troff, was originally written by M.
                    319: E. Lesk at Bell Labs in 1975.
                    320: The GNU reimplementation of tbl, part of the groff package, was released
                    321: in 1990 by James Clark.
                    322: A standalone tbl implementation was written by Kristaps Dzonsons in
                    323: 2010.
                    324: This formed the basis of the implementation that is part of the
                    325: .Xr mandoc 1
                    326: utility.
                    327: .Sh AUTHORS
                    328: This partial
                    329: .Nm
                    330: reference was written by
                    331: .An Kristaps Dzonsons Aq kristaps@bsd.lv .

CVSweb