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

Annotation of mandoc/roff.7, Revision 1.8

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

CVSweb