Annotation of mandoc/roff.7, Revision 1.5
1.5 ! kristaps 1: .\" $Id: roff.7,v 1.4 2010/05/17 02:01:05 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.4 kristaps 17: .Dd $Mdocdate: May 17 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.
93: .Ss \&de1
94: The syntax of this macro is the same as that of
95: .Sx \&ig ,
96: except that a leading argument must be specified.
97: It is ignored, as are its children.
1.5 ! kristaps 98: .Ss \&el
! 99: The
! 100: .Qq else
! 101: half of an if/else conditional.
! 102: Pops a result off the stack of conditional evaluations pushed by
! 103: .Sx \&ie
! 104: and uses it as its conditional.
! 105: If no stack entries are present (e.g., due to no prior
! 106: .Sx \&ie
! 107: calls)
! 108: then false is assumed.
! 109: The syntax of this macro is similar to
! 110: .Sx \&if
! 111: except that the conditional is missing.
! 112: .Ss \&ie
! 113: The
! 114: .Qq if
! 115: half of an if/else conditional.
! 116: The result of the conditional is pushed into a stack used by subsequent
! 117: invocations of
! 118: .Sx \&el ,
! 119: which may be separated by any intervening input (or not exist at all).
! 120: Its syntax is equivalent to
! 121: .Sx \&if .
1.1 kristaps 122: .Ss \&if
1.3 kristaps 123: Begins a conditional that always evaluates to false.
124: If a conditional is false, its children are not processed, but are
125: syntactically interpreted to preserve the integrity of the input
126: document.
127: Thus,
128: .Pp
129: .D1 \&.if t \e .ig
130: .Pp
131: will discard the
132: .Sq \&.ig ,
133: which may lead to interesting results, but
134: .Pp
135: .D1 \&.if t \e .if t \e{\e
136: .Pp
137: will continue to syntactically interpret to the block close of the final
138: conditional.
139: Sub-conditionals, in this case, obviously inherit the truth value of
140: the parent.
141: This macro has the following syntax:
1.1 kristaps 142: .Pp
143: .Bd -literal -offset indent -compact
144: \&.if COND \e{\e
145: BODY...
146: \&.\e}
147: .Ed
148: .Bd -literal -offset indent -compact
149: \&.if COND \e{ BODY
1.2 kristaps 150: BODY... \e}
151: .Ed
152: .Bd -literal -offset indent -compact
153: \&.if COND \e{ BODY
1.1 kristaps 154: BODY...
155: \&.\e}
156: .Ed
157: .Bd -literal -offset indent -compact
158: \&.if COND \e
159: BODY
160: .Ed
161: .Pp
1.3 kristaps 162: COND is a conditional (for the time being, this always evaluates to
163: false).
1.1 kristaps 164: .Pp
165: If the BODY section is begun by an escaped brace
166: .Sq \e{ ,
167: scope continues until a closing-brace macro
168: .Sq \.\e} .
169: If the BODY is not enclosed in braces, scope continues until the next
170: macro or word.
171: If the COND is followed by a BODY on the same line, whether after a
172: brace or not, then macros
173: .Em must
174: begin with a control character.
175: It is generally more intuitive, in this case, to write
176: .Bd -literal -offset indent
177: \&.if COND \e{\e
178: \&.foo
179: bar
180: \&.\e}
181: .Ed
182: .Pp
183: than having the macro follow as
184: .Pp
185: .D1 \&.if COND \e{ .foo
186: .Pp
187: The scope of a conditional is always parsed, but only executed if the
188: conditional evaluates to true.
189: .Pp
190: Note that text subsequent a
1.2 kristaps 191: .Sq \&.\e}
192: macro is discarded.
193: Furthermore, if an explicit closing sequence
1.1 kristaps 194: .Sq \e}
1.2 kristaps 195: is specified in a free-form line, the entire line is accepted within the
196: scope of the prior macro, not only the text preceding the close.
1.1 kristaps 197: .Ss \&ig
1.2 kristaps 198: Ignore input.
199: Accepts the following syntax:
200: .Pp
201: .Bd -literal -offset indent -compact
202: \&.ig
203: BODY...
204: \&..
205: .Ed
206: .Bd -literal -offset indent -compact
207: \&.ig END
208: BODY...
209: \&.END
210: .Ed
211: .Pp
212: In the first case, input is ignored until a
213: .Sq \&..
1.1 kristaps 214: macro is encountered on its own line.
1.2 kristaps 215: In the second case, input is ignored until a
216: .Sq \&.END
217: is encountered.
218: Text subsequent the
219: .Sq \&.END
220: or
221: .Sq \&..
1.1 kristaps 222: is discarded.
1.2 kristaps 223: .Pp
224: Do not use the escape
225: .Sq \e
226: anywhere in the definition of END.
227: It causes very strange behaviour.
228: Furthermore, if you redefine a
229: .Nm
230: macro, such as
231: .Pp
232: .D1 \&.ig if
233: .Pp
234: the subsequent invocation of
235: .Sx \&if
236: will first signify the end of comment, then be invoked as a macro.
237: This behaviour really shouldn't be counted upon.
238: .Sh COMPATIBILITY
239: This section documents compatibility between mandoc and other other
240: troff implementations, at this time limited to GNU troff
241: .Pq Qq groff .
242: The term
243: .Qq historic groff
244: refers to groff versions before the
245: .Pa doc.tmac
246: file re-write
247: .Pq somewhere between 1.15 and 1.19 .
248: .Pp
249: .Bl -dash -compact
250: .It
251: Historic groff did not accept white-space buffering the custom END tag
252: for the
253: .Sx \&ig
254: macro.
1.4 kristaps 255: .It
256: The
257: .Sx \&if
258: and family would print funny white-spaces with historic groff when
259: depending on next-line syntax.
1.2 kristaps 260: .El
1.1 kristaps 261: .Sh AUTHORS
262: The
263: .Nm
264: reference was written by
265: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to roff.7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc