1 .\" $Id: mdoc.7,v 1.41 2009/07/12 19:34:51 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 12 2009 $
23 .Nd mdoc language reference
28 language is used to format
31 manuals. In this reference document, we describe the syntax and
34 language. Our reference implementation is
38 section describes compatibility with
44 document follows simple rules: lines beginning with the control
47 are parsed for macros. Other lines are interpreted within the scope of
49 .Bd -literal -offset indent
50 \&.Sh Macro lines change control state.
51 Other lines are interpreted within the current state.
56 documents may contain only graphable 7-bit ASCII characters, the space
59 and, in certain circumstances, the tab character
65 The only time a blank line is acceptable is within
69 .Sq \&.Bd \-unfilled .
73 are only acceptable when delimiting
84 delimiter is considered a comment (unless the
86 itself has been escaped) and is ignored to the end of line.
87 Furthermore, a macro line with only a control character
89 optionally followed by whitespace, is ignored.
91 .Ss Reserved Characters
92 Within a macro line, the following characters are reserved:
93 .Bl -tag -width Ds -offset indent -compact
105 .Pq right-parenthesis
119 Use of reserved characters is described in
121 For general non-reserved use, characters must either be escaped with a
124 or, if applicable, an appropriate escape-sequence used.
126 .Ss Special Characters
127 Special character sequences begin with the escape character
129 followed by either an open-parenthesis
131 for two-character sequences; an open-bracket
133 for n-character sequences (terminated at a close-bracket
135 or a single one-character sequence.
137 Characters may alternatively be escaped by a slash-asterisk,
139 with the same combinations as described above.
141 Terms may also be text-decorated using the
143 escape followed by a text-decoration letter: B (bold), I, (italic), or P
144 and R (Roman, or reset). This form is not recommended.
147 Unless in literal mode or specifically escaped, consecutive blocks of
148 whitespace are pruned from input. These are later re-added, if
149 applicable, by a front-end utility such as
155 document must begin with the document prologue, containing, in order,
160 Following these, the document body must begin with the NAME section
161 containing at least one
167 At least one free-form or macro line must follow this prologue.
170 Macros are classified by their scope rules. Some macros are allowed to
171 deviate from their classifications to preserve backward-compatibility
172 with old macro combinations still found in the manual corpus. These are
173 specifically noted on a per-macro basis.
179 macros enclose other block macros, in-line macros or text, and
180 may span multiple lines.
181 .Bl -inset -offset indent
184 macros always span multiple lines. They consist of zero or
187 subsequent macros or text on the same line following invocation; an
190 which spans subsequent lines of text or macros; and an optional
192 macros or text on the same line following closure.
195 macros may span multiple lines. They consists of a optional
197 text immediately following invocation; always a
199 text or macros following the head on the same and subsequent lines; and
202 text immediately following closure.
205 macros may only enclose text and span at most a single line.
210 Closure of a macro's scope depends first on its classification, then
211 on whether it's parsable. In this table,
213 refers to block full-explicit and so on.
216 .Bl -tag -width 12n -offset indent -compact
218 corresponding explicit closure macro
220 end-of-file or a corresponding implicit closure macro
222 end-of-line (body may be closed by >0 space-separated
223 .Sx Reserved Characters ,
224 although block scope will still be open)
230 If a macro (block or in-line) is parsable, it may also be closed out by
231 one of the following scenarios (unless specifically noted otherwise):
234 .Bl -dash -offset indent -compact
236 a sequence of >0 space-separated
237 .Sx Reserved Characters ,
243 completion of a set number of arguments.
247 If >0 space-separated
248 .Sx Reserved Characters
249 are followed by non-reserved characters, the behaviour differs per
250 macro. In general, scope of the macro is closed and re-opened:
251 subsequent tokens are interpreted as if the scope had just been opened.
252 In other circumstances, scope is simply closed out.
255 Macros are two or three characters in length. The syntax of macro
256 invocation depends on its classification.
258 refers to the macro arguments (which may contain zero or more values).
259 In these illustrations,
261 opens the scope of a macro, and if specified,
263 closes it out (closure may be implicit at end-of-line or end-of-file).
266 Block full-explicit (may contain head, body, tail).
267 .Bd -literal -offset indent
268 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
270 \&.Yc \(lBtail...\(rB
274 Block full-implicit (may contain zero or more heads, body, no tail).
275 .Bd -literal -offset indent
276 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
282 Block partial-explicit (may contain head, multi-line body, tail).
283 .Bd -literal -offset indent
284 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
286 \&.Yc \(lBtail...\(rB
288 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
289 \(lBbody...\(rB \&Yc \(lBtail...\(rB
293 Block partial-implicit (no head, body, no tail). Note that the body
294 section may be followed by zero or more
296 These are in the block scope, but not in the body scope.
297 .Bd -literal -offset indent
298 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
302 In-lines have \(>=0 scoped arguments.
303 .Bd -literal -offset indent
304 \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
306 \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
310 This section contains a complete list of all
312 macros, arranged by classification. A
314 macro is invoked subsequent to the initial macro-line macro. A
316 macro may be followed by further (ostensibly callable) macros.
318 .Ss Block full-implicit
319 The head of these macros follows invocation; the body is the content of
320 subsequent lines prior to closure. None of these macros have tails;
331 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "Closing"
332 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
333 .It \&.Nd Ta \&No Ta \&No Ta \&.Sh
334 .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
335 .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
336 .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
339 .Ss Block full-explicit
340 None of these macros are callable or parsed. The last column indicates
341 the explicit scope rules. All contains bodies, some may contain heads
344 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
345 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
346 .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
347 .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
348 .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
349 .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
350 .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
351 .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
352 .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
353 .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
356 .Ss Block partial-implicit
357 All of these are callable and parsed for further macros. Their scopes
358 close at the invocation's end-of-line.
360 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
361 .It Em Macro Ta Em Callable Ta Em Parsable
362 .It \&.Aq Ta Yes Ta Yes
363 .It \&.Op Ta Yes Ta Yes
364 .It \&.Bq Ta Yes Ta Yes
365 .It \&.Dq Ta Yes Ta Yes
366 .It \&.Pq Ta Yes Ta Yes
367 .It \&.Qq Ta Yes Ta Yes
368 .It \&.Sq Ta Yes Ta Yes
369 .It \&.Brq Ta Yes Ta Yes
370 .It \&.D1 Ta \&No Ta \&Yes
371 .It \&.Dl Ta \&No Ta Yes
372 .It \&.Ql Ta Yes Ta Yes
380 as in the following example:
381 .Bd -literal -offset indent
386 In the above example, the scope of
388 is technically broken by
390 however, due to the overwhelming existence of this sequence, it's
393 .Ss Block partial-explicit
394 Each of these contains at least a body and, in limited circumstances, a
396 .Pq So \&.Fo Sc , So \&.Eo Sc
400 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
401 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
402 .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
403 .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
404 .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
405 .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
406 .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
407 .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
408 .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
409 .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
410 .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
411 .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
412 .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
413 .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
414 .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
415 .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
416 .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
417 .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
418 .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
419 .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
420 .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
421 .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
422 .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
423 .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
424 .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
425 .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
429 In-line macros have only text children. If a number (or inequality) of
432 then the macro accepts an arbitrary number of arguments.
434 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
435 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
436 .It \&.Dd Ta \&No Ta \&No Ta >0
437 .It \&.Dt Ta \&No Ta \&No Ta n
438 .It \&.Os Ta \&No Ta \&No Ta n
439 .It \&.Pp Ta \&No Ta \&No Ta 0
440 .It \&.Ad Ta Yes Ta Yes Ta n
441 .It \&.An Ta Yes Ta Yes Ta n
442 .It \&.Ar Ta Yes Ta Yes Ta n
443 .It \&.Cd Ta Yes Ta \&No Ta >0
444 .It \&.Cm Ta Yes Ta Yes Ta n
445 .It \&.Dv Ta Yes Ta Yes Ta n
446 .It \&.Er Ta Yes Ta Yes Ta >0
447 .It \&.Ev Ta Yes Ta Yes Ta n
448 .It \&.Ex Ta \&No Ta \&No Ta 0
449 .It \&.Fa Ta Yes Ta Yes Ta n
450 .It \&.Fd Ta \&No Ta \&No Ta >0
451 .It \&.Fl Ta Yes Ta Yes Ta n
452 .It \&.Fn Ta Yes Ta Yes Ta >0
453 .It \&.Ft Ta Yes Ta Yes Ta n
454 .It \&.Ic Ta Yes Ta Yes Ta >0
455 .It \&.In Ta \&No Ta \&No Ta n
456 .It \&.Li Ta Yes Ta Yes Ta n
457 .It \&.Nm Ta Yes Ta Yes Ta n
458 .It \&.Ot Ta \&No Ta \&No Ta n
459 .It \&.Pa Ta Yes Ta Yes Ta n
460 .It \&.Rv Ta \&No Ta \&No Ta 0
461 .It \&.St Ta \&No Ta Yes Ta 1
462 .It \&.Va Ta Yes Ta Yes Ta n
463 .It \&.Vt Ta Yes Ta Yes Ta >0
464 .It \&.Xr Ta Yes Ta Yes Ta >0, <3
465 .It \&.%A Ta \&No Ta \&No Ta >0
466 .It \&.%B Ta \&No Ta \&No Ta >0
467 .It \&.%C Ta \&No Ta \&No Ta >0
468 .It \&.%D Ta \&No Ta \&No Ta >0
469 .It \&.%I Ta \&No Ta \&No Ta >0
470 .It \&.%J Ta \&No Ta \&No Ta >0
471 .It \&.%N Ta \&No Ta \&No Ta >0
472 .It \&.%O Ta \&No Ta \&No Ta >0
473 .It \&.%P Ta \&No Ta \&No Ta >0
474 .It \&.%R Ta \&No Ta \&No Ta >0
475 .It \&.%T Ta \&No Ta \&No Ta >0
476 .It \&.%V Ta \&No Ta \&No Ta >0
477 .It \&.At Ta Yes Ta Yes Ta 1
478 .It \&.Bsx Ta Yes Ta Yes Ta n
479 .It \&.Bx Ta Yes Ta Yes Ta n
480 .It \&.Db Ta \&No Ta \&No Ta 1
481 .It \&.Em Ta Yes Ta Yes Ta >0
482 .It \&.Fx Ta Yes Ta Yes Ta n
483 .It \&.Ms Ta Yes Ta Yes Ta >0
484 .It \&.No Ta Yes Ta Yes Ta 0
485 .It \&.Ns Ta Yes Ta Yes Ta 0
486 .It \&.Nx Ta Yes Ta Yes Ta n
487 .It \&.Ox Ta Yes Ta Yes Ta n
488 .It \&.Pf Ta \&No Ta Yes Ta 1
489 .It \&.Sm Ta \&No Ta \&No Ta 1
490 .It \&.Sx Ta Yes Ta Yes Ta >0
491 .It \&.Sy Ta Yes Ta Yes Ta >0
492 .It \&.Tn Ta Yes Ta Yes Ta >0
493 .It \&.Ux Ta Yes Ta Yes Ta n
494 .It \&.Dx Ta Yes Ta Yes Ta n
495 .It \&.Bt Ta \&No Ta \&No Ta 0
496 .It \&.Hf Ta \&No Ta \&No Ta n
497 .It \&.Fr Ta \&No Ta \&No Ta n
498 .It \&.Ud Ta \&No Ta \&No Ta 0
499 .It \&.Lb Ta \&No Ta \&No Ta 1
500 .It \&.Ap Ta Yes Ta Yes Ta 0
501 .It \&.Lp Ta \&No Ta \&No Ta 0
502 .It \&.Lk Ta Yes Ta Yes Ta n
503 .It \&.Mt Ta Yes Ta Yes Ta >0
504 .It \&.Es Ta \&No Ta \&No Ta 0
505 .It \&.En Ta \&No Ta \&No Ta 0
517 This section documents compatibility with other roff implementations, at
522 refers to those versions before the
525 .Pq somewhere between 1.15 and 1.19 .
530 Some character sequences in groff are not handled depending on escape
535 may not be interchanged. This is no longer the case: all character
536 sequences resolve to the same symbol, regardless the escape style.
539 Blocks of whitespace are stripped from both macro and free-form text
540 lines (except when in literal mode), while groff would retain whitespace
541 in free-form text lines.
544 Historic groff has many un-callable macros. Most of these (excluding
545 some block-level macros) are now callable, conforming to the
546 non-historic groff version.
553 but is a proper delimiter in this implementation.
557 is assumed for all lists (it wasn't in historic groff): any list may be
560 lists will restart the sequence only for the sub-list.
564 syntax where column widths may be preceded by other arguments (instead
565 of proceeded) is not supported.
570 macro only accepts a single parameter.
575 incorrectly by following it with a reserved character and expecting the
576 delimiter to render. This is not supported.
579 If an special-character control character is escaped
581 it will obviously not render the subsequent sequence. Even newer
582 versions of groff seem to dither on this.
587 macro only produces the first parameter. This is no longer the case.
597 utility was written by
598 .An Kristaps Dzonsons Aq kristaps@kth.se .
601 There are many ambiguous parts of mdoc.
609 as function arguments are variables.
615 as function return types are still types. Furthermore, the
617 should be removed and
619 which ostensibly follows it, should follow the same convention as
624 should formalise that only one or two arguments are acceptable: a
625 variable name and optional, preceding type.
629 is ambiguous. It's commonly used to indicate an include file in the
632 should be used, instead.
639 makes sense. The remaining ones should be removed.
646 macros should be deprecated.
651 macro lacks clarity. It should be absolutely clear which title will
652 render when formatting the manual page.
657 should be provided for Linux (\(`a la
663 There's no way to refer to references in
668 The \-split and \-nosplit arguments to
673 The end-of-line whitespace warnings are superfluous holdovers from