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

Annotation of mandoc/tbl.7, Revision 1.13

1.13    ! kristaps    1: .\"    $Id: tbl.7,v 1.12 2011/02/07 00:05:40 schwarze 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.13    ! kristaps   17: .Dd $Mdocdate: February 7 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
1.13    ! kristaps   72: .Pp
        !            73: The
        !            74: .Nm
        !            75: implementation in
        !            76: .Xr mandoc 1
        !            77: is
        !            78: .Ud
1.1       kristaps   79: .Sh TABLE STRUCTURE
                     80: Tables are enclosed by the
                     81: .Sq TS
                     82: and
                     83: .Sq TE
                     84: .Xr roff 7
                     85: macros.
1.2       kristaps   86: A table consists of an optional single line of table
                     87: .Sx Options
                     88: terminated by a semicolon, followed by one or more lines of
                     89: .Sx Layout
                     90: specifications terminated by a period, then
                     91: .Sx Data .
1.1       kristaps   92: All input must be 7-bit ASCII.
                     93: Example:
                     94: .Bd -literal -offset indent
                     95: \&.TS
                     96: box tab(:);
                     97: c | c
                     98: | c | c.
                     99: 1:2
                    100: 3:4
                    101: \&.TE
                    102: .Ed
                    103: .Pp
                    104: Table data is
                    105: .Em pre-processed ,
                    106: that is, data rows are parsed then inserted into the underlying stream
                    107: of input data.
1.3       kristaps  108: This allows data rows to be interspersed by arbitrary
1.1       kristaps  109: .Xr roff 7 ,
                    110: .Xr mdoc 7 ,
                    111: and
                    112: .Xr man 7
                    113: macros such as
                    114: .Bd -literal -offset indent
                    115: \&.TS
                    116: tab(:);
                    117: c c c.
                    118: 1:2:3
                    119: \&.Ao
                    120: 3:2:1
                    121: \&.Ac
                    122: \&.TE
                    123: .Ed
                    124: .Pp
                    125: in the case of
                    126: .Xr mdoc 7
                    127: or
                    128: .Bd -literal -offset indent
                    129: \&.TS
                    130: tab(:);
                    131: c c c.
                    132: \&.ds ab 2
                    133: 1:\e*(ab:3
                    134: \&.I
                    135: 3:2:1
                    136: \&.TE
                    137: .Ed
                    138: .Pp
                    139: in the case of
                    140: .Xr man 7 .
1.2       kristaps  141: .Ss Options
                    142: The first line of a table consists of space-separated option keys and
                    143: modifiers terminated by a semicolon.
1.1       kristaps  144: If the first line does not have a terminating semicolon, it is assumed
1.2       kristaps  145: that no options are specified and instead a
                    146: .Sx Layout
                    147: is processed.
1.3       kristaps  148: Some options accept arguments enclosed by parenthesis.
1.1       kristaps  149: The following case-insensitive options are available:
                    150: .Bl -tag -width Ds
                    151: .It Cm center
                    152: This option is not supported by
                    153: .Xr mandoc 1 .
                    154: This may also be invoked with
                    155: .Cm centre .
                    156: .It Cm delim
                    157: Accepts a two-character argument.
                    158: This option is not supported by
                    159: .Xr mandoc 1 .
                    160: .It Cm expand
                    161: This option is not supported by
                    162: .Xr mandoc 1 .
                    163: .It Cm box
                    164: Draw a single-line box around the table.
                    165: This may also be invoked with
                    166: .Cm frame .
                    167: .It Cm doublebox
                    168: Draw a double-line box around the table.
                    169: This may also be invoked with
                    170: .Cm doubleframe .
                    171: .It Cm allbox
                    172: This option is not supported by
                    173: .Xr mandoc 1 .
                    174: .It Cm tab
                    175: Accepts a single-character argument.
1.3       kristaps  176: This character is used as a delimiter between data cells, which otherwise
1.1       kristaps  177: defaults to the tab character.
                    178: .It Cm linesize
                    179: Accepts a natural number (all digits).
                    180: This option is not supported by
                    181: .Xr mandoc 1 .
                    182: .It Cm nokeep
                    183: This option is not supported by
                    184: .Xr mandoc 1 .
                    185: .It Cm decimalpoint
                    186: Accepts a single-character argument.
                    187: This character will be used as the decimal point with the
                    188: .Cm n
                    189: layout key.
                    190: .It Cm nospaces
                    191: This option is not supported by
                    192: .Xr mandoc 1 .
                    193: .El
1.2       kristaps  194: .Ss Layout
                    195: The table layout follows
                    196: .Sx Options
                    197: or a
                    198: .Sq \&T&
                    199: macro invocation.
1.1       kristaps  200: Layout specifies how data rows are displayed on output.
                    201: Each layout line corresponds to a line of data; the last layout line
                    202: applies to all remaining data lines.
                    203: Layout lines may also be separated by a comma.
                    204: Each layout cell consists of one of the following case-insensitive keys:
                    205: .Bl -tag -width Ds
                    206: .It Cm c
                    207: Centre a literal string within its column.
                    208: .It Cm r
                    209: Right-justify a literal string within its column.
                    210: .It Cm l
                    211: Left-justify a literal string within its column.
                    212: .It Cm n
1.6       kristaps  213: Justify a number around its last decimal point.
1.1       kristaps  214: If the decimal point is not found on the number, it's assumed to trail
                    215: the number.
                    216: .It Cm s
1.12      schwarze  217: Horizontally span columns from the last
                    218: .No non- Ns Cm s
1.9       kristaps  219: data cell.
1.8       kristaps  220: It is an error if spanning columns follow a
                    221: .Cm \-
                    222: or
                    223: .Cm \(ba
                    224: cell, or come first.
1.9       kristaps  225: This option is not supported by
                    226: .Xr mandoc 1 .
1.1       kristaps  227: .It Cm a
1.7       kristaps  228: Left-justify a literal string and pad with one space.
1.1       kristaps  229: .It Cm ^
1.12      schwarze  230: Vertically span rows from the last
                    231: .No non- Ns Cm ^
1.9       kristaps  232: data cell.
                    233: It is an error to invoke a vertical span on the first layout row.
1.10      kristaps  234: Unlike a horizontal spanner, you must specify an empty cell (if it not
                    235: empty, the data is discarded) in the corresponding data cell.
1.1       kristaps  236: .It Cm \-
                    237: Replace the data cell (its contents will be lost) with a single
                    238: horizontal line.
                    239: This may also be invoked with
                    240: .Cm _ .
                    241: .It Cm =
                    242: Replace the data cell (its contents will be lost) with a double
                    243: horizontal line.
                    244: .It Cm \(ba
                    245: Emit a vertical bar instead of data.
                    246: .It Cm \(ba\(ba
                    247: Emit a double-vertical bar instead of data.
                    248: .El
                    249: .Pp
                    250: Keys may be followed by a set of modifiers.
                    251: A modifier is either a modifier key or a natural number for specifying
1.5       kristaps  252: the minimum width of a column.
1.1       kristaps  253: The following case-insensitive modifier keys are available:
                    254: .Cm z ,
                    255: .Cm u ,
                    256: .Cm e ,
                    257: .Cm t ,
                    258: .Cm d ,
                    259: .Cm f ,
                    260: .Cm b ,
                    261: .Cm i ,
                    262: .Cm b ,
                    263: and
                    264: .Cm i .
                    265: All of these are ignored by
                    266: .Xr mandoc 1 .
1.5       kristaps  267: .Pp
                    268: For example, the following layout specifies a centre-justified column of
                    269: minimum width 10, followed by vertical bar, followed by a left-justified
                    270: column of minimum width 10, another vertical bar, then a column
                    271: justified about the decimal point in numbers:
                    272: .Pp
                    273: .Dl c10 | l10 | n
1.2       kristaps  274: .Ss Data
1.1       kristaps  275: The data section follows the last layout row.
                    276: By default, cells in a data section are delimited by a tab.
                    277: This behaviour may be changed with the
                    278: .Cm tab
                    279: option.
                    280: If
                    281: .Cm _
                    282: or
                    283: .Cm =
                    284: is specified, a single or double line, respectively, is drawn across the
                    285: data field.
                    286: If
                    287: .Cm \e-
                    288: or
                    289: .Cm \e=
1.3       kristaps  290: is specified, a line is drawn within the data field (i.e. terminating
1.1       kristaps  291: within the cell and not draw to the border).
                    292: If the last cell of a line is
                    293: .Cm T{ ,
                    294: all subsequent lines are included as part of the cell until
                    295: .Cm T}
1.4       kristaps  296: is specified as its own data cell.
                    297: It may then be followed by a tab
                    298: .Pq or as designated by Cm tab
                    299: or an end-of-line to terminate the row.
1.1       kristaps  300: .Sh COMPATIBILITY
                    301: This section documents compatibility between mandoc and other
                    302: .Nm
                    303: implementations, at this time limited to GNU tbl.
                    304: .Pp
                    305: .Bl -dash -compact
                    306: .It
                    307: In GNU tbl, comments and macros are disallowed prior to the data block
                    308: of a table.
                    309: The
                    310: .Xr mandoc 1
                    311: implementation allows them.
                    312: .El
                    313: .Sh SEE ALSO
                    314: .Xr mandoc 1 ,
1.3       kristaps  315: .Xr man 7 ,
1.1       kristaps  316: .Xr mandoc_char 7 ,
1.3       kristaps  317: .Xr mdoc 7 ,
                    318: .Xr roff 7
1.1       kristaps  319: .Rs
                    320: .%A M. E. Lesk
                    321: .%T Tbl\(emA Program to Format Tables
                    322: .%D June 11, 1976
                    323: .Re
                    324: .Sh HISTORY
                    325: The tbl utility, a preprocessor for troff, was originally written by M.
                    326: E. Lesk at Bell Labs in 1975.
                    327: The GNU reimplementation of tbl, part of the groff package, was released
                    328: in 1990 by James Clark.
                    329: A standalone tbl implementation was written by Kristaps Dzonsons in
                    330: 2010.
                    331: This formed the basis of the implementation that is part of the
                    332: .Xr mandoc 1
                    333: utility.
                    334: .Sh AUTHORS
                    335: This partial
                    336: .Nm
                    337: reference was written by
                    338: .An Kristaps Dzonsons Aq kristaps@bsd.lv .

CVSweb