1 .\" $Id: mdoc.7,v 1.50 2009/07/20 13:45:11 kristaps Exp $
3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
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.
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.
17 .Dd $Mdocdate: July 20 2009 $
20 .\" SECTION---------------------------------------------
23 .Nd mdoc language reference
24 .\" SECTION---------------------------------------------
28 language is used to format
31 manuals. In this reference document, we describe its syntax, structure,
32 and usage. Our reference implementation is
36 section describes compatibility with
38 .\" PARAGRAPH------------
42 document follows simple rules: lines beginning with the control
45 are parsed for macros. Other lines are interpreted within the scope of
47 .Bd -literal -offset indent
48 \&.Sh Macro lines change control state.
49 Other lines are interpreted within the current state.
51 .\" SECTION---------------------------------------------
54 documents may contain only graphable 7-bit ASCII characters, the space
55 character, and, in certain circumstances, the tab character. All
59 .\" SUB-SECTION----------------------
63 whether in a macro or free-form text line, is ignored to the end of
64 line. A macro line with only a control character and comment escape,
67 .\" SUB-SECTION----------------------
68 .Ss Reserved Characters
69 Within a macro line, the following characters are reserved:
70 .Bl -tag -width Ds -offset indent -compact
94 .\" PARAGRAPH------------
96 Use of reserved characters is described in
98 For general use in macro lines, these characters must either be escaped
99 with a non-breaking space
101 or, if applicable, an appropriate escape sequence used.
102 .\" SUB-SECTION----------------------
103 .Ss Special Characters
104 Special characters may occur in both macro and free-form lines.
105 Sequences begin with the escape character
107 followed by either an open-parenthesis
109 for two-character sequences; an open-bracket
111 for n-character sequences (terminated at a close-bracket
113 or a single one-character sequence. See
115 for a complete list. Examples include
121 .\" PARAGRAPH------------
123 An alternative escape sequence is
126 but this method is discouraged for compatibility reasons.
127 .\" PARAGRAPH------------
130 also be text-decorated using the
132 escape followed by an indicator: B (bold), I, (italic), or P and R
133 (Roman, or reset). This form is not recommended.
134 .\" SUB-SECTION----------------------
136 In non-literal free-form lines, consecutive blocks of whitespace are
137 pruned from input and added later in the output filter, if applicable:
138 .Bd -literal -offset indent
139 These spaces are pruned from input.
144 .\" PARAGRAPH------------
146 In macro lines, whitespace delimits arguments and is discarded. If
147 arguments are quoted, whitespace within the quotes is retained.
148 .\" PARAGRAPH------------
150 Blank lines are only permitted within literal contexts, as are lines
151 containing only whitespace. Tab characters are only acceptable when
154 or when in a literal context.
155 .\" SUB-SECTION----------------------
157 Macro arguments may be quoted with a double-quote to group
158 space-delimited terms or to retain blocks of whitespace. A quoted
159 argument begins with a double-quote preceded by whitespace. The next
160 double-quote not pair-wise adjacent to another double-quote terminates
161 the literal, regardless of surrounding whitespace.
162 .\" PARAGRAPH------------
170 Note that any quoted term, be it argument or macro, is indiscriminately
171 considered literal text. Thus, the following produces
173 .Bd -literal -offset indent
176 .\" PARAGRAPH------------
178 In free-form mode, quotes are regarded as opaque text.
179 .\" SECTION---------------------------------------------
183 document must begin with a document prologue, containing, in order,
188 then the NAME section containing at least one
192 .Bd -literal -offset indent
198 \&.Nd mdoc language reference
200 .\" PARAGRAPH------------
202 Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
204 .\" SECTION---------------------------------------------
206 Every line beginning with the control character
208 is processed for macros, two- or three-character sequences.
209 .\" PARAGRAPH------------
211 The syntax of a macro depends on its classification. In this section,
213 refers to macro arguments, which may be followed by zero or more
217 opens the scope of a macro; and if specified,
220 .\" PARAGRAPH------------
224 column indicates that the macro may be called subsequent to the initial
227 column indicates whether the macro may be followed by further
228 (ostensibly callable) macros. The
230 column, if applicable, describes closure rules.
231 .\" SUB-SECTION----------------------
232 .Ss Block full-explicit
233 Multi-line scope closed by an explicit closing macro. All macros
234 contains bodies; only
237 .Bd -literal -offset indent
238 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
242 .\" PARAGRAPH------------
244 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
245 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
246 .It \&Bd Ta \&No Ta \&No Ta closed by \&Ed
247 .It \&Bf Ta \&No Ta \&No Ta closed by \&Ef
248 .It \&Bk Ta \&No Ta \&No Ta closed by \&Ek
249 .It \&Bl Ta \&No Ta \&No Ta closed by \&El
250 .It \&Ed Ta \&No Ta \&No Ta opened by \&Bd
251 .It \&Ef Ta \&No Ta \&No Ta opened by \&Bf
252 .It \&Ek Ta \&No Ta \&No Ta opened by \&Bk
253 .It \&El Ta \&No Ta \&No Ta opened by \&Bl
255 .\" SUB-SECTION----------------------
256 .Ss Block full-implicit
257 Multi-line scope closed by end-of-file or implicitly by another macro.
258 All macros have bodies; some
266 don't have heads, while
268 may have multiple heads.
269 .Bd -literal -offset indent
270 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
273 .\" PARAGRAPH------------
275 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
276 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
277 .It \&It Ta \&No Ta Yes Ta closed by \&It, \&El
278 .It \&Nd Ta \&No Ta \&No Ta closed by \&Sh
279 .It \&Sh Ta \&No Ta \&No Ta closed by \&Sh
280 .It \&Ss Ta \&No Ta \&No Ta closed by \&Sh, \&Ss
282 .\" SUB-SECTION----------------------
283 .Ss Block partial-explicit
284 Like block full-explicit, but also with single-line scope. Each
285 has at least a body and, in limited circumstances, a head
286 .Pq So \&Fo Sc , So \&Eo Sc
289 .Bd -literal -offset indent
290 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
292 \&.Yc \(lBtail...\(rB
294 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
295 \(lBbody...\(rB \&Yc \(lBtail...\(rB
297 .\" PARAGRAPH------------
299 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
300 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
301 .It \&Ac Ta Yes Ta Yes Ta opened by \&Ao
302 .It \&Ao Ta Yes Ta Yes Ta closed by \&Ac
303 .It \&Bc Ta Yes Ta Yes Ta closed by \&Bo
304 .It \&Bo Ta Yes Ta Yes Ta opened by \&Bc
305 .It \&Brc Ta Yes Ta Yes Ta opened by \&Bro
306 .It \&Bro Ta Yes Ta Yes Ta closed by \&Brc
307 .It \&Dc Ta Yes Ta Yes Ta opened by \&Do
308 .It \&Do Ta Yes Ta Yes Ta closed by \&Dc
309 .It \&Ec Ta Yes Ta Yes Ta opened by \&Eo
310 .It \&Eo Ta Yes Ta Yes Ta closed by \&Ec
311 .It \&Fc Ta Yes Ta Yes Ta opened by \&Fo
312 .It \&Fo Ta \&No Ta \&No Ta closed by \&Fc
313 .It \&Oc Ta Yes Ta Yes Ta closed by \&Oo
314 .It \&Oo Ta Yes Ta Yes Ta opened by \&Oc
315 .It \&Pc Ta Yes Ta Yes Ta closed by \&Po
316 .It \&Po Ta Yes Ta Yes Ta opened by \&Pc
317 .It \&Qc Ta Yes Ta Yes Ta opened by \&Oo
318 .It \&Qo Ta Yes Ta Yes Ta closed by \&Oc
319 .It \&Re Ta \&No Ta \&No Ta opened by \&Rs
320 .It \&Rs Ta \&No Ta \&No Ta closed by \&Re
321 .It \&Sc Ta Yes Ta Yes Ta opened by \&So
322 .It \&So Ta Yes Ta Yes Ta closed by \&Sc
323 .It \&Xc Ta Yes Ta Yes Ta opened by \&Xo
324 .It \&Xo Ta Yes Ta Yes Ta closed by \&Xc
326 .\" SUB-SECTION----------------------
327 .Ss Block partial-implicit
328 Like block full-implicit, but with single-line scope closed by
329 .Sx Reserved Characters
331 .Bd -literal -offset indent
332 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
334 .\" PARAGRAPH------------
336 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
337 .It Em Macro Ta Em Callable Ta Em Parsable
338 .It \&Aq Ta Yes Ta Yes
339 .It \&Bq Ta Yes Ta Yes
340 .It \&Brq Ta Yes Ta Yes
341 .It \&D1 Ta \&No Ta \&Yes
342 .It \&Dl Ta \&No Ta Yes
343 .It \&Dq Ta Yes Ta Yes
344 .It \&Op Ta Yes Ta Yes
345 .It \&Pq Ta Yes Ta Yes
346 .It \&Ql Ta Yes Ta Yes
347 .It \&Qq Ta Yes Ta Yes
348 .It \&Sq Ta Yes Ta Yes
350 .\" SUB-SECTION----------------------
353 .Sx Reserved Characters ,
354 end of line, fixed argument lengths, and/or subsequent macros. In-line
355 macros have only text children. If a number (or inequality) of
358 then the macro accepts an arbitrary number of arguments.
359 .Bd -literal -offset indent
360 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
362 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
364 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
366 .\" PARAGRAPH------------
368 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
369 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
370 .It \&%A Ta \&No Ta \&No Ta >0
371 .It \&%B Ta \&No Ta \&No Ta >0
372 .It \&%C Ta \&No Ta \&No Ta >0
373 .It \&%D Ta \&No Ta \&No Ta >0
374 .It \&%I Ta \&No Ta \&No Ta >0
375 .It \&%J Ta \&No Ta \&No Ta >0
376 .It \&%N Ta \&No Ta \&No Ta >0
377 .It \&%O Ta \&No Ta \&No Ta >0
378 .It \&%P Ta \&No Ta \&No Ta >0
379 .It \&%R Ta \&No Ta \&No Ta >0
380 .It \&%T Ta \&No Ta \&No Ta >0
381 .It \&%V Ta \&No Ta \&No Ta >0
382 .It \&Ad Ta Yes Ta Yes Ta n
383 .It \&An Ta Yes Ta Yes Ta n
384 .It \&Ap Ta Yes Ta Yes Ta 0
385 .It \&Ar Ta Yes Ta Yes Ta n
386 .It \&At Ta Yes Ta Yes Ta 1
387 .It \&Bsx Ta Yes Ta Yes Ta n
388 .It \&Bt Ta \&No Ta \&No Ta 0
389 .It \&Bx Ta Yes Ta Yes Ta n
390 .It \&Cd Ta Yes Ta Yes Ta >0
391 .It \&Cm Ta Yes Ta Yes Ta n
392 .It \&Db Ta \&No Ta \&No Ta 1
393 .It \&Dd Ta \&No Ta \&No Ta >0
394 .It \&Dt Ta \&No Ta \&No Ta n
395 .It \&Dv Ta Yes Ta Yes Ta n
396 .It \&Dx Ta Yes Ta Yes Ta n
397 .It \&Em Ta Yes Ta Yes Ta >0
398 .It \&En Ta \&No Ta \&No Ta 0
399 .It \&Er Ta Yes Ta Yes Ta >0
400 .It \&Es Ta \&No Ta \&No Ta 0
401 .It \&Ev Ta Yes Ta Yes Ta n
402 .It \&Ex Ta \&No Ta \&No Ta 0
403 .It \&Fa Ta Yes Ta Yes Ta n
404 .It \&Fd Ta \&No Ta \&No Ta >0
405 .It \&Fl Ta Yes Ta Yes Ta n
406 .It \&Fn Ta Yes Ta Yes Ta >0
407 .It \&Fr Ta \&No Ta \&No Ta n
408 .It \&Ft Ta Yes Ta Yes Ta n
409 .It \&Fx Ta Yes Ta Yes Ta n
410 .It \&Hf Ta \&No Ta \&No Ta n
411 .It \&Ic Ta Yes Ta Yes Ta >0
412 .It \&In Ta \&No Ta \&No Ta n
413 .It \&Lb Ta \&No Ta \&No Ta 1
414 .It \&Li Ta Yes Ta Yes Ta n
415 .It \&Lk Ta Yes Ta Yes Ta n
416 .It \&Lp Ta \&No Ta \&No Ta 0
417 .It \&Ms Ta Yes Ta Yes Ta >0
418 .It \&Mt Ta Yes Ta Yes Ta >0
419 .It \&Nm Ta Yes Ta Yes Ta n
420 .It \&No Ta Yes Ta Yes Ta 0
421 .It \&Ns Ta Yes Ta Yes Ta 0
422 .It \&Nx Ta Yes Ta Yes Ta n
423 .It \&Os Ta \&No Ta \&No Ta n
424 .It \&Ot Ta \&No Ta \&No Ta n
425 .It \&Ox Ta Yes Ta Yes Ta n
426 .It \&Pa Ta Yes Ta Yes Ta n
427 .It \&Pf Ta \&No Ta Yes Ta 1
428 .It \&Pp Ta \&No Ta \&No Ta 0
429 .It \&Rv Ta \&No Ta \&No Ta 0
430 .It \&Sm Ta \&No Ta \&No Ta 1
431 .It \&St Ta \&No Ta Yes Ta 1
432 .It \&Sx Ta Yes Ta Yes Ta >0
433 .It \&Sy Ta Yes Ta Yes Ta >0
434 .It \&Tn Ta Yes Ta Yes Ta >0
435 .It \&Ud Ta \&No Ta \&No Ta 0
436 .It \&Ux Ta Yes Ta Yes Ta n
437 .It \&Va Ta Yes Ta Yes Ta n
438 .It \&Vt Ta Yes Ta Yes Ta >0
439 .It \&Xr Ta Yes Ta Yes Ta >0, <3
440 .It \&br Ta \&No Ta \&No Ta 0
441 .It \&sp Ta \&No Ta \&No Ta 1
443 .\" SECTION---------------------------------------------
445 This section documents compatibility with other roff implementations, at
450 refers to those versions before the
453 .Pq somewhere between 1.15 and 1.19 .
454 .\" PARAGRAPH------------
459 In quoted literals, groff allowed pair-wise double-quotes to produce a
460 standalone double-quote in formatted output. This idiosyncratic
461 behaviour is no longer applicable.
466 macro does not accept negative numbers.
469 Some character sequences in groff are not handled depending on escape
474 may not be interchanged. This is no longer the case: all character
475 sequences resolve to the same symbol, regardless the escape style.
478 Blocks of whitespace are stripped from both macro and free-form text
479 lines (except when in literal mode), while groff would retain whitespace
480 in free-form text lines.
483 Historic groff has many un-callable macros. Most of these (excluding
484 some block-level macros) are now callable, conforming to the
485 non-historic groff version.
492 but is a proper delimiter in this implementation.
496 is assumed for all lists (it wasn't in historic groff): any list may be
499 lists will restart the sequence only for the sub-list.
503 syntax where column widths may be preceded by other arguments (instead
504 of proceeded) is not supported.
509 macro only accepts a single parameter.
514 incorrectly by following it with a reserved character and expecting the
515 delimiter to render. This is not supported.
518 If an special-character control character is escaped
520 it will obviously not render the subsequent sequence. Even newer
521 versions of groff seem to dither on this.
526 macro only produces the first parameter. This is no longer the case.
528 .\" SECTION---------------------------------------------
532 .\" SECTION---------------------------------------------
536 reference was written by
537 .An Kristaps Dzonsons Aq kristaps@kth.se .
538 .\" SECTION---------------------------------------------
540 There are many ambiguous parts of mdoc.
541 .\" PARAGRAPH------------
549 as function arguments are variables.
555 as function return types are still types. Furthermore, the
557 should be removed and
559 which ostensibly follows it, should follow the same convention as
564 should formalise that only one or two arguments are acceptable: a
565 variable name and optional, preceding type.
569 is ambiguous. It's commonly used to indicate an include file in the
572 should be used, instead.
579 makes sense. The remaining ones should be removed.
586 macros should be deprecated.
591 macro lacks clarity. It should be absolutely clear which title will
592 render when formatting the manual page.
597 should be provided for Linux (\(`a la
603 There's no way to refer to references in
608 The \-split and \-nosplit arguments to