1 .\" $Id: roff.7,v 1.14 2010/07/27 13:16:00 kristaps Exp $
3 .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 .Dd $Mdocdate: July 27 2010 $
23 .Nd roff language reference
27 language is a general-purpose text-formatting language. The purpose of
28 this document is to consistently describe those language constructs
31 utility. It is a work in progress.
35 document follows simple rules: lines beginning with the control
40 are parsed for macros. Other lines are interpreted within the scope of
42 .Bd -literal -offset indent
43 \&.xx Macro lines change control state.
44 Other lines are interpreted within the current state.
48 documents may contain only graphable 7-bit ASCII characters, the space
49 character, and, in certain circumstances, the tab character. All
54 Macros are arbitrary in length and begin with a control character ,
58 at the beginning of the line.
59 An arbitrary amount of whitespace may sit between the control character
61 Thus, the following are equivalent:
62 .Bd -literal -offset indent
67 This section is a canonical reference of all macros, arranged
70 The syntax of this macro is the same as that of
72 except that a leading argument must be specified.
73 It is ignored, as are its children.
75 The syntax of this macro is the same as that of
77 except that a leading argument must be specified.
78 It is ignored, as are its children.
80 The syntax of this macro is the same as that of
82 except that a leading argument must be specified.
83 It is ignored, as are its children.
85 The syntax of this macro is the same as that of
87 except that a leading argument must be specified.
88 It is ignored, as are its children.
90 The syntax of this macro is the same as that of
92 except that a leading argument must be specified.
93 It is ignored, as are its children.
95 Define a reserved word.
96 Its syntax is as follows:
98 .D1 Pf \. Sx \&ds No Cm key val
104 strings are space-separated.
107 values may be invoked in subsequent text by using \e*(NN for two-letter
108 pairs, \e*N for one-letter, and \e*[NNN] for arbitrary-length values.
112 is begun with a double-quote mark, the mark is passed over.
116 text following this point, including whitespace and trailing
119 The syntax of this macro is the same as that of
121 except that a leading argument must be specified.
122 It is ignored, as are its children.
126 half of an if/else conditional.
127 Pops a result off the stack of conditional evaluations pushed by
129 and uses it as its conditional.
130 If no stack entries are present (e.g., due to no prior
133 then false is assumed.
134 The syntax of this macro is similar to
136 except that the conditional is missing.
140 half of an if/else conditional.
141 The result of the conditional is pushed into a stack used by subsequent
144 which may be separated by any intervening input (or not exist at all).
145 Its syntax is equivalent to
148 Begins a conditional.
149 Right now, the conditional evaluates to true
150 if and only if it starts with the letter
152 indicating processing in
157 If a conditional is false, its children are not processed, but are
158 syntactically interpreted to preserve the integrity of the input
166 which may lead to interesting results, but
168 .D1 \&.if t \e .if t \e{\e
170 will continue to syntactically interpret to the block close of the final
172 Sub-conditionals, in this case, obviously inherit the truth value of
174 This macro has the following syntax:
176 .Bd -literal -offset indent -compact
181 .Bd -literal -offset indent -compact
185 .Bd -literal -offset indent -compact
190 .Bd -literal -offset indent -compact
195 COND is a conditional statement.
196 roff allows for complicated conditionals; mandoc is much simpler.
197 At this time, mandoc supports only
206 All other invocations are read up to the next end of line or space and
209 If the BODY section is begun by an escaped brace
211 scope continues until a closing-brace macro
213 If the BODY is not enclosed in braces, scope continues until the next
215 If the COND is followed by a BODY on the same line, whether after a
216 brace or not, then macros
218 begin with a control character.
219 It is generally more intuitive, in this case, to write
220 .Bd -literal -offset indent
227 than having the macro follow as
229 .D1 \&.if COND \e{ .foo
231 The scope of a conditional is always parsed, but only executed if the
232 conditional evaluates to true.
234 Note that text subsequent a
237 Furthermore, if an explicit closing sequence
239 is specified in a free-form line, the entire line is accepted within the
240 scope of the prior macro, not only the text preceding the close, with the
242 collapsing into a zero-width space.
245 Accepts the following syntax:
247 .Bd -literal -offset indent -compact
252 .Bd -literal -offset indent -compact
258 In the first case, input is ignored until a
260 macro is encountered on its own line.
261 In the second case, input is ignored until a
270 Do not use the escape
272 anywhere in the definition of END.
273 It causes very strange behaviour.
274 Furthermore, if you redefine a
280 the subsequent invocation of
282 will first signify the end of comment, then be invoked as a macro.
283 This behaviour really shouldn't be counted upon.
285 Remove a request, macro or string.
286 This macro is intended to have one argument,
287 the name of the request, macro or string to be undefined.
288 Currently, it is ignored including its arguments,
289 and the number of arguments is not checked.
292 A register is an arbitrary string value that defines some sort of state,
293 which influences parsing and/or formatting.
294 Its syntax is as follows:
296 .D1 Pf \. Sx \&nr Cm name value
300 may, at the moment, only be an integer.
303 is defined up to the next whitespace.
304 The following register
306 requests are recognised:
309 If set to a positive integer value, certain
311 macros will behave as if they were defined in the
314 Otherwise, this behaviour is unset (even if called within the
317 Note that invoking a new
319 section will unset this value.
322 Output character translation.
323 This macro is intended to have one argument,
324 consisting of an even number of characters.
325 Currently, it is ignored including its arguments,
326 and the number of arguments is not checked.
328 This section documents compatibility between mandoc and other other
329 troff implementations, at this time limited to GNU troff
333 refers to groff versions before the
336 .Pq somewhere between 1.15 and 1.19 .
344 is only compatible with OpenBSD's groff.
346 Historic groff did not accept white-space buffering the custom END tag
353 and family would print funny white-spaces with historic groff when
354 depending on next-line syntax.
359 reference was written by
360 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
git.ckatri.com / mandoc.git / blob