]> git.cameronkatri.com Git - mandoc.git/blob - roff.7
Fixed my breaking of Ingo's eoln-whitespace detection code, where a
[mandoc.git] / roff.7
1 .\" $Id: roff.7,v 1.7 2010/05/24 23:54:18 schwarze Exp $
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: May 24 2010 $
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 \&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 \&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.
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.
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 .
128 .Ss \&if
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.
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:
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
164 BODY... \e}
165 .Ed
166 .Bd -literal -offset indent -compact
167 \&.if COND \e{ BODY
168 BODY...
169 \&.\e}
170 .Ed
171 .Bd -literal -offset indent -compact
172 \&.if COND \e
173 BODY
174 .Ed
175 .Pp
176 COND is a conditional (for the time being, this always evaluates to
177 false).
178 .Pp
179 If the BODY section is begun by an escaped brace
180 .Sq \e{ ,
181 scope continues until a closing-brace macro
182 .Sq \.\e} .
183 If the BODY is not enclosed in braces, scope continues until the next
184 macro or word.
185 If the COND is followed by a BODY on the same line, whether after a
186 brace or not, then macros
187 .Em must
188 begin with a control character.
189 It is generally more intuitive, in this case, to write
190 .Bd -literal -offset indent
191 \&.if COND \e{\e
192 \&.foo
193 bar
194 \&.\e}
195 .Ed
196 .Pp
197 than having the macro follow as
198 .Pp
199 .D1 \&.if COND \e{ .foo
200 .Pp
201 The scope of a conditional is always parsed, but only executed if the
202 conditional evaluates to true.
203 .Pp
204 Note that text subsequent a
205 .Sq \&.\e}
206 macro is discarded.
207 Furthermore, if an explicit closing sequence
208 .Sq \e}
209 is specified in a free-form line, the entire line is accepted within the
210 scope of the prior macro, not only the text preceding the close.
211 .Ss \&ig
212 Ignore input.
213 Accepts the following syntax:
214 .Pp
215 .Bd -literal -offset indent -compact
216 \&.ig
217 BODY...
218 \&..
219 .Ed
220 .Bd -literal -offset indent -compact
221 \&.ig END
222 BODY...
223 \&.END
224 .Ed
225 .Pp
226 In the first case, input is ignored until a
227 .Sq \&..
228 macro is encountered on its own line.
229 In the second case, input is ignored until a
230 .Sq \&.END
231 is encountered.
232 Text subsequent the
233 .Sq \&.END
234 or
235 .Sq \&..
236 is discarded.
237 .Pp
238 Do not use the escape
239 .Sq \e
240 anywhere in the definition of END.
241 It causes very strange behaviour.
242 Furthermore, if you redefine a
243 .Nm
244 macro, such as
245 .Pp
246 .D1 \&.ig if
247 .Pp
248 the subsequent invocation of
249 .Sx \&if
250 will first signify the end of comment, then be invoked as a macro.
251 This behaviour really shouldn't be counted upon.
252 .Ss \&rm
253 Remove a request, macro or string.
254 This macro is intended to have one argument,
255 the name of the request, macro or string to be undefined.
256 Currently, it is ignored including its arguments,
257 and the number of arguments is not checked.
258 .Ss \&tr
259 Output character translation.
260 This macro is intended to have one argument,
261 consisting of an even number of characters.
262 Currently, it is ignored including its arguments,
263 and the number of arguments is not checked.
264 .Sh COMPATIBILITY
265 This section documents compatibility between mandoc and other other
266 troff implementations, at this time limited to GNU troff
267 .Pq Qq groff .
268 The term
269 .Qq historic groff
270 refers to groff versions before the
271 .Pa doc.tmac
272 file re-write
273 .Pq somewhere between 1.15 and 1.19 .
274 .Pp
275 .Bl -dash -compact
276 .It
277 Historic groff did not accept white-space buffering the custom END tag
278 for the
279 .Sx \&ig
280 macro.
281 .It
282 The
283 .Sx \&if
284 and family would print funny white-spaces with historic groff when
285 depending on next-line syntax.
286 .El
287 .Sh AUTHORS
288 The
289 .Nm
290 reference was written by
291 .An Kristaps Dzonsons Aq kristaps@bsd.lv .