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

Annotation of mandoc/roff.7, Revision 1.10

1.10    ! kristaps    1: .\"    $Id: roff.7,v 1.9 2010/06/10 21:42:02 kristaps 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.10    ! kristaps   17: .Dd $Mdocdate: June 10 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.9       kristaps  176: COND is a conditional statement.
                    177: roff allows for complicated conditionals; mandoc is much simpler.
                    178: At this time, mandoc supports only
                    179: .Sq n ,
                    180: evaluating to true;
                    181: and
                    182: .Sq t ,
                    183: .Sq e ,
                    184: and
                    185: .Sq o ,
                    186: evaluating to false.
                    187: All other invocations are read up to the next end of line or space and
                    188: evaluate as false.
1.1       kristaps  189: .Pp
                    190: If the BODY section is begun by an escaped brace
                    191: .Sq \e{ ,
                    192: scope continues until a closing-brace macro
                    193: .Sq \.\e} .
                    194: If the BODY is not enclosed in braces, scope continues until the next
                    195: macro or word.
                    196: If the COND is followed by a BODY on the same line, whether after a
                    197: brace or not, then macros
                    198: .Em must
                    199: begin with a control character.
                    200: It is generally more intuitive, in this case, to write
                    201: .Bd -literal -offset indent
                    202: \&.if COND \e{\e
                    203: \&.foo
                    204: bar
                    205: \&.\e}
                    206: .Ed
                    207: .Pp
                    208: than having the macro follow as
                    209: .Pp
                    210: .D1 \&.if COND \e{ .foo
                    211: .Pp
                    212: The scope of a conditional is always parsed, but only executed if the
                    213: conditional evaluates to true.
                    214: .Pp
                    215: Note that text subsequent a
1.2       kristaps  216: .Sq \&.\e}
                    217: macro is discarded.
                    218: Furthermore, if an explicit closing sequence
1.1       kristaps  219: .Sq \e}
1.2       kristaps  220: is specified in a free-form line, the entire line is accepted within the
1.8       kristaps  221: scope of the prior macro, not only the text preceding the close, with the
                    222: .Sq \e}
                    223: collapsing into a zero-width space.
1.1       kristaps  224: .Ss \&ig
1.2       kristaps  225: Ignore input.
                    226: Accepts the following syntax:
                    227: .Pp
                    228: .Bd -literal -offset indent -compact
                    229: \&.ig
                    230: BODY...
                    231: \&..
                    232: .Ed
                    233: .Bd -literal -offset indent -compact
                    234: \&.ig END
                    235: BODY...
                    236: \&.END
                    237: .Ed
                    238: .Pp
                    239: In the first case, input is ignored until a
                    240: .Sq \&..
1.1       kristaps  241: macro is encountered on its own line.
1.2       kristaps  242: In the second case, input is ignored until a
                    243: .Sq \&.END
                    244: is encountered.
                    245: Text subsequent the
                    246: .Sq \&.END
                    247: or
                    248: .Sq \&..
1.1       kristaps  249: is discarded.
1.2       kristaps  250: .Pp
                    251: Do not use the escape
                    252: .Sq \e
                    253: anywhere in the definition of END.
                    254: It causes very strange behaviour.
                    255: Furthermore, if you redefine a
                    256: .Nm
                    257: macro, such as
                    258: .Pp
                    259: .D1 \&.ig if
                    260: .Pp
                    261: the subsequent invocation of
                    262: .Sx \&if
                    263: will first signify the end of comment, then be invoked as a macro.
                    264: This behaviour really shouldn't be counted upon.
1.6       schwarze  265: .Ss \&rm
                    266: Remove a request, macro or string.
                    267: This macro is intended to have one argument,
                    268: the name of the request, macro or string to be undefined.
                    269: Currently, it is ignored including its arguments,
                    270: and the number of arguments is not checked.
1.10    ! kristaps  271: .Ss \&nr
        !           272: Define a register.
        !           273: A register is an arbitrary string value that defines some sort of state,
        !           274: which influences parsing and/or formatting.
        !           275: Its syntax is as follows:
        !           276: .Pp
        !           277: .D1 Pf \. Sx \&nr Cm name value
        !           278: .Pp
        !           279: The
        !           280: .Cm value
        !           281: may, at the moment, only be an integer.
        !           282: The
        !           283: .Cm name
        !           284: is defined up to the next whitespace.
        !           285: The following register
        !           286: .Cm name
        !           287: requests are recognised:
        !           288: .Bl -tag -width Ds
        !           289: .It Cm nS
        !           290: If set to a positive integer value, certain
        !           291: .Xr mdoc 7
        !           292: macros will behave as if they are defined in the
        !           293: .Em SYNOPSIS
        !           294: section to a manual.
        !           295: Otherwise, this behaviour is unset (even if called within the
        !           296: .Em SYNOPSIS
        !           297: section itself).
        !           298: .El
1.6       schwarze  299: .Ss \&tr
                    300: Output character translation.
1.7       schwarze  301: This macro is intended to have one argument,
1.6       schwarze  302: consisting of an even number of characters.
                    303: Currently, it is ignored including its arguments,
                    304: and the number of arguments is not checked.
1.2       kristaps  305: .Sh COMPATIBILITY
                    306: This section documents compatibility between mandoc and other other
                    307: troff implementations, at this time limited to GNU troff
                    308: .Pq Qq groff .
                    309: The term
                    310: .Qq historic groff
                    311: refers to groff versions before the
                    312: .Pa doc.tmac
                    313: file re-write
                    314: .Pq somewhere between 1.15 and 1.19 .
                    315: .Pp
                    316: .Bl -dash -compact
1.10    ! kristaps  317: .It
        !           318: The
        !           319: .Cm nS
        !           320: request to
        !           321: .Sx \&nr
        !           322: is only compatible with OpenBSD's groff.
1.2       kristaps  323: .It
                    324: Historic groff did not accept white-space buffering the custom END tag
                    325: for the
                    326: .Sx \&ig
                    327: macro.
1.4       kristaps  328: .It
                    329: The
                    330: .Sx \&if
                    331: and family would print funny white-spaces with historic groff when
                    332: depending on next-line syntax.
1.2       kristaps  333: .El
1.1       kristaps  334: .Sh AUTHORS
                    335: The
                    336: .Nm
                    337: reference was written by
                    338: .An Kristaps Dzonsons Aq kristaps@bsd.lv .

CVSweb