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

Annotation of mandoc/roff.7, Revision 1.2

1.2     ! kristaps    1: .\"    $Id: roff.7,v 1.1 2010/05/16 19:08:11 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.2     ! kristaps   17: .Dd $Mdocdate: May 16 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.
                     68: .Ss \&if
                     69: Begins a conditional.
                     70: Has the following syntax:
                     71: .Pp
                     72: .Bd -literal -offset indent -compact
                     73: \&.if COND \e{\e
                     74: BODY...
                     75: \&.\e}
                     76: .Ed
                     77: .Bd -literal -offset indent -compact
                     78: \&.if COND \e{ BODY
1.2     ! kristaps   79: BODY... \e}
        !            80: .Ed
        !            81: .Bd -literal -offset indent -compact
        !            82: \&.if COND \e{ BODY
1.1       kristaps   83: BODY...
                     84: \&.\e}
                     85: .Ed
                     86: .Bd -literal -offset indent -compact
                     87: \&.if COND \e
                     88: BODY
                     89: .Ed
                     90: .Pp
                     91: COND is a conditional (TODO: document).
                     92: .Pp
                     93: If the BODY section is begun by an escaped brace
                     94: .Sq \e{ ,
                     95: scope continues until a closing-brace macro
                     96: .Sq \.\e} .
                     97: If the BODY is not enclosed in braces, scope continues until the next
                     98: macro or word.
                     99: If the COND is followed by a BODY on the same line, whether after a
                    100: brace or not, then macros
                    101: .Em must
                    102: begin with a control character.
                    103: It is generally more intuitive, in this case, to write
                    104: .Bd -literal -offset indent
                    105: \&.if COND \e{\e
                    106: \&.foo
                    107: bar
                    108: \&.\e}
                    109: .Ed
                    110: .Pp
                    111: than having the macro follow as
                    112: .Pp
                    113: .D1 \&.if COND \e{ .foo
                    114: .Pp
                    115: The scope of a conditional is always parsed, but only executed if the
                    116: conditional evaluates to true.
                    117: .Pp
                    118: Note that text subsequent a
1.2     ! kristaps  119: .Sq \&.\e}
        !           120: macro is discarded.
        !           121: Furthermore, if an explicit closing sequence
1.1       kristaps  122: .Sq \e}
1.2     ! kristaps  123: is specified in a free-form line, the entire line is accepted within the
        !           124: scope of the prior macro, not only the text preceding the close.
1.1       kristaps  125: .Ss \&ig
1.2     ! kristaps  126: Ignore input.
        !           127: Accepts the following syntax:
        !           128: .Pp
        !           129: .Bd -literal -offset indent -compact
        !           130: \&.ig
        !           131: BODY...
        !           132: \&..
        !           133: .Ed
        !           134: .Bd -literal -offset indent -compact
        !           135: \&.ig END
        !           136: BODY...
        !           137: \&.END
        !           138: .Ed
        !           139: .Pp
        !           140: In the first case, input is ignored until a
        !           141: .Sq \&..
1.1       kristaps  142: macro is encountered on its own line.
1.2     ! kristaps  143: In the second case, input is ignored until a
        !           144: .Sq \&.END
        !           145: is encountered.
        !           146: Text subsequent the
        !           147: .Sq \&.END
        !           148: or
        !           149: .Sq \&..
1.1       kristaps  150: is discarded.
1.2     ! kristaps  151: .Pp
        !           152: Do not use the escape
        !           153: .Sq \e
        !           154: anywhere in the definition of END.
        !           155: It causes very strange behaviour.
        !           156: Furthermore, if you redefine a
        !           157: .Nm
        !           158: macro, such as
        !           159: .Pp
        !           160: .D1 \&.ig if
        !           161: .Pp
        !           162: the subsequent invocation of
        !           163: .Sx \&if
        !           164: will first signify the end of comment, then be invoked as a macro.
        !           165: This behaviour really shouldn't be counted upon.
        !           166: .Sh COMPATIBILITY
        !           167: This section documents compatibility between mandoc and other other
        !           168: troff implementations, at this time limited to GNU troff
        !           169: .Pq Qq groff .
        !           170: The term
        !           171: .Qq historic groff
        !           172: refers to groff versions before the
        !           173: .Pa doc.tmac
        !           174: file re-write
        !           175: .Pq somewhere between 1.15 and 1.19 .
        !           176: .Pp
        !           177: .Bl -dash -compact
        !           178: .It
        !           179: Historic groff did not accept white-space buffering the custom END tag
        !           180: for the
        !           181: .Sx \&ig
        !           182: macro.
        !           183: .El
1.1       kristaps  184: .Sh AUTHORS
                    185: The
                    186: .Nm
                    187: reference was written by
                    188: .An Kristaps Dzonsons Aq kristaps@bsd.lv .

CVSweb