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