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

Annotation of mandoc/tbl.7, Revision 1.19

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

CVSweb