Annotation of mandoc/roff.7, Revision 1.1
1.1 ! kristaps 1: .\" $Id$
! 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: .\"
! 17: .Dd $Mdocdate$
! 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
! 79: BODY...
! 80: \&.\e}
! 81: .Ed
! 82: .Bd -literal -offset indent -compact
! 83: \&.if COND \e
! 84: BODY
! 85: .Ed
! 86: .Pp
! 87: COND is a conditional (TODO: document).
! 88: .Pp
! 89: If the BODY section is begun by an escaped brace
! 90: .Sq \e{ ,
! 91: scope continues until a closing-brace macro
! 92: .Sq \.\e} .
! 93: If the BODY is not enclosed in braces, scope continues until the next
! 94: macro or word.
! 95: If the COND is followed by a BODY on the same line, whether after a
! 96: brace or not, then macros
! 97: .Em must
! 98: begin with a control character.
! 99: It is generally more intuitive, in this case, to write
! 100: .Bd -literal -offset indent
! 101: \&.if COND \e{\e
! 102: \&.foo
! 103: bar
! 104: \&.\e}
! 105: .Ed
! 106: .Pp
! 107: than having the macro follow as
! 108: .Pp
! 109: .D1 \&.if COND \e{ .foo
! 110: .Pp
! 111: The scope of a conditional is always parsed, but only executed if the
! 112: conditional evaluates to true.
! 113: .Pp
! 114: Note that text subsequent a
! 115: .Sq \e}
! 116: is discarded.
! 117: .Ss \&ig
! 118: Ignore input until a
! 119: .Sq \.\.
! 120: macro is encountered on its own line.
! 121: Note that text subsequent the
! 122: .Sq \.\.
! 123: is discarded.
! 124: .Sh AUTHORS
! 125: The
! 126: .Nm
! 127: reference was written by
! 128: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb