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

Annotation of mandoc/tbl.7, Revision 1.28

1.28    ! schwarze    1: .\"    $Id: tbl.7,v 1.27 2017/06/08 18:11:22 schwarze Exp $
1.1       kristaps    2: .\"
1.12      schwarze    3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.27      schwarze    4: .\" Copyright (c) 2014, 2015, 2017 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.28    ! schwarze   18: .Dd $Mdocdate: June 8 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.1       kristaps  150: .It Cm ^
1.12      schwarze  151: Vertically span rows from the last
1.28    ! schwarze  152: .Pf non- Cm ^
        !           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
        !           234: If a data cells contains only the single character
        !           235: .Ql _
        !           236: or
        !           237: .Ql = ,
        !           238: a single or double horizontal line is drawn across the cell,
        !           239: joining its neighbours.
        !           240: If a data cells contains only the two character sequence
        !           241: .Ql \e_
        !           242: or
        !           243: .Ql \e= ,
        !           244: a single or double horizontal line is drawn inside the cell,
        !           245: not joining its neighbours.
        !           246: If a data line contains nothing but the single character
        !           247: .Ql _
1.1       kristaps  248: or
1.28    ! schwarze  249: .Ql = ,
        !           250: a horizontal line across the whole table is inserted
        !           251: without consuming a layout row.
        !           252: .Pp
        !           253: In place of any data cell, a text block can be used.
        !           254: It starts with
        !           255: .Ic \&T{
        !           256: at the end of a physical input line.
        !           257: Input line breaks inside the text block
        !           258: neither end the text block nor its data cell.
        !           259: It only ends if
        !           260: .Ic \&T}
        !           261: occurs at the beginning of a physical input line and is followed
        !           262: by an end-of-cell indicator.
        !           263: If the
        !           264: .Ic \&T}
        !           265: is followed by the end of the physical input line, the text block,
        !           266: the data cell, and the data line ends at this point.
        !           267: If the
        !           268: .Ic \&T}
        !           269: is followed by the
        !           270: .Cm tab
        !           271: character, only the text block and the data cell end,
        !           272: but the data line continues with the data cell following the
        !           273: .Cm tab
        !           274: character.
1.1       kristaps  275: If
1.28    ! schwarze  276: .Ic \&T}
        !           277: is followed by any other character, it does not end the text block,
        !           278: which instead continues to the following physical input line.
        !           279: .Sh EXAMPLES
        !           280: String justification and font selection:
        !           281: .Bd -literal -offset indent
        !           282: \&.TS
        !           283: rb c  lb
        !           284: r  ci l.
        !           285: r      center  l
        !           286: ri     ce      le
        !           287: right  c       left
        !           288: \&.TE
        !           289: .Ed
        !           290: .Bd -filled -offset indent
        !           291: .TS
        !           292: rb c  lb
        !           293: r  ci l.
        !           294: r      center  l
        !           295: ri     ce      le
        !           296: right  c       left
        !           297: .TE
        !           298: .Ed
        !           299: .Pp
        !           300: Some ports in
        !           301: .Ox 6.1
        !           302: to show number alignment and line drawing:
        !           303: .Bd -literal -offset indent
        !           304: \&.TS
        !           305: box tab(:);
        !           306: r| l
        !           307: r  n.
        !           308: software:version
        !           309: _
        !           310: AFL:2.39b
        !           311: Mutt:1.8.0
        !           312: Ruby:1.8.7.374
        !           313: TeX Live:2015
        !           314: \&.TE
        !           315: .Ed
        !           316: .Bd -filled -offset indent
        !           317: .TS
        !           318: box tab(:);
        !           319: r| l
        !           320: r  n.
        !           321: software:version
        !           322: _
        !           323: AFL:2.39b
        !           324: Mutt:1.8.0
        !           325: Ruby:1.8.7.374
        !           326: TeX Live:2015
        !           327: .TE
        !           328: .Ed
        !           329: .sp 2v
        !           330: Spans and skipping width calculations:
        !           331: .Bd -literal -offset indent
        !           332: \&.TS
        !           333: box tab(:);
        !           334: lz  s | rt
        !           335: lt| cb| ^
        !           336: ^ | rz  s.
        !           337: left:r
        !           338: l:center:
        !           339: :right
        !           340: \&.TE
        !           341: .Ed
        !           342: .Bd -filled -offset indent
        !           343: .TS
        !           344: box tab(:);
        !           345: lz  s | rt
        !           346: lt| cb| ^
        !           347: ^ | rz  s.
        !           348: left:r
        !           349: l:center:
        !           350: :right
        !           351: .TE
        !           352: .Ed
        !           353: .sp 2v
        !           354: Text blocks, specifying spacings and specifying and equalizing
        !           355: column widths, putting lines into individual cells, and overriding
        !           356: .Cm allbox :
        !           357: .Bd -literal -offset indent
        !           358: \&.TS
        !           359: allbox tab(:);
        !           360: le le||7 lw10.
        !           361: The fourth line:_:line 1
        !           362: of this column:=:line 2
        !           363: determines:\_:line 3
        !           364: the column width.:T{
        !           365: This text is too wide to fit into a column of width 17.
        !           366: T}:line 4
        !           367: T{
        !           368: No break here.
        !           369: T}::line 5
        !           370: \&.TE
        !           371: .Ed
        !           372: .Bd -filled -offset indent
        !           373: .TS
        !           374: allbox tab(:);
        !           375: le le||7 lw10.
        !           376: The fourth line:_:line 1
        !           377: of this column:=:line 2
        !           378: determines:\_:line 3
        !           379: the column width.:T{
        !           380: This text is too wide to fit into a column of width 17.
        !           381: T}:line 4
        !           382: T{
        !           383: No break here.
        !           384: T}::line 5
        !           385: .TE
        !           386: .Ed
        !           387: .sp 2v
        !           388: These examples were constructed to demonstrate many
        !           389: .Nm
        !           390: features in a compact way.
        !           391: In real manual pages, keep tables as simple as possible:
        !           392: Like that, they usually look better, are less fragile, and more portable.
1.1       kristaps  393: .Sh COMPATIBILITY
                    394: The
                    395: .Xr mandoc 1
1.26      schwarze  396: implementation of
                    397: .Nm
                    398: doesn't support
                    399: .Xr mdoc 7
                    400: and
                    401: .Xr man 7
                    402: macros and
                    403: .Xr eqn 7
                    404: equations inside tables.
1.1       kristaps  405: .Sh SEE ALSO
                    406: .Xr mandoc 1 ,
1.3       kristaps  407: .Xr man 7 ,
1.1       kristaps  408: .Xr mandoc_char 7 ,
1.3       kristaps  409: .Xr mdoc 7 ,
                    410: .Xr roff 7
1.1       kristaps  411: .Rs
                    412: .%A M. E. Lesk
                    413: .%T Tbl\(emA Program to Format Tables
                    414: .%D June 11, 1976
                    415: .Re
                    416: .Sh HISTORY
                    417: The tbl utility, a preprocessor for troff, was originally written by M.
                    418: E. Lesk at Bell Labs in 1975.
                    419: The GNU reimplementation of tbl, part of the groff package, was released
                    420: in 1990 by James Clark.
                    421: A standalone tbl implementation was written by Kristaps Dzonsons in
                    422: 2010.
                    423: This formed the basis of the implementation that is part of the
                    424: .Xr mandoc 1
                    425: utility.
                    426: .Sh AUTHORS
1.14      kristaps  427: This
1.1       kristaps  428: .Nm
                    429: reference was written by
1.28    ! schwarze  430: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
        !           431: and
        !           432: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .

CVSweb