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

Annotation of mandoc/tbl.7, Revision 1.7

1.7     ! kristaps    1: .\"    $Id: tbl.7,v 1.6 2011/01/08 17:16:48 kristaps Exp $
1.1       kristaps    2: .\"
                      3: .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
                      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.6       kristaps   17: .Dd $Mdocdate: January 8 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: This option is not supported by
                    184: .Xr mandoc 1 .
                    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:
                    200: .Bl -tag -width Ds
                    201: .It Cm c
                    202: Centre a literal string within its column.
                    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
                    212: This option is not supported by
                    213: .Xr mandoc 1 .
                    214: .It Cm a
1.7     ! kristaps  215: Left-justify a literal string and pad with one space.
1.1       kristaps  216: .It Cm ^
                    217: This option is not supported by
                    218: .Xr mandoc 1 .
                    219: .It Cm \-
                    220: Replace the data cell (its contents will be lost) with a single
                    221: horizontal line.
                    222: This may also be invoked with
                    223: .Cm _ .
                    224: .It Cm =
                    225: Replace the data cell (its contents will be lost) with a double
                    226: horizontal line.
                    227: .It Cm \(ba
                    228: Emit a vertical bar instead of data.
                    229: .It Cm \(ba\(ba
                    230: Emit a double-vertical bar instead of data.
                    231: .El
                    232: .Pp
                    233: Keys may be followed by a set of modifiers.
                    234: A modifier is either a modifier key or a natural number for specifying
1.5       kristaps  235: the minimum width of a column.
1.1       kristaps  236: The following case-insensitive modifier keys are available:
                    237: .Cm z ,
                    238: .Cm u ,
                    239: .Cm e ,
                    240: .Cm t ,
                    241: .Cm d ,
                    242: .Cm f ,
                    243: .Cm b ,
                    244: .Cm i ,
                    245: .Cm b ,
                    246: and
                    247: .Cm i .
                    248: All of these are ignored by
                    249: .Xr mandoc 1 .
1.5       kristaps  250: .Pp
                    251: For example, the following layout specifies a centre-justified column of
                    252: minimum width 10, followed by vertical bar, followed by a left-justified
                    253: column of minimum width 10, another vertical bar, then a column
                    254: justified about the decimal point in numbers:
                    255: .Pp
                    256: .Dl c10 | l10 | n
1.2       kristaps  257: .Ss Data
1.1       kristaps  258: The data section follows the last layout row.
                    259: By default, cells in a data section are delimited by a tab.
                    260: This behaviour may be changed with the
                    261: .Cm tab
                    262: option.
                    263: If
                    264: .Cm _
                    265: or
                    266: .Cm =
                    267: is specified, a single or double line, respectively, is drawn across the
                    268: data field.
                    269: If
                    270: .Cm \e-
                    271: or
                    272: .Cm \e=
1.3       kristaps  273: is specified, a line is drawn within the data field (i.e. terminating
1.1       kristaps  274: within the cell and not draw to the border).
                    275: If the last cell of a line is
                    276: .Cm T{ ,
                    277: all subsequent lines are included as part of the cell until
                    278: .Cm T}
1.4       kristaps  279: is specified as its own data cell.
                    280: It may then be followed by a tab
                    281: .Pq or as designated by Cm tab
                    282: or an end-of-line to terminate the row.
1.1       kristaps  283: .Sh COMPATIBILITY
                    284: This section documents compatibility between mandoc and other
                    285: .Nm
                    286: implementations, at this time limited to GNU tbl.
                    287: .Pp
                    288: .Bl -dash -compact
                    289: .It
                    290: In GNU tbl, comments and macros are disallowed prior to the data block
                    291: of a table.
                    292: The
                    293: .Xr mandoc 1
                    294: implementation allows them.
                    295: .El
                    296: .Sh SEE ALSO
                    297: .Xr mandoc 1 ,
1.3       kristaps  298: .Xr man 7 ,
1.1       kristaps  299: .Xr mandoc_char 7 ,
1.3       kristaps  300: .Xr mdoc 7 ,
                    301: .Xr roff 7
1.1       kristaps  302: .Rs
                    303: .%A M. E. Lesk
                    304: .%T Tbl\(emA Program to Format Tables
                    305: .%D June 11, 1976
                    306: .Re
                    307: .Sh HISTORY
                    308: The tbl utility, a preprocessor for troff, was originally written by M.
                    309: E. Lesk at Bell Labs in 1975.
                    310: The GNU reimplementation of tbl, part of the groff package, was released
                    311: in 1990 by James Clark.
                    312: A standalone tbl implementation was written by Kristaps Dzonsons in
                    313: 2010.
                    314: This formed the basis of the implementation that is part of the
                    315: .Xr mandoc 1
                    316: utility.
                    317: .Sh AUTHORS
                    318: This partial
                    319: .Nm
                    320: reference was written by
                    321: .An Kristaps Dzonsons Aq kristaps@bsd.lv .

CVSweb