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

Annotation of mandoc/roff.7, Revision 1.21

1.21    ! kristaps    1: .\"    $Id: roff.7,v 1.20 2011/01/03 16:04:41 kristaps Exp $
1.1       kristaps    2: .\"
                      3: .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
1.12      schwarze    4: .\" Copyright (c) 2010 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.21    ! kristaps   18: .Dd $Mdocdate: January 3 2011 $
1.1       kristaps   19: .Dt ROFF 7
                     20: .Os
                     21: .Sh NAME
                     22: .Nm roff
1.17      schwarze   23: .Nd roff language reference for mandoc
1.1       kristaps   24: .Sh DESCRIPTION
                     25: The
                     26: .Nm roff
1.17      schwarze   27: language is a general purpose text formatting language.
                     28: In particular, it serves as the basis for the
                     29: .Xr mdoc 7
                     30: and
                     31: .Xr man 7
                     32: manual formatting macro languages.
                     33: This manual describes the subset of the
                     34: .Nm
                     35: language accepted by the
1.1       kristaps   36: .Xr mandoc 1
1.17      schwarze   37: utility.
1.1       kristaps   38: .Pp
1.17      schwarze   39: Input lines beginning with the control characters
                     40: .Sq \&.
1.1       kristaps   41: or
                     42: .Sq \(aq
1.15      kristaps   43: are parsed for requests and macros.
1.17      schwarze   44: These define the document structure, change the processing state
                     45: and manipulate the formatting.
                     46: Some requests and macros also produce formatted output,
                     47: while others do not.
                     48: .Pp
                     49: All other input lines provide free-form text to be printed;
                     50: the formatting of free-form text depends on the respective
                     51: processing context.
1.1       kristaps   52: .Sh LANGUAGE SYNTAX
                     53: .Nm
                     54: documents may contain only graphable 7-bit ASCII characters, the space
1.17      schwarze   55: character, and, in certain circumstances, the tab character.
                     56: To produce other characters in the output, use the escape sequences
                     57: documented in the
                     58: .Xr mandoc_char 7
                     59: manual.
                     60: .Pp
                     61: All manuals must have
1.1       kristaps   62: .Ux
                     63: line terminators.
1.17      schwarze   64: .Sh REQUEST SYNTAX
                     65: A request or macro line consists of:
                     66: .Pp
                     67: .Bl -enum -compact
                     68: .It
                     69: the control character
                     70: .Sq \&.
1.1       kristaps   71: or
1.17      schwarze   72: .Sq \(aq
                     73: at the beginning of the line,
                     74: .It
                     75: optionally an arbitrary amount of whitespace,
                     76: .It
                     77: the name of the request or the macro, which is one word of arbitrary
                     78: length, terminated by whitespace,
                     79: .It
                     80: and zero or more arguments delimited by whitespace.
                     81: .El
                     82: .Pp
                     83: Thus, the following request lines are all equivalent:
1.1       kristaps   84: .Bd -literal -offset indent
1.17      schwarze   85: \&.ig end
                     86: \&.ig    end
                     87: \&.   ig end
1.1       kristaps   88: .Ed
1.15      kristaps   89: .Sh REQUEST REFERENCE
1.17      schwarze   90: The
1.15      kristaps   91: .Xr mandoc 1
                     92: .Nm
1.17      schwarze   93: parser recognizes the following requests.
                     94: Note that the
1.15      kristaps   95: .Nm
1.17      schwarze   96: language defines many more requests not implemented in
1.15      kristaps   97: .Xr mandoc 1 .
                     98: .Ss \&ad
                     99: Set line adjustment mode.
                    100: This line-scoped request is intended to have one argument to select
                    101: normal, left, right, or center adjustment for subsequent text.
                    102: Currently, it is ignored including its arguments,
                    103: and the number of arguments is not checked.
1.3       kristaps  104: .Ss \&am
1.15      kristaps  105: Append to a macro definition.
                    106: The syntax of this request is the same as that of
                    107: .Sx \&de .
                    108: It is currently ignored by
                    109: .Xr mandoc 1 ,
                    110: as are its children.
1.3       kristaps  111: .Ss \&ami
1.15      kristaps  112: Append to a macro definition, specifying the macro name indirectly.
                    113: The syntax of this request is the same as that of
                    114: .Sx \&dei .
                    115: It is currently ignored by
                    116: .Xr mandoc 1 ,
                    117: as are its children.
1.3       kristaps  118: .Ss \&am1
1.15      kristaps  119: Append to a macro definition, switching roff compatibility mode off
                    120: during macro execution.
                    121: The syntax of this request is the same as that of
                    122: .Sx \&de1 .
                    123: It is currently ignored by
                    124: .Xr mandoc 1 ,
                    125: as are its children.
1.3       kristaps  126: .Ss \&de
1.17      schwarze  127: Define a
1.15      kristaps  128: .Nm
                    129: macro.
                    130: Its syntax can be either
                    131: .Bd -literal -offset indent
                    132: .Pf . Cm \&de Ar name
                    133: .Ar macro definition
                    134: \&..
                    135: .Ed
                    136: .Pp
                    137: or
                    138: .Bd -literal -offset indent
                    139: .Pf . Cm \&de Ar name Ar end
                    140: .Ar macro definition
                    141: .Pf . Ar end
                    142: .Ed
                    143: .Pp
                    144: Both forms define or redefine the macro
                    145: .Ar name
                    146: to represent the
                    147: .Ar macro definition ,
                    148: which may consist of one or more input lines, including the newline
                    149: characters terminating each line, optionally containing calls to
                    150: .Nm
                    151: requests,
                    152: .Nm
                    153: macros or high-level macros like
                    154: .Xr man 7
                    155: or
                    156: .Xr mdoc 7
                    157: macros, whichever applies to the document in question.
                    158: .Pp
                    159: Specifying a custom
                    160: .Ar end
                    161: macro works in the same way as for
                    162: .Sx \&ig ;
                    163: namely, the call to
                    164: .Sq Pf . Ar end
                    165: first ends the
                    166: .Ar macro definition ,
                    167: and after that, it is also evaluated as a
                    168: .Nm
                    169: request or
                    170: .Nm
                    171: macro, but not as a high-level macro.
                    172: .Pp
1.17      schwarze  173: The macro can be invoked later using the syntax
1.15      kristaps  174: .Pp
                    175: .D1 Pf . Ar name Op Ar argument Op Ar argument ...
                    176: .Pp
                    177: Arguments are separated by blank characters and can be quoted
                    178: using double-quotes
                    179: .Pq Sq \(dq
                    180: to allow inclusion of blank characters into arguments.
                    181: To include the double-quote character into a quoted argument,
                    182: escape it from ending the argument by doubling it.
                    183: .Pp
1.17      schwarze  184: The line invoking the macro will be replaced
1.15      kristaps  185: in the input stream by the
                    186: .Ar macro definition ,
                    187: replacing all occurrences of
                    188: .No \e\e$ Ns Ar N ,
1.17      schwarze  189: where
1.15      kristaps  190: .Ar N
                    191: is a digit, by the
                    192: .Ar N Ns th Ar argument .
                    193: For example,
                    194: .Bd -literal -offset indent
                    195: \&.de ZN
                    196: \efI\e^\e\e$1\e^\efP\e\e$2
                    197: \&..
                    198: \&.ZN XtFree .
                    199: .Ed
                    200: .Pp
                    201: produces
                    202: .Pp
                    203: .D1 \efI\e^XtFree\e^\efP.
                    204: .Pp
                    205: in the input stream, and thus in the output: \fI\^XtFree\^\fP.
                    206: .Pp
1.17      schwarze  207: Since macros and user-defined strings share a common string table,
1.15      kristaps  208: defining a macro
                    209: .Ar name
                    210: clobbers the user-defined string
                    211: .Ar name ,
                    212: and the
                    213: .Ar macro definition
                    214: can also be printed using the
                    215: .Sq \e*
                    216: string interpolation syntax described below
                    217: .Sx ds ,
                    218: but this is rarely useful because every macro definition contains at least
                    219: one explicit newline character.
1.16      schwarze  220: .Pp
                    221: In order to prevent endless recursion, both groff and
                    222: .Xr mandoc 1
                    223: limit the stack depth for expanding macros and strings
                    224: to a large, but finite number.
                    225: Do not rely on the exact value of this limit.
1.3       kristaps  226: .Ss \&dei
1.17      schwarze  227: Define a
1.15      kristaps  228: .Nm
                    229: macro, specifying the macro name indirectly.
1.17      schwarze  230: The syntax of this request is the same as that of
1.15      kristaps  231: .Sx \&de .
                    232: It is currently ignored by
                    233: .Xr mandoc 1 ,
                    234: as are its children.
                    235: .Ss \&de1
1.17      schwarze  236: Define a
1.15      kristaps  237: .Nm
                    238: macro that will be executed with
                    239: .Nm
                    240: compatibility mode switched off during macro execution.
                    241: This is a GNU extension not available in traditional
                    242: .Nm
                    243: implementations and not even in older versions of groff.
                    244: Since
                    245: .Xr mandoc 1
                    246: does not implement
                    247: .Nm
1.17      schwarze  248: compatibility mode at all, it handles this request as an alias for
1.15      kristaps  249: .Sx \&de .
1.6       schwarze  250: .Ss \&ds
1.15      kristaps  251: Define a user-defined string.
1.13      kristaps  252: Its syntax is as follows:
                    253: .Pp
1.15      kristaps  254: .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
1.13      kristaps  255: .Pp
                    256: The
1.15      kristaps  257: .Ar name
1.13      kristaps  258: and
1.15      kristaps  259: .Ar string
                    260: arguments are space-separated.
                    261: If the
                    262: .Ar string
                    263: begins with a double-quote character, that character will not be part
                    264: of the string.
                    265: All remaining characters on the input line form the
                    266: .Ar string ,
                    267: including whitespace and double-quote characters, even trailing ones.
                    268: .Pp
1.13      kristaps  269: The
1.15      kristaps  270: .Ar string
                    271: can be interpolated into subsequent text by using
                    272: .No \e* Ns Bq Ar name
                    273: for a
                    274: .Ar name
                    275: of arbitrary length, or \e*(NN or \e*N if the length of
                    276: .Ar name
                    277: is two or one characters, respectively.
1.17      schwarze  278: Interpolation can be prevented by escaping the leading backslash;
                    279: that is, an asterisk preceded by an even number of backslashes
                    280: does not trigger string interpolation.
1.15      kristaps  281: .Pp
                    282: Since user-defined strings and macros share a common string table,
                    283: defining a string
                    284: .Ar name
1.17      schwarze  285: clobbers the macro
1.15      kristaps  286: .Ar name ,
                    287: and the
                    288: .Ar name
                    289: used for defining a string can also be invoked as a macro,
                    290: in which case the following input line will be appended to the
                    291: .Ar string ,
                    292: forming a new input line passed to the
                    293: .Nm
                    294: parser.
                    295: For example,
                    296: .Bd -literal -offset indent
                    297: \&.ds badidea .S
                    298: \&.badidea
                    299: H SYNOPSIS
                    300: .Ed
                    301: .Pp
                    302: invokes the
                    303: .Cm SH
                    304: macro when used in a
                    305: .Xr man 7
                    306: document.
                    307: Such abuse is of course strongly discouraged.
1.5       kristaps  308: .Ss \&el
                    309: The
                    310: .Qq else
                    311: half of an if/else conditional.
                    312: Pops a result off the stack of conditional evaluations pushed by
                    313: .Sx \&ie
                    314: and uses it as its conditional.
                    315: If no stack entries are present (e.g., due to no prior
                    316: .Sx \&ie
                    317: calls)
                    318: then false is assumed.
1.17      schwarze  319: The syntax of this request is similar to
1.5       kristaps  320: .Sx \&if
                    321: except that the conditional is missing.
1.15      kristaps  322: .Ss \&hy
                    323: Set automatic hyphenation mode.
                    324: This line-scoped request is currently ignored.
1.5       kristaps  325: .Ss \&ie
                    326: The
                    327: .Qq if
                    328: half of an if/else conditional.
                    329: The result of the conditional is pushed into a stack used by subsequent
                    330: invocations of
                    331: .Sx \&el ,
                    332: which may be separated by any intervening input (or not exist at all).
                    333: Its syntax is equivalent to
                    334: .Sx \&if .
1.1       kristaps  335: .Ss \&if
1.7       schwarze  336: Begins a conditional.
                    337: Right now, the conditional evaluates to true
                    338: if and only if it starts with the letter
                    339: .Sy n ,
1.17      schwarze  340: indicating processing in nroff style as opposed to troff style.
1.3       kristaps  341: If a conditional is false, its children are not processed, but are
                    342: syntactically interpreted to preserve the integrity of the input
                    343: document.
                    344: Thus,
                    345: .Pp
1.17      schwarze  346: .D1 \&.if t .ig
1.3       kristaps  347: .Pp
                    348: will discard the
                    349: .Sq \&.ig ,
                    350: which may lead to interesting results, but
                    351: .Pp
1.17      schwarze  352: .D1 \&.if t .if t \e{\e
1.3       kristaps  353: .Pp
                    354: will continue to syntactically interpret to the block close of the final
                    355: conditional.
                    356: Sub-conditionals, in this case, obviously inherit the truth value of
                    357: the parent.
1.17      schwarze  358: This request has the following syntax:
                    359: .Bd -literal -offset indent
1.1       kristaps  360: \&.if COND \e{\e
                    361: BODY...
                    362: \&.\e}
                    363: .Ed
1.17      schwarze  364: .Bd -literal -offset indent
1.1       kristaps  365: \&.if COND \e{ BODY
1.2       kristaps  366: BODY... \e}
                    367: .Ed
1.17      schwarze  368: .Bd -literal -offset indent
1.2       kristaps  369: \&.if COND \e{ BODY
1.1       kristaps  370: BODY...
                    371: \&.\e}
                    372: .Ed
1.17      schwarze  373: .Bd -literal -offset indent
1.1       kristaps  374: \&.if COND \e
                    375: BODY
                    376: .Ed
                    377: .Pp
1.9       kristaps  378: COND is a conditional statement.
                    379: roff allows for complicated conditionals; mandoc is much simpler.
                    380: At this time, mandoc supports only
                    381: .Sq n ,
                    382: evaluating to true;
                    383: and
                    384: .Sq t ,
                    385: .Sq e ,
                    386: and
                    387: .Sq o ,
                    388: evaluating to false.
                    389: All other invocations are read up to the next end of line or space and
                    390: evaluate as false.
1.1       kristaps  391: .Pp
                    392: If the BODY section is begun by an escaped brace
                    393: .Sq \e{ ,
1.17      schwarze  394: scope continues until a closing-brace escape sequence
1.1       kristaps  395: .Sq \.\e} .
1.17      schwarze  396: If the BODY is not enclosed in braces, scope continues until
                    397: the end of the line.
1.1       kristaps  398: If the COND is followed by a BODY on the same line, whether after a
1.17      schwarze  399: brace or not, then requests and macros
1.1       kristaps  400: .Em must
                    401: begin with a control character.
                    402: It is generally more intuitive, in this case, to write
                    403: .Bd -literal -offset indent
                    404: \&.if COND \e{\e
                    405: \&.foo
                    406: bar
                    407: \&.\e}
                    408: .Ed
                    409: .Pp
1.17      schwarze  410: than having the request or macro follow as
1.1       kristaps  411: .Pp
                    412: .D1 \&.if COND \e{ .foo
                    413: .Pp
                    414: The scope of a conditional is always parsed, but only executed if the
                    415: conditional evaluates to true.
                    416: .Pp
1.17      schwarze  417: Note that text following an
1.2       kristaps  418: .Sq \&.\e}
1.17      schwarze  419: escape sequence is discarded.
1.2       kristaps  420: Furthermore, if an explicit closing sequence
1.1       kristaps  421: .Sq \e}
1.2       kristaps  422: is specified in a free-form line, the entire line is accepted within the
1.17      schwarze  423: scope of the prior request, not only the text preceding the close, with the
1.8       kristaps  424: .Sq \e}
                    425: collapsing into a zero-width space.
1.1       kristaps  426: .Ss \&ig
1.2       kristaps  427: Ignore input.
1.15      kristaps  428: Its syntax can be either
                    429: .Bd -literal -offset indent
                    430: .Pf . Cm \&ig
                    431: .Ar ignored text
1.2       kristaps  432: \&..
                    433: .Ed
1.15      kristaps  434: .Pp
                    435: or
                    436: .Bd -literal -offset indent
                    437: .Pf . Cm \&ig Ar end
                    438: .Ar ignored text
                    439: .Pf . Ar end
1.2       kristaps  440: .Ed
                    441: .Pp
                    442: In the first case, input is ignored until a
                    443: .Sq \&..
1.17      schwarze  444: request is encountered on its own line.
1.15      kristaps  445: In the second case, input is ignored until the specified
                    446: .Sq Pf . Ar end
                    447: macro is encountered.
                    448: Do not use the escape character
1.2       kristaps  449: .Sq \e
1.15      kristaps  450: anywhere in the definition of
                    451: .Ar end ;
                    452: it would cause very strange behaviour.
                    453: .Pp
                    454: When the
                    455: .Ar end
                    456: macro is a roff request or a roff macro, like in
1.2       kristaps  457: .Pp
                    458: .D1 \&.ig if
                    459: .Pp
                    460: the subsequent invocation of
                    461: .Sx \&if
1.15      kristaps  462: will first terminate the
                    463: .Ar ignored text ,
                    464: then be invoked as usual.
                    465: Otherwise, it only terminates the
                    466: .Ar ignored text ,
                    467: and arguments following it or the
                    468: .Sq \&..
1.17      schwarze  469: request are discarded.
1.15      kristaps  470: .Ss \&ne
                    471: Declare the need for the specified minimum vertical space
                    472: before the next trap or the bottom of the page.
                    473: This line-scoped request is currently ignored.
                    474: .Ss \&nh
                    475: Turn off automatic hyphenation mode.
                    476: This line-scoped request is currently ignored.
1.6       schwarze  477: .Ss \&rm
                    478: Remove a request, macro or string.
1.15      kristaps  479: This request is intended to have one argument,
1.6       schwarze  480: the name of the request, macro or string to be undefined.
                    481: Currently, it is ignored including its arguments,
                    482: and the number of arguments is not checked.
1.10      kristaps  483: .Ss \&nr
                    484: Define a register.
                    485: A register is an arbitrary string value that defines some sort of state,
                    486: which influences parsing and/or formatting.
                    487: Its syntax is as follows:
                    488: .Pp
1.15      kristaps  489: .D1 Pf \. Cm \&nr Ar name Ar value
1.10      kristaps  490: .Pp
                    491: The
1.15      kristaps  492: .Ar value
1.10      kristaps  493: may, at the moment, only be an integer.
1.15      kristaps  494: So far, only the following register
                    495: .Ar name
                    496: is recognised:
1.10      kristaps  497: .Bl -tag -width Ds
                    498: .It Cm nS
                    499: If set to a positive integer value, certain
                    500: .Xr mdoc 7
1.17      schwarze  501: macros will behave in the same way as in the
1.10      kristaps  502: .Em SYNOPSIS
1.11      kristaps  503: section.
1.17      schwarze  504: If set to 0, these macros will behave in the same way as outside the
                    505: .Em SYNOPSIS
                    506: section, even when called within the
1.10      kristaps  507: .Em SYNOPSIS
1.17      schwarze  508: section itself.
                    509: Note that starting a new
1.11      kristaps  510: .Xr mdoc 7
1.17      schwarze  511: section with the
                    512: .Cm \&Sh
                    513: macro will reset this register.
1.10      kristaps  514: .El
1.15      kristaps  515: .Ss \&so
                    516: Include a source file.
                    517: Its syntax is as follows:
                    518: .Pp
                    519: .D1 Pf \. Cm \&so Ar file
                    520: .Pp
                    521: The
                    522: .Ar file
                    523: will be read and its contents processed as input in place of the
                    524: .Sq \&.so
                    525: request line.
                    526: To avoid inadvertant inclusion of unrelated files,
                    527: .Xr mandoc 1
                    528: only accepts relative paths not containing the strings
                    529: .Qq ../
                    530: and
                    531: .Qq /.. .
1.6       schwarze  532: .Ss \&tr
                    533: Output character translation.
1.17      schwarze  534: This request is intended to have one argument,
1.6       schwarze  535: consisting of an even number of characters.
                    536: Currently, it is ignored including its arguments,
                    537: and the number of arguments is not checked.
1.20      kristaps  538: .Ss \&T&
                    539: Re-start a table layout, retaining the options of the prior table
                    540: invocation.
                    541: See
                    542: .Sx \&TS .
                    543: .Ss \&TE
                    544: End a table context.
                    545: See
                    546: .Sx \&TS .
                    547: .Ss \&TS
                    548: Begin a table, which formats input in aligned rows and columns.
                    549: A table consists of an optional single line of table options terminated
                    550: by a semicolon, followed by one or more lines of layout specification
                    551: terminated by a period, then table data.
                    552: A table block may also include
                    553: .Nm ,
                    554: .Xr mdoc 7 ,
                    555: or
                    556: .Xr man 7
                    557: macros.
                    558: Example:
                    559: .Bd -literal -offset indent
                    560: \&.TS
                    561: box tab(:);   \e" Table-wide options.
                    562: c | c         \e" Layout for first line.
                    563: | c | c.      \e" Layout for all subsequent lines.
                    564: 1:2           \e" Data...
                    565: 3:4
                    566: \&.TE
                    567: .Ed
                    568: .Pp
                    569: Table data is
                    570: .Em pre-processed ,
                    571: that is, data rows are parsed then inserted into the underlying stream
                    572: of input data.
                    573: This allows data rows to be interspersed by arbitrary macros, such as
                    574: .Bd -literal -offset indent
                    575: \&.TS
                    576: tab(:);
                    577: c c c.
                    578: 1:2:3
                    579: \&.Ao
                    580: 3:2:1
                    581: \&.Ac
                    582: \&.TE
                    583: .Ed
                    584: .Pp
                    585: in the case of
                    586: .Xr mdoc 7
                    587: or
                    588: .Bd -literal -offset indent
                    589: \&.TS
                    590: tab(:);
                    591: c c c.
                    592: \&.ds ab 2
                    593: 1:\e*(ab:3
                    594: \&.I
                    595: 3:2:1
                    596: \&.TE
                    597: .Ed
                    598: .Pp
                    599: in the case of
                    600: .Xr man 7 .
                    601: .Pp
                    602: The first line of a table consists of its options, which consists of
                    603: space-separated keys and modifiers terminated by a semicolon.
                    604: If the first line does not have a terminating semicolon, it is assumed
                    605: that no options are specified and instead a layout is processed.
                    606: Some options accept arguments enclosed by paranthesis.
                    607: The following case-insensitive options are available:
                    608: .Bl -tag -width Ds
                    609: .It Cm center
                    610: This option is not supported by
                    611: .Xr mandoc 1 .
                    612: This may also be invoked with
                    613: .Cm centre .
                    614: .It Cm delim
                    615: Accepts a two-character argument.
                    616: This option is not supported by
                    617: .Xr mandoc 1 .
                    618: .It Cm expand
                    619: This option is not supported by
                    620: .Xr mandoc 1 .
                    621: .It Cm box
                    622: Draw a single-line box around the table.
                    623: This may also be invoked with
                    624: .Cm frame .
                    625: .It Cm doublebox
                    626: Draw a double-line box around the table.
                    627: This may also be invoked with
                    628: .Cm doubleframe .
                    629: .It Cm allbox
                    630: This option is not supported by
                    631: .Xr mandoc 1 .
                    632: .It Cm tab
                    633: Accepts a single-character argument.
                    634: This character is used a delimiter between data cells, which otherwise
                    635: defaults to the tab character.
                    636: .It Cm linesize
                    637: Accepts a natural number (all digits).
                    638: This option is not supported by
                    639: .Xr mandoc 1 .
                    640: .It Cm nokeep
                    641: This option is not supported by
                    642: .Xr mandoc 1 .
                    643: .It Cm decimalpoint
                    644: Accepts a single-character argument.
                    645: This character will be used as the decimal point with the
                    646: .Cm n
                    647: layout key.
                    648: This option is not supported by
                    649: .Xr mandoc 1 .
                    650: .It Cm nospaces
                    651: This option is not supported by
                    652: .Xr mandoc 1 .
                    653: .El
                    654: .Pp
                    655: The table layout follows table options, except in the case of
                    656: .Sx \&T& ,
                    657: where it immediately procedes invocation.
                    658: Layout specifies how data rows are displayed on output.
                    659: Each layout line corresponds to a line of data; the last layout line
                    660: applies to all remaining data lines.
                    661: Layout lines may also be separated by a comma.
                    662: Each layout cell consists of one of the following case-insensitive keys:
                    663: .Bl -tag -width Ds
                    664: .It Cm c
                    665: Centre a literal string within its column.
                    666: .It Cm r
                    667: Right-justify a literal string within its column.
                    668: .It Cm l
                    669: Left-justify a literal string within its column.
                    670: .It Cm n
                    671: Justify a number around its decimal point.
                    672: If the decimal point is not found on the number, it's assumed to trail
                    673: the number.
                    674: .It Cm s
                    675: This option is not supported by
                    676: .Xr mandoc 1 .
                    677: .It Cm a
                    678: This option is not supported by
                    679: .Xr mandoc 1 .
                    680: .It Cm ^
                    681: This option is not supported by
                    682: .Xr mandoc 1 .
                    683: .It Cm \-
1.21    ! kristaps  684: Replace the data cell (its contents will be lost) with a single
        !           685: horizontal line.
1.20      kristaps  686: This may also be invoked with
                    687: .Cm _ .
                    688: .It Cm =
1.21    ! kristaps  689: Replace the data cell (its contents will be lost) with a double
        !           690: horizontal line.
1.20      kristaps  691: .It Cm \(ba
                    692: Emit a vertical bar instead of data.
                    693: .It Cm \(ba\(ba
                    694: Emit a double-vertical bar instead of data.
                    695: .El
                    696: .Pp
1.21    ! kristaps  697: For example, following layout specifies a centre-justified column of
        !           698: minimum width 10, followed by vertical bar, followed by a left-justified
        !           699: column of minimum width 10, another vertical bar, then a column
        !           700: justified about the decimal point in numbers:
        !           701: .Pp
        !           702: .Dl c10 | l10 | n
        !           703: .Pp
1.20      kristaps  704: Keys may be followed by a set of modifiers.
                    705: A modifier is either a modifier key or a natural number for specifying
                    706: spacing.
                    707: The following case-insensitive modifier keys are available:
1.21    ! kristaps  708: .Cm z ,
        !           709: .Cm u ,
        !           710: .Cm e ,
        !           711: .Cm t ,
        !           712: .Cm d ,
        !           713: .Cm f ,
        !           714: .Cm b ,
        !           715: .Cm i ,
        !           716: .Cm b ,
        !           717: and
        !           718: .Cm i .
        !           719: All of these are ignored by
        !           720: .Xr mandoc 1 .
        !           721: .Pp
        !           722: The data section follows the last layout row.
        !           723: By default, cells in a data section are delimited by a tab.
        !           724: This behaviour may be changed with the
        !           725: .Cm tab
        !           726: option.
        !           727: If
        !           728: .Cm _
        !           729: or
        !           730: .Cm =
        !           731: is specified, a single or double line, respectively, is drawn across the
        !           732: data field.
        !           733: If
        !           734: .Cm \e-
        !           735: or
        !           736: .Cm \e=
        !           737: is specified, a line is drawn within the data field (i.e., terminating
        !           738: within the cell and not draw to the border).
1.2       kristaps  739: .Sh COMPATIBILITY
                    740: This section documents compatibility between mandoc and other other
1.17      schwarze  741: .Nm
                    742: implementations, at this time limited to GNU troff
1.2       kristaps  743: .Pq Qq groff .
                    744: The term
                    745: .Qq historic groff
1.17      schwarze  746: refers to groff version 1.15.
1.2       kristaps  747: .Pp
                    748: .Bl -dash -compact
1.10      kristaps  749: .It
                    750: The
                    751: .Cm nS
1.17      schwarze  752: register is only compatible with OpenBSD's groff-1.15.
1.2       kristaps  753: .It
1.17      schwarze  754: Historic groff did not accept white-space before a custom
                    755: .Ar end
                    756: macro for the
1.2       kristaps  757: .Sx \&ig
1.17      schwarze  758: request.
1.4       kristaps  759: .It
                    760: The
                    761: .Sx \&if
                    762: and family would print funny white-spaces with historic groff when
1.17      schwarze  763: using the next-line syntax.
1.2       kristaps  764: .El
1.17      schwarze  765: .Sh SEE ALSO
                    766: .Xr mandoc 1 ,
                    767: .Xr man 7 ,
                    768: .Xr mandoc_char 7 ,
                    769: .Xr mdoc 7
1.21    ! kristaps  770: .Rs
        !           771: .%A M. E. Lesk
        !           772: .%T Tbl\(emA Program to Format Tables
        !           773: .%D June 11, 1976
        !           774: .%U http://www.kohala.com/start/troff/v7/man/tbl/tbl.ps
        !           775: .Re
1.17      schwarze  776: .Rs
                    777: .%A Joseph F. Ossanna
                    778: .%A Brian W. Kernighan
                    779: .%I AT&T Bell Laboratories
                    780: .%T Troff User's Manual
                    781: .%R Computing Science Technical Report
                    782: .%N 54
                    783: .%C Murray Hill, New Jersey
                    784: .%D 1976 and 1992
                    785: .%U http://www.kohala.com/start/troff/cstr54.ps
                    786: .Re
                    787: .Rs
                    788: .%A Joseph F. Ossanna
                    789: .%A Brian W. Kernighan
                    790: .%A Gunnar Ritter
                    791: .%T Heirloom Documentation Tools Nroff/Troff User's Manual
                    792: .%D September 17, 2007
                    793: .%U http://heirloom.sourceforge.net/doctools/troff.pdf
                    794: .Re
                    795: .Sh HISTORY
                    796: The RUNOFF typesetting system was written in PL/1 for the CTSS
                    797: operating system by Jerome ("Jerry") E. Saltzer in 1961.
                    798: It was first used as the main documentation tool by Multics since 1963.
                    799: Robert ("Bob") H. Morris ported it to the GE-635 and called it
                    800: .Nm ,
                    801: Doug McIlroy rewrote it in BCPL in 1969,
                    802: Joseph F. Ossanna rewrote it in PDP-11 assembly in 1973,
                    803: and Brian W. Kernighan rewrote it in C in 1975.
1.1       kristaps  804: .Sh AUTHORS
1.15      kristaps  805: .An -nosplit
                    806: This partial
1.1       kristaps  807: .Nm
                    808: reference was written by
1.15      kristaps  809: .An Kristaps Dzonsons Aq kristaps@bsd.lv
                    810: and
                    811: .An Ingo Schwarze Aq schwarze@openbsd.org .

CVSweb