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

Annotation of mandoc/tbl.7, Revision 1.30

1.30    ! schwarze    1: .\"    $Id: tbl.7,v 1.29 2017/10/17 23:19:12 schwarze Exp $
1.1       kristaps    2: .\"
1.12      schwarze    3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.30    ! schwarze    4: .\" Copyright (c) 2014, 2015, 2017, 2018 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.30    ! schwarze   18: .Dd $Mdocdate: October 17 2017 $
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
1.28      schwarze   27: language formats tables.
1.1       kristaps   28: It is used within
                     29: .Xr mdoc 7
                     30: and
                     31: .Xr man 7
1.28      schwarze   32: pages.
1.1       kristaps   33: This manual describes the subset of the
                     34: .Nm
                     35: language accepted by the
                     36: .Xr mandoc 1
                     37: utility.
                     38: .Pp
1.28      schwarze   39: Each table is started with a
1.1       kristaps   40: .Xr roff 7
1.28      schwarze   41: .Ic \&TS
                     42: macro, consist of at most one line of
                     43: .Sx Options ,
                     44: one or more
1.2       kristaps   45: .Sx Layout
1.28      schwarze   46: lines, one or more
                     47: .Sx Data
                     48: lines, and ends with a
                     49: .Ic \&TE
                     50: macro.
1.1       kristaps   51: All input must be 7-bit ASCII.
1.2       kristaps   52: .Ss Options
1.28      schwarze   53: If the first input line of a table ends with a semicolon, it contains
                     54: case-insensitive options separated by spaces, tabs, or commas.
                     55: Otherwise, it is interpreted as the first
1.2       kristaps   56: .Sx Layout
1.28      schwarze   57: line.
                     58: .Pp
                     59: The following options are available.
                     60: Some of them require arguments enclosed in parentheses:
1.1       kristaps   61: .Bl -tag -width Ds
1.23      schwarze   62: .It Cm allbox
                     63: Draw a single-line box around each table cell.
                     64: .It Cm box
                     65: Draw a single-line box around the table.
                     66: For GNU compatibility, this may also be invoked with
                     67: .Cm frame .
1.1       kristaps   68: .It Cm center
1.23      schwarze   69: Center the table instead of left-adjusting it.
                     70: For GNU compatibility, this may also be invoked with
1.1       kristaps   71: .Cm centre .
1.23      schwarze   72: .It Cm decimalpoint
                     73: Use the single-character argument as the decimal point with the
                     74: .Cm n
                     75: layout key.
                     76: This is a GNU extension.
1.1       kristaps   77: .It Cm delim
1.23      schwarze   78: Use the two characters of the argument as
                     79: .Xr eqn 7
                     80: delimiters.
                     81: Currently unsupported.
1.1       kristaps   82: .It Cm doublebox
                     83: Draw a double-line box around the table.
1.23      schwarze   84: For GNU compatibility, this may also be invoked with
1.1       kristaps   85: .Cm doubleframe .
1.23      schwarze   86: .It Cm expand
                     87: Increase the width of the table to the current line length.
                     88: Currently ignored.
1.1       kristaps   89: .It Cm linesize
1.23      schwarze   90: Draw lines with the point size given by the unsigned integer argument.
                     91: Currently ignored.
1.1       kristaps   92: .It Cm nokeep
1.23      schwarze   93: Allow page breaks within the table.
                     94: This is a GNU extension and currently ignored.
1.1       kristaps   95: .It Cm nospaces
1.23      schwarze   96: Ignore leading and trailing spaces in data cells.
                     97: This is a GNU extension and currently ignored.
                     98: .It Cm nowarn
                     99: Suppress warnings about tables exceeding the current line length.
                    100: This is a GNU extension and currently ignored.
                    101: .It Cm tab
                    102: Use the single-character argument as a delimiter between data cells.
1.28      schwarze  103: By default, the horizontal tabulator character is used.
1.1       kristaps  104: .El
1.2       kristaps  105: .Ss Layout
1.28      schwarze  106: The table layout follows an
1.2       kristaps  107: .Sx Options
1.28      schwarze  108: line or a
                    109: .Xr roff 7
                    110: .Ic \&TS
                    111: or
                    112: .Ic \&T&
                    113: macro.
                    114: Each layout line specifies how one line of
                    115: .Sx Data
                    116: is formatted.
                    117: The last layout line ends with a full stop.
                    118: It also applies to all remaining data lines.
                    119: Multiple layout lines can be joined by commas on a single physical
                    120: input line.
                    121: .Pp
                    122: Each layout line consists of one or more layout cell specifications,
                    123: optionally separated by whitespace.
                    124: The following case-insensitive key characters start a new cell
                    125: specification:
1.19      schwarze  126: .Bl -tag -width 2n
1.1       kristaps  127: .It Cm c
1.28      schwarze  128: Center the string in this cell.
1.1       kristaps  129: .It Cm r
1.28      schwarze  130: Right-justify the string in this cell.
1.1       kristaps  131: .It Cm l
1.28      schwarze  132: Left-justify the string in this cell.
1.1       kristaps  133: .It Cm n
1.6       kristaps  134: Justify a number around its last decimal point.
1.28      schwarze  135: If no decimal point is found in the number,
                    136: it is assumed to trail the number.
1.1       kristaps  137: .It Cm s
1.12      schwarze  138: Horizontally span columns from the last
1.28      schwarze  139: .Pf non- Cm s
                    140: layout cell.
                    141: It is an error if a column span follows a
                    142: .Cm _
1.8       kristaps  143: or
1.28      schwarze  144: .Cm =
                    145: cell, or comes first on a layout line.
                    146: The combined cell as a whole consumes only one cell
                    147: of the corresponding data line.
1.1       kristaps  148: .It Cm a
1.28      schwarze  149: Left-justify a string and pad with one space.
1.30    ! schwarze  150: .It Cm \(ha
1.12      schwarze  151: Vertically span rows from the last
1.30    ! schwarze  152: .Pf non- Cm \(ha
1.28      schwarze  153: layout cell.
                    154: It is an error to invoke a vertical span on the first layout line.
                    155: Unlike a horizontal span, a vertical span consumes a data cell
                    156: and discards the content.
                    157: .It Cm _
                    158: Draw a single horizontal line in this cell.
                    159: This consumes a data cell and discards the content.
                    160: It may also be invoked with
                    161: .Cm \- .
1.1       kristaps  162: .It Cm =
1.28      schwarze  163: Draw a double horizontal line in this cell.
                    164: This consumes a data cell and discards the content.
1.1       kristaps  165: .El
                    166: .Pp
1.28      schwarze  167: Each cell key may be followed by zero or more of the following
                    168: case-insensitive modifiers:
1.19      schwarze  169: .Bl -tag -width 2n
                    170: .It Cm b
1.28      schwarze  171: Use a bold font for the contents of this cell.
1.24      schwarze  172: .It Cm d
1.28      schwarze  173: Move content down to the last row of this vertical span.
1.24      schwarze  174: Currently ignored.
1.20      schwarze  175: .It Cm e
                    176: Make this column wider to match the maximum width
                    177: of any other column also having the
                    178: .Cm e
                    179: modifier.
1.19      schwarze  180: .It Cm f
1.28      schwarze  181: The next character selects the font to use for this cell.
1.19      schwarze  182: See the
                    183: .Xr roff 7
                    184: manual for supported one-character font names.
                    185: .It Cm i
1.28      schwarze  186: Use an italic font for the contents of this cell.
1.24      schwarze  187: .It Cm m
                    188: Specify a cell start macro.
                    189: This is a GNU extension and currently unsupported.
                    190: .It Cm p
                    191: Set the point size to the following unsigned argument,
                    192: or change it by the following signed argument.
                    193: Currently ignored.
                    194: .It Cm v
                    195: Set the vertical line spacing to the following unsigned argument,
                    196: or change it by the following signed argument.
                    197: Currently ignored.
                    198: .It Cm t
1.28      schwarze  199: Do not vertically center content in this vertical span,
                    200: leave it in the top row.
1.24      schwarze  201: Currently ignored.
                    202: .It Cm u
1.28      schwarze  203: Move cell content up by half a table row.
1.24      schwarze  204: Currently ignored.
                    205: .It Cm w
1.28      schwarze  206: Specify a minimum column width.
1.20      schwarze  207: .It Cm x
                    208: After determining the width of all other columns, distribute the
                    209: rest of the line length among all columns having the
                    210: .Cm x
                    211: modifier.
                    212: .It Cm z
                    213: Do not use this cell for determining the width of this column.
1.28      schwarze  214: .It Cm \&|
                    215: Draw a single vertical line to the right of this cell.
                    216: .It Cm ||
                    217: Draw a double vertical line to the right of this cell.
1.19      schwarze  218: .El
1.5       kristaps  219: .Pp
1.28      schwarze  220: If a modifier consists of decimal digits,
                    221: it specifies a minimum spacing in units of
                    222: .Cm n
                    223: between this column and the next column to the right.
                    224: The default is 3.
                    225: If there is a vertical line, it is drawn inside the spacing.
1.2       kristaps  226: .Ss Data
1.28      schwarze  227: The data section follows the last
                    228: .Sx Layout
                    229: line.
                    230: Each data line consists of one or more data cells, delimited by
1.1       kristaps  231: .Cm tab
1.28      schwarze  232: characters.
                    233: .Pp
1.30    ! schwarze  234: If a data cell contains only the two bytes
        !           235: .Ql \e\(ha ,
        !           236: the cell above spans to this row, as if the layout specification
        !           237: of this cell were
        !           238: .Cm \(ha .
        !           239: .Pp
        !           240: If a data cell contains only the single character
1.28      schwarze  241: .Ql _
                    242: or
                    243: .Ql = ,
                    244: a single or double horizontal line is drawn across the cell,
                    245: joining its neighbours.
                    246: If a data cells contains only the two character sequence
                    247: .Ql \e_
                    248: or
                    249: .Ql \e= ,
                    250: a single or double horizontal line is drawn inside the cell,
                    251: not joining its neighbours.
                    252: If a data line contains nothing but the single character
                    253: .Ql _
1.1       kristaps  254: or
1.28      schwarze  255: .Ql = ,
                    256: a horizontal line across the whole table is inserted
                    257: without consuming a layout row.
                    258: .Pp
                    259: In place of any data cell, a text block can be used.
                    260: It starts with
                    261: .Ic \&T{
                    262: at the end of a physical input line.
                    263: Input line breaks inside the text block
                    264: neither end the text block nor its data cell.
                    265: It only ends if
                    266: .Ic \&T}
                    267: occurs at the beginning of a physical input line and is followed
                    268: by an end-of-cell indicator.
                    269: If the
                    270: .Ic \&T}
                    271: is followed by the end of the physical input line, the text block,
                    272: the data cell, and the data line ends at this point.
                    273: If the
                    274: .Ic \&T}
                    275: is followed by the
                    276: .Cm tab
                    277: character, only the text block and the data cell end,
                    278: but the data line continues with the data cell following the
                    279: .Cm tab
                    280: character.
1.1       kristaps  281: If
1.28      schwarze  282: .Ic \&T}
                    283: is followed by any other character, it does not end the text block,
                    284: which instead continues to the following physical input line.
                    285: .Sh EXAMPLES
                    286: String justification and font selection:
                    287: .Bd -literal -offset indent
                    288: \&.TS
                    289: rb c  lb
                    290: r  ci l.
                    291: r      center  l
                    292: ri     ce      le
                    293: right  c       left
                    294: \&.TE
                    295: .Ed
                    296: .Bd -filled -offset indent
                    297: .TS
                    298: rb c  lb
                    299: r  ci l.
                    300: r      center  l
                    301: ri     ce      le
                    302: right  c       left
                    303: .TE
                    304: .Ed
                    305: .Pp
                    306: Some ports in
                    307: .Ox 6.1
                    308: to show number alignment and line drawing:
                    309: .Bd -literal -offset indent
                    310: \&.TS
                    311: box tab(:);
                    312: r| l
                    313: r  n.
                    314: software:version
                    315: _
                    316: AFL:2.39b
                    317: Mutt:1.8.0
                    318: Ruby:1.8.7.374
                    319: TeX Live:2015
                    320: \&.TE
                    321: .Ed
                    322: .Bd -filled -offset indent
                    323: .TS
                    324: box tab(:);
                    325: r| l
                    326: r  n.
                    327: software:version
                    328: _
                    329: AFL:2.39b
                    330: Mutt:1.8.0
                    331: Ruby:1.8.7.374
                    332: TeX Live:2015
                    333: .TE
                    334: .Ed
                    335: .sp 2v
                    336: Spans and skipping width calculations:
                    337: .Bd -literal -offset indent
                    338: \&.TS
                    339: box tab(:);
                    340: lz  s | rt
1.30    ! schwarze  341: lt| cb| \(ha
        !           342: \(ha | rz  s.
1.28      schwarze  343: left:r
                    344: l:center:
                    345: :right
                    346: \&.TE
                    347: .Ed
                    348: .Bd -filled -offset indent
                    349: .TS
                    350: box tab(:);
                    351: lz  s | rt
                    352: lt| cb| ^
                    353: ^ | rz  s.
                    354: left:r
                    355: l:center:
                    356: :right
                    357: .TE
                    358: .Ed
                    359: .sp 2v
                    360: Text blocks, specifying spacings and specifying and equalizing
                    361: column widths, putting lines into individual cells, and overriding
                    362: .Cm allbox :
                    363: .Bd -literal -offset indent
                    364: \&.TS
                    365: allbox tab(:);
                    366: le le||7 lw10.
                    367: The fourth line:_:line 1
                    368: of this column:=:line 2
                    369: determines:\_:line 3
                    370: the column width.:T{
                    371: This text is too wide to fit into a column of width 17.
                    372: T}:line 4
                    373: T{
                    374: No break here.
                    375: T}::line 5
                    376: \&.TE
                    377: .Ed
                    378: .Bd -filled -offset indent
                    379: .TS
                    380: allbox tab(:);
                    381: le le||7 lw10.
                    382: The fourth line:_:line 1
                    383: of this column:=:line 2
                    384: determines:\_:line 3
                    385: the column width.:T{
                    386: This text is too wide to fit into a column of width 17.
                    387: T}:line 4
                    388: T{
                    389: No break here.
                    390: T}::line 5
                    391: .TE
                    392: .Ed
                    393: .sp 2v
                    394: These examples were constructed to demonstrate many
                    395: .Nm
                    396: features in a compact way.
                    397: In real manual pages, keep tables as simple as possible:
                    398: Like that, they usually look better, are less fragile, and more portable.
1.1       kristaps  399: .Sh COMPATIBILITY
                    400: The
                    401: .Xr mandoc 1
1.26      schwarze  402: implementation of
                    403: .Nm
                    404: doesn't support
                    405: .Xr mdoc 7
                    406: and
                    407: .Xr man 7
                    408: macros and
                    409: .Xr eqn 7
                    410: equations inside tables.
1.1       kristaps  411: .Sh SEE ALSO
                    412: .Xr mandoc 1 ,
1.3       kristaps  413: .Xr man 7 ,
1.1       kristaps  414: .Xr mandoc_char 7 ,
1.3       kristaps  415: .Xr mdoc 7 ,
                    416: .Xr roff 7
1.1       kristaps  417: .Rs
                    418: .%A M. E. Lesk
                    419: .%T Tbl\(emA Program to Format Tables
                    420: .%D June 11, 1976
                    421: .Re
                    422: .Sh HISTORY
                    423: The tbl utility, a preprocessor for troff, was originally written by M.
                    424: E. Lesk at Bell Labs in 1975.
                    425: The GNU reimplementation of tbl, part of the groff package, was released
                    426: in 1990 by James Clark.
                    427: A standalone tbl implementation was written by Kristaps Dzonsons in
                    428: 2010.
1.29      schwarze  429: This formed the basis of the implementation that first appeared in
                    430: .Ox 4.9
                    431: as a part of the
1.1       kristaps  432: .Xr mandoc 1
                    433: utility.
                    434: .Sh AUTHORS
1.14      kristaps  435: This
1.1       kristaps  436: .Nm
                    437: reference was written by
1.28      schwarze  438: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
                    439: and
                    440: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .

CVSweb