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

Annotation of mandoc/tbl.7, Revision 1.1

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

CVSweb