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