1 .\" $Id: roff.7,v 1.13 2010/07/07 15:04:54 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 7 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.
110 The syntax of this macro is the same as that of
112 except that a leading argument must be specified.
113 It is ignored, as are its children.
117 half of an if/else conditional.
118 Pops a result off the stack of conditional evaluations pushed by
120 and uses it as its conditional.
121 If no stack entries are present (e.g., due to no prior
124 then false is assumed.
125 The syntax of this macro is similar to
127 except that the conditional is missing.
131 half of an if/else conditional.
132 The result of the conditional is pushed into a stack used by subsequent
135 which may be separated by any intervening input (or not exist at all).
136 Its syntax is equivalent to
139 Begins a conditional.
140 Right now, the conditional evaluates to true
141 if and only if it starts with the letter
143 indicating processing in
148 If a conditional is false, its children are not processed, but are
149 syntactically interpreted to preserve the integrity of the input
157 which may lead to interesting results, but
159 .D1 \&.if t \e .if t \e{\e
161 will continue to syntactically interpret to the block close of the final
163 Sub-conditionals, in this case, obviously inherit the truth value of
165 This macro has the following syntax:
167 .Bd -literal -offset indent -compact
172 .Bd -literal -offset indent -compact
176 .Bd -literal -offset indent -compact
181 .Bd -literal -offset indent -compact
186 COND is a conditional statement.
187 roff allows for complicated conditionals; mandoc is much simpler.
188 At this time, mandoc supports only
197 All other invocations are read up to the next end of line or space and
200 If the BODY section is begun by an escaped brace
202 scope continues until a closing-brace macro
204 If the BODY is not enclosed in braces, scope continues until the next
206 If the COND is followed by a BODY on the same line, whether after a
207 brace or not, then macros
209 begin with a control character.
210 It is generally more intuitive, in this case, to write
211 .Bd -literal -offset indent
218 than having the macro follow as
220 .D1 \&.if COND \e{ .foo
222 The scope of a conditional is always parsed, but only executed if the
223 conditional evaluates to true.
225 Note that text subsequent a
228 Furthermore, if an explicit closing sequence
230 is specified in a free-form line, the entire line is accepted within the
231 scope of the prior macro, not only the text preceding the close, with the
233 collapsing into a zero-width space.
236 Accepts the following syntax:
238 .Bd -literal -offset indent -compact
243 .Bd -literal -offset indent -compact
249 In the first case, input is ignored until a
251 macro is encountered on its own line.
252 In the second case, input is ignored until a
261 Do not use the escape
263 anywhere in the definition of END.
264 It causes very strange behaviour.
265 Furthermore, if you redefine a
271 the subsequent invocation of
273 will first signify the end of comment, then be invoked as a macro.
274 This behaviour really shouldn't be counted upon.
276 Remove a request, macro or string.
277 This macro is intended to have one argument,
278 the name of the request, macro or string to be undefined.
279 Currently, it is ignored including its arguments,
280 and the number of arguments is not checked.
283 A register is an arbitrary string value that defines some sort of state,
284 which influences parsing and/or formatting.
285 Its syntax is as follows:
287 .D1 Pf \. Sx \&nr Cm name value
291 may, at the moment, only be an integer.
294 is defined up to the next whitespace.
295 The following register
297 requests are recognised:
300 If set to a positive integer value, certain
302 macros will behave as if they were defined in the
305 Otherwise, this behaviour is unset (even if called within the
308 Note that invoking a new
310 section will unset this value.
313 Output character translation.
314 This macro is intended to have one argument,
315 consisting of an even number of characters.
316 Currently, it is ignored including its arguments,
317 and the number of arguments is not checked.
319 This section documents compatibility between mandoc and other other
320 troff implementations, at this time limited to GNU troff
324 refers to groff versions before the
327 .Pq somewhere between 1.15 and 1.19 .
335 is only compatible with OpenBSD's groff.
337 Historic groff did not accept white-space buffering the custom END tag
344 and family would print funny white-spaces with historic groff when
345 depending on next-line syntax.
350 reference was written by
351 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
git.ckatri.com / mandoc.git / blob