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

Annotation of mandoc/tbl.7, Revision 1.10

1.10    ! kristaps    1: .\"    $Id: tbl.7,v 1.9 2011/01/11 14:12:01 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.10    ! kristaps   17: .Dd $Mdocdate: January 11 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
1.9       kristaps  212: Horizontally span columns from the last non-
                    213: .Ns Cm s
                    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.9       kristaps  225: Vertically span rows from the last non-
                    226: .Ns Cm ^
                    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:
                    249: .Cm z ,
                    250: .Cm u ,
                    251: .Cm e ,
                    252: .Cm t ,
                    253: .Cm d ,
                    254: .Cm f ,
                    255: .Cm b ,
                    256: .Cm i ,
                    257: .Cm b ,
                    258: and
                    259: .Cm i .
                    260: All of these are ignored by
                    261: .Xr mandoc 1 .
1.5       kristaps  262: .Pp
                    263: For example, the following layout specifies a centre-justified column of
                    264: minimum width 10, followed by vertical bar, followed by a left-justified
                    265: column of minimum width 10, another vertical bar, then a column
                    266: justified about the decimal point in numbers:
                    267: .Pp
                    268: .Dl c10 | l10 | n
1.2       kristaps  269: .Ss Data
1.1       kristaps  270: The data section follows the last layout row.
                    271: By default, cells in a data section are delimited by a tab.
                    272: This behaviour may be changed with the
                    273: .Cm tab
                    274: option.
                    275: If
                    276: .Cm _
                    277: or
                    278: .Cm =
                    279: is specified, a single or double line, respectively, is drawn across the
                    280: data field.
                    281: If
                    282: .Cm \e-
                    283: or
                    284: .Cm \e=
1.3       kristaps  285: is specified, a line is drawn within the data field (i.e. terminating
1.1       kristaps  286: within the cell and not draw to the border).
                    287: If the last cell of a line is
                    288: .Cm T{ ,
                    289: all subsequent lines are included as part of the cell until
                    290: .Cm T}
1.4       kristaps  291: is specified as its own data cell.
                    292: It may then be followed by a tab
                    293: .Pq or as designated by Cm tab
                    294: or an end-of-line to terminate the row.
1.1       kristaps  295: .Sh COMPATIBILITY
                    296: This section documents compatibility between mandoc and other
                    297: .Nm
                    298: implementations, at this time limited to GNU tbl.
                    299: .Pp
                    300: .Bl -dash -compact
                    301: .It
                    302: In GNU tbl, comments and macros are disallowed prior to the data block
                    303: of a table.
                    304: The
                    305: .Xr mandoc 1
                    306: implementation allows them.
                    307: .El
                    308: .Sh SEE ALSO
                    309: .Xr mandoc 1 ,
1.3       kristaps  310: .Xr man 7 ,
1.1       kristaps  311: .Xr mandoc_char 7 ,
1.3       kristaps  312: .Xr mdoc 7 ,
                    313: .Xr roff 7
1.1       kristaps  314: .Rs
                    315: .%A M. E. Lesk
                    316: .%T Tbl\(emA Program to Format Tables
                    317: .%D June 11, 1976
                    318: .Re
                    319: .Sh HISTORY
                    320: The tbl utility, a preprocessor for troff, was originally written by M.
                    321: E. Lesk at Bell Labs in 1975.
                    322: The GNU reimplementation of tbl, part of the groff package, was released
                    323: in 1990 by James Clark.
                    324: A standalone tbl implementation was written by Kristaps Dzonsons in
                    325: 2010.
                    326: This formed the basis of the implementation that is part of the
                    327: .Xr mandoc 1
                    328: utility.
                    329: .Sh AUTHORS
                    330: This partial
                    331: .Nm
                    332: reference was written by
                    333: .An Kristaps Dzonsons Aq kristaps@bsd.lv .

CVSweb