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

Annotation of mandoc/tbl.7, Revision 1.23

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

CVSweb