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

Annotation of mandoc/roff.7, Revision 1.14

1.14    ! kristaps    1: .\"    $Id: roff.7,v 1.13 2010/07/07 15:04:54 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.14    ! kristaps   18: .Dd $Mdocdate: July 7 2010 $
1.1       kristaps   19: .Dt ROFF 7
                     20: .Os
                     21: .Sh NAME
                     22: .Nm roff
                     23: .Nd roff language reference
                     24: .Sh DESCRIPTION
                     25: The
                     26: .Nm roff
                     27: language is a general-purpose text-formatting language.  The purpose of
                     28: this document is to consistently describe those language constructs
                     29: accepted by the
                     30: .Xr mandoc 1
                     31: utility.  It is a work in progress.
                     32: .Pp
                     33: An
                     34: .Nm
                     35: document follows simple rules:  lines beginning with the control
                     36: characters
                     37: .Sq \.
                     38: or
                     39: .Sq \(aq
                     40: are parsed for macros.  Other lines are interpreted within the scope of
                     41: prior macros:
                     42: .Bd -literal -offset indent
                     43: \&.xx Macro lines change control state.
                     44: Other lines are interpreted within the current state.
                     45: .Ed
                     46: .Sh LANGUAGE SYNTAX
                     47: .Nm
                     48: documents may contain only graphable 7-bit ASCII characters, the space
                     49: character, and, in certain circumstances, the tab character.  All
                     50: manuals must have
                     51: .Ux
                     52: line terminators.
                     53: .Sh MACRO SYNTAX
                     54: Macros are arbitrary in length and begin with a control character ,
                     55: .Sq \.
                     56: or
                     57: .Sq \(aq ,
                     58: at the beginning of the line.
                     59: An arbitrary amount of whitespace may sit between the control character
                     60: and the macro name.
                     61: Thus, the following are equivalent:
                     62: .Bd -literal -offset indent
                     63: \&.if
                     64: \&.\ \ \ \&if
                     65: .Ed
                     66: .Sh REFERENCE
                     67: This section is a canonical reference of all macros, arranged
                     68: alphabetically.
1.3       kristaps   69: .Ss \&am
                     70: The syntax of this macro is the same as that of
                     71: .Sx \&ig ,
                     72: except that a leading argument must be specified.
                     73: It is ignored, as are its children.
                     74: .Ss \&ami
                     75: The syntax of this macro is the same as that of
                     76: .Sx \&ig ,
                     77: except that a leading argument must be specified.
                     78: It is ignored, as are its children.
                     79: .Ss \&am1
                     80: The syntax of this macro is the same as that of
                     81: .Sx \&ig ,
                     82: except that a leading argument must be specified.
                     83: It is ignored, as are its children.
                     84: .Ss \&de
                     85: The syntax of this macro is the same as that of
                     86: .Sx \&ig ,
                     87: except that a leading argument must be specified.
                     88: It is ignored, as are its children.
                     89: .Ss \&dei
                     90: The syntax of this macro is the same as that of
                     91: .Sx \&ig ,
                     92: except that a leading argument must be specified.
                     93: It is ignored, as are its children.
1.6       schwarze   94: .Ss \&ds
1.13      kristaps   95: Define a reserved word.
                     96: Its syntax is as follows:
                     97: .Pp
                     98: .D1 Pf \. Sx \&ds No Cm key val
                     99: .Pp
                    100: The
                    101: .Cm key
                    102: and
                    103: .Cm val
                    104: strings are space-separated.
                    105: The
                    106: .Cm key
                    107: values may be invoked in subsequent text by using \e*(NN for two-letter
                    108: pairs, \e*N for one-letter, and \e*[NNN] for arbitrary-length values.
1.14    ! kristaps  109: .Pp
        !           110: If
        !           111: .Cm val
        !           112: is begun with a double-quote mark, the mark is passed over.
        !           113: .Cm val
        !           114: consists of
        !           115: .Em all
        !           116: text following this point, including whitespace and trailing
        !           117: double-quotes.
1.3       kristaps  118: .Ss \&de1
                    119: The syntax of this macro is the same as that of
                    120: .Sx \&ig ,
                    121: except that a leading argument must be specified.
                    122: It is ignored, as are its children.
1.5       kristaps  123: .Ss \&el
                    124: The
                    125: .Qq else
                    126: half of an if/else conditional.
                    127: Pops a result off the stack of conditional evaluations pushed by
                    128: .Sx \&ie
                    129: and uses it as its conditional.
                    130: If no stack entries are present (e.g., due to no prior
                    131: .Sx \&ie
                    132: calls)
                    133: then false is assumed.
                    134: The syntax of this macro is similar to
                    135: .Sx \&if
                    136: except that the conditional is missing.
                    137: .Ss \&ie
                    138: The
                    139: .Qq if
                    140: half of an if/else conditional.
                    141: The result of the conditional is pushed into a stack used by subsequent
                    142: invocations of
                    143: .Sx \&el ,
                    144: which may be separated by any intervening input (or not exist at all).
                    145: Its syntax is equivalent to
                    146: .Sx \&if .
1.1       kristaps  147: .Ss \&if
1.7       schwarze  148: Begins a conditional.
                    149: Right now, the conditional evaluates to true
                    150: if and only if it starts with the letter
                    151: .Sy n ,
                    152: indicating processing in
                    153: .Xr nroff 1
                    154: style as opposed to
                    155: .Xr troff 1
                    156: style.
1.3       kristaps  157: If a conditional is false, its children are not processed, but are
                    158: syntactically interpreted to preserve the integrity of the input
                    159: document.
                    160: Thus,
                    161: .Pp
                    162: .D1 \&.if t \e .ig
                    163: .Pp
                    164: will discard the
                    165: .Sq \&.ig ,
                    166: which may lead to interesting results, but
                    167: .Pp
                    168: .D1 \&.if t \e .if t \e{\e
                    169: .Pp
                    170: will continue to syntactically interpret to the block close of the final
                    171: conditional.
                    172: Sub-conditionals, in this case, obviously inherit the truth value of
                    173: the parent.
                    174: This macro has the following syntax:
1.1       kristaps  175: .Pp
                    176: .Bd -literal -offset indent -compact
                    177: \&.if COND \e{\e
                    178: BODY...
                    179: \&.\e}
                    180: .Ed
                    181: .Bd -literal -offset indent -compact
                    182: \&.if COND \e{ BODY
1.2       kristaps  183: BODY... \e}
                    184: .Ed
                    185: .Bd -literal -offset indent -compact
                    186: \&.if COND \e{ BODY
1.1       kristaps  187: BODY...
                    188: \&.\e}
                    189: .Ed
                    190: .Bd -literal -offset indent -compact
                    191: \&.if COND \e
                    192: BODY
                    193: .Ed
                    194: .Pp
1.9       kristaps  195: COND is a conditional statement.
                    196: roff allows for complicated conditionals; mandoc is much simpler.
                    197: At this time, mandoc supports only
                    198: .Sq n ,
                    199: evaluating to true;
                    200: and
                    201: .Sq t ,
                    202: .Sq e ,
                    203: and
                    204: .Sq o ,
                    205: evaluating to false.
                    206: All other invocations are read up to the next end of line or space and
                    207: evaluate as false.
1.1       kristaps  208: .Pp
                    209: If the BODY section is begun by an escaped brace
                    210: .Sq \e{ ,
                    211: scope continues until a closing-brace macro
                    212: .Sq \.\e} .
                    213: If the BODY is not enclosed in braces, scope continues until the next
                    214: macro or word.
                    215: If the COND is followed by a BODY on the same line, whether after a
                    216: brace or not, then macros
                    217: .Em must
                    218: begin with a control character.
                    219: It is generally more intuitive, in this case, to write
                    220: .Bd -literal -offset indent
                    221: \&.if COND \e{\e
                    222: \&.foo
                    223: bar
                    224: \&.\e}
                    225: .Ed
                    226: .Pp
                    227: than having the macro follow as
                    228: .Pp
                    229: .D1 \&.if COND \e{ .foo
                    230: .Pp
                    231: The scope of a conditional is always parsed, but only executed if the
                    232: conditional evaluates to true.
                    233: .Pp
                    234: Note that text subsequent a
1.2       kristaps  235: .Sq \&.\e}
                    236: macro is discarded.
                    237: Furthermore, if an explicit closing sequence
1.1       kristaps  238: .Sq \e}
1.2       kristaps  239: is specified in a free-form line, the entire line is accepted within the
1.8       kristaps  240: scope of the prior macro, not only the text preceding the close, with the
                    241: .Sq \e}
                    242: collapsing into a zero-width space.
1.1       kristaps  243: .Ss \&ig
1.2       kristaps  244: Ignore input.
                    245: Accepts the following syntax:
                    246: .Pp
                    247: .Bd -literal -offset indent -compact
                    248: \&.ig
                    249: BODY...
                    250: \&..
                    251: .Ed
                    252: .Bd -literal -offset indent -compact
                    253: \&.ig END
                    254: BODY...
                    255: \&.END
                    256: .Ed
                    257: .Pp
                    258: In the first case, input is ignored until a
                    259: .Sq \&..
1.1       kristaps  260: macro is encountered on its own line.
1.2       kristaps  261: In the second case, input is ignored until a
                    262: .Sq \&.END
                    263: is encountered.
                    264: Text subsequent the
                    265: .Sq \&.END
                    266: or
                    267: .Sq \&..
1.1       kristaps  268: is discarded.
1.2       kristaps  269: .Pp
                    270: Do not use the escape
                    271: .Sq \e
                    272: anywhere in the definition of END.
                    273: It causes very strange behaviour.
                    274: Furthermore, if you redefine a
                    275: .Nm
                    276: macro, such as
                    277: .Pp
                    278: .D1 \&.ig if
                    279: .Pp
                    280: the subsequent invocation of
                    281: .Sx \&if
                    282: will first signify the end of comment, then be invoked as a macro.
                    283: This behaviour really shouldn't be counted upon.
1.6       schwarze  284: .Ss \&rm
                    285: Remove a request, macro or string.
                    286: This macro is intended to have one argument,
                    287: the name of the request, macro or string to be undefined.
                    288: Currently, it is ignored including its arguments,
                    289: and the number of arguments is not checked.
1.10      kristaps  290: .Ss \&nr
                    291: Define a register.
                    292: A register is an arbitrary string value that defines some sort of state,
                    293: which influences parsing and/or formatting.
                    294: Its syntax is as follows:
                    295: .Pp
                    296: .D1 Pf \. Sx \&nr Cm name value
                    297: .Pp
                    298: The
                    299: .Cm value
                    300: may, at the moment, only be an integer.
                    301: The
                    302: .Cm name
                    303: is defined up to the next whitespace.
                    304: The following register
                    305: .Cm name
                    306: requests are recognised:
                    307: .Bl -tag -width Ds
                    308: .It Cm nS
                    309: If set to a positive integer value, certain
                    310: .Xr mdoc 7
1.11      kristaps  311: macros will behave as if they were defined in the
1.10      kristaps  312: .Em SYNOPSIS
1.11      kristaps  313: section.
1.10      kristaps  314: Otherwise, this behaviour is unset (even if called within the
                    315: .Em SYNOPSIS
                    316: section itself).
1.11      kristaps  317: Note that invoking a new
                    318: .Xr mdoc 7
                    319: section will unset this value.
1.10      kristaps  320: .El
1.6       schwarze  321: .Ss \&tr
                    322: Output character translation.
1.7       schwarze  323: This macro is intended to have one argument,
1.6       schwarze  324: consisting of an even number of characters.
                    325: Currently, it is ignored including its arguments,
                    326: and the number of arguments is not checked.
1.2       kristaps  327: .Sh COMPATIBILITY
                    328: This section documents compatibility between mandoc and other other
                    329: troff implementations, at this time limited to GNU troff
                    330: .Pq Qq groff .
                    331: The term
                    332: .Qq historic groff
                    333: refers to groff versions before the
                    334: .Pa doc.tmac
                    335: file re-write
                    336: .Pq somewhere between 1.15 and 1.19 .
                    337: .Pp
                    338: .Bl -dash -compact
1.10      kristaps  339: .It
                    340: The
                    341: .Cm nS
                    342: request to
                    343: .Sx \&nr
                    344: is only compatible with OpenBSD's groff.
1.2       kristaps  345: .It
                    346: Historic groff did not accept white-space buffering the custom END tag
                    347: for the
                    348: .Sx \&ig
                    349: macro.
1.4       kristaps  350: .It
                    351: The
                    352: .Sx \&if
                    353: and family would print funny white-spaces with historic groff when
                    354: depending on next-line syntax.
1.2       kristaps  355: .El
1.1       kristaps  356: .Sh AUTHORS
                    357: The
                    358: .Nm
                    359: reference was written by
                    360: .An Kristaps Dzonsons Aq kristaps@bsd.lv .

CVSweb