1 .\" $Id: mdoc.7,v 1.59 2009/08/20 13:32:09 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: August 20 2009 $
24 .Nd mdoc language reference
30 language is used to format
33 manuals. In this reference document, we describe its syntax, structure,
34 and usage. 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.
57 documents may contain only graphable 7-bit ASCII characters, the space
58 character, and, in certain circumstances, the tab character. All
67 whether in a macro or free-form text line, is ignored to the end of
68 line. A macro line with only a control character and comment escape,
70 is also ignored. Macro lines with only a control charater and optionally
71 whitespace are stripped from input.
74 .Ss Reserved Characters
75 Within a macro line, the following characters are reserved:
76 .Bl -tag -width Ds -offset indent -compact
102 Use of reserved characters is described in
104 For general use in macro lines, these characters must either be escaped
105 with a non-breaking space
107 or, if applicable, an appropriate escape sequence used.
110 .Ss Special Characters
111 Special characters may occur in both macro and free-form lines.
112 Sequences begin with the escape character
114 followed by either an open-parenthesis
116 for two-character sequences; an open-bracket
118 for n-character sequences (terminated at a close-bracket
120 or a single one-character sequence. See
122 for a complete list. Examples include
131 Terms may be text-decorated using the
133 escape followed by an indicator: B (bold), I, (italic), or P and R
134 (Roman, or reset). This form is not recommended for
136 which encourages semantic, not presentation, annotation.
139 .Ss Predefined Strings
142 also defined a set of package-specific
143 .Dq predefined strings ,
145 .Sx Special Characters ,
146 demark special output characters and strings by way of input codes.
147 Predefined strings are escaped with the slash-asterisk,
157 for a complete list. Examples include
166 In non-literal free-form lines, consecutive blocks of whitespace are
167 pruned from input and added later in the output filter, if applicable:
168 .Bd -literal -offset indent
169 These spaces are pruned from input.
176 In macro lines, whitespace delimits arguments and is discarded. If
177 arguments are quoted, whitespace within the quotes is retained.
180 Blank lines are only permitted within literal contexts, as are lines
181 containing only whitespace. Tab characters are only acceptable when
184 or when in a literal context.
188 Macro arguments may be quoted with a double-quote to group
189 space-delimited terms or to retain blocks of whitespace. A quoted
190 argument begins with a double-quote preceded by whitespace. The next
191 double-quote not pair-wise adjacent to another double-quote terminates
192 the literal, regardless of surrounding whitespace.
201 Note that any quoted term, be it argument or macro, is indiscriminately
202 considered literal text. Thus, the following produces
204 .Bd -literal -offset indent
209 In free-form mode, quotes are regarded as opaque text.
215 document must begin with a document prologue, containing, in order,
220 then the NAME section containing at least one
224 .Bd -literal -offset indent
231 \&.Nd a description goes here
232 \&.\e\*q The next is for sections 2 & 3 only.
243 utility processes files ...
244 \&.\e\*q .Sh IMPLEMENTATION NOTES
245 \&.\e\*q The next is for sections 1 & 8 only.
246 \&.\e\*q .Sh EXIT STATUS
247 \&.\e\*q The next is for sections 2, 3, & 9 only.
248 \&.\e\*q .Sh RETURN VALUES
249 \&.\e\*q The next is for sections 1, 6, 7, & 8 only.
250 \&.\e\*q .Sh ENVIRONMENT
252 \&.\e\*q .Sh EXAMPLES
253 \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
254 \&.\e\*q .Sh DIAGNOSTICS
255 \&.\e\*q The next is for sections 2, 3, & 9 only.
257 \&.\e\*q .Sh SEE ALSO
258 \&.\e\*q .Xr foobar 1
259 \&.\e\*q .Sh STANDARDS
264 \&.\e\*q .Sh SECURITY CONSIDERATIONS
268 Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,
273 Macros are one to three three characters in length and begin with a
276 at the beginning of the line. An arbitrary amount of whitespace may
277 sit between the control character and the macro name. Thus,
281 are equivalent. Macro names are two or three characters in length.
284 The syntax of a macro depends on its classification. In this section,
286 refers to macro arguments, which may be followed by zero or more
290 opens the scope of a macro; and if specified,
297 column indicates that the macro may be called subsequent to the initial
298 line-macro. If a macro is not callable, then its invocation after the
299 initial line macro is interpreted as opaque text, such that
307 column indicates whether the macro may be followed by further
308 (ostensibly callable) macros. If a macro is not parsable, subsequent
309 macro invocations on the line will be interpreted as opaque text.
314 column, if applicable, describes closure rules.
317 .Ss Block full-explicit
318 Multi-line scope closed by an explicit closing macro. All macros
319 contains bodies; only
322 .Bd -literal -offset indent
323 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
329 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
330 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
331 .It \&Bd Ta \&No Ta \&No Ta closed by \&Ed
332 .It \&Bf Ta \&No Ta \&No Ta closed by \&Ef
333 .It \&Bk Ta \&No Ta \&No Ta closed by \&Ek
334 .It \&Bl Ta \&No Ta \&No Ta closed by \&El
335 .It \&Ed Ta \&No Ta \&No Ta opened by \&Bd
336 .It \&Ef Ta \&No Ta \&No Ta opened by \&Bf
337 .It \&Ek Ta \&No Ta \&No Ta opened by \&Bk
338 .It \&El Ta \&No Ta \&No Ta opened by \&Bl
342 .Ss Block full-implicit
343 Multi-line scope closed by end-of-file or implicitly by another macro.
344 All macros have bodies; some
352 don't have heads, while
354 may have multiple heads.
355 .Bd -literal -offset indent
356 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
361 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
362 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
363 .It \&It Ta \&No Ta Yes Ta closed by \&It, \&El
364 .It \&Nd Ta \&No Ta \&No Ta closed by \&Sh
365 .It \&Sh Ta \&No Ta \&No Ta closed by \&Sh
366 .It \&Ss Ta \&No Ta \&No Ta closed by \&Sh, \&Ss
370 .Ss Block partial-explicit
371 Like block full-explicit, but also with single-line scope. Each
372 has at least a body and, in limited circumstances, a head
373 .Pq So \&Fo Sc , So \&Eo Sc
376 .Bd -literal -offset indent
377 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
379 \&.Yc \(lBtail...\(rB
381 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
382 \(lBbody...\(rB \&Yc \(lBtail...\(rB
386 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
387 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
388 .It \&Ac Ta Yes Ta Yes Ta opened by \&Ao
389 .It \&Ao Ta Yes Ta Yes Ta closed by \&Ac
390 .It \&Bc Ta Yes Ta Yes Ta closed by \&Bo
391 .It \&Bo Ta Yes Ta Yes Ta opened by \&Bc
392 .It \&Brc Ta Yes Ta Yes Ta opened by \&Bro
393 .It \&Bro Ta Yes Ta Yes Ta closed by \&Brc
394 .It \&Dc Ta Yes Ta Yes Ta opened by \&Do
395 .It \&Do Ta Yes Ta Yes Ta closed by \&Dc
396 .It \&Ec Ta Yes Ta Yes Ta opened by \&Eo
397 .It \&Eo Ta Yes Ta Yes Ta closed by \&Ec
398 .It \&Fc Ta Yes Ta Yes Ta opened by \&Fo
399 .It \&Fo Ta \&No Ta \&No Ta closed by \&Fc
400 .It \&Oc Ta Yes Ta Yes Ta closed by \&Oo
401 .It \&Oo Ta Yes Ta Yes Ta opened by \&Oc
402 .It \&Pc Ta Yes Ta Yes Ta closed by \&Po
403 .It \&Po Ta Yes Ta Yes Ta opened by \&Pc
404 .It \&Qc Ta Yes Ta Yes Ta opened by \&Oo
405 .It \&Qo Ta Yes Ta Yes Ta closed by \&Oc
406 .It \&Re Ta \&No Ta \&No Ta opened by \&Rs
407 .It \&Rs Ta \&No Ta \&No Ta closed by \&Re
408 .It \&Sc Ta Yes Ta Yes Ta opened by \&So
409 .It \&So Ta Yes Ta Yes Ta closed by \&Sc
410 .It \&Xc Ta Yes Ta Yes Ta opened by \&Xo
411 .It \&Xo Ta Yes Ta Yes Ta closed by \&Xc
415 .Ss Block partial-implicit
416 Like block full-implicit, but with single-line scope closed by
417 .Sx Reserved Characters
419 .Bd -literal -offset indent
420 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
424 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
425 .It Em Macro Ta Em Callable Ta Em Parsable
426 .It \&Aq Ta Yes Ta Yes
427 .It \&Bq Ta Yes Ta Yes
428 .It \&Brq Ta Yes Ta Yes
429 .It \&D1 Ta \&No Ta \&Yes
430 .It \&Dl Ta \&No Ta Yes
431 .It \&Dq Ta Yes Ta Yes
432 .It \&Op Ta Yes Ta Yes
433 .It \&Pq Ta Yes Ta Yes
434 .It \&Ql Ta Yes Ta Yes
435 .It \&Qq Ta Yes Ta Yes
436 .It \&Sq Ta Yes Ta Yes
442 .Sx Reserved Characters ,
443 end of line, fixed argument lengths, and/or subsequent macros. In-line
444 macros have only text children. If a number (or inequality) of
447 then the macro accepts an arbitrary number of arguments.
448 .Bd -literal -offset indent
449 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
451 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
453 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
457 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
458 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
459 .It \&%A Ta \&No Ta \&No Ta >0
460 .It \&%B Ta \&No Ta \&No Ta >0
461 .It \&%C Ta \&No Ta \&No Ta >0
462 .It \&%D Ta \&No Ta \&No Ta >0
463 .It \&%I Ta \&No Ta \&No Ta >0
464 .It \&%J Ta \&No Ta \&No Ta >0
465 .It \&%N Ta \&No Ta \&No Ta >0
466 .It \&%O Ta \&No Ta \&No Ta >0
467 .It \&%P Ta \&No Ta \&No Ta >0
468 .It \&%R Ta \&No Ta \&No Ta >0
469 .It \&%T Ta \&No Ta \&No Ta >0
470 .It \&%V Ta \&No Ta \&No Ta >0
471 .It \&Ad Ta Yes Ta Yes Ta n
472 .It \&An Ta Yes Ta Yes Ta n
473 .It \&Ap Ta Yes Ta Yes Ta 0
474 .It \&Ar Ta Yes Ta Yes Ta n
475 .It \&At Ta Yes Ta Yes Ta 1
476 .It \&Bsx Ta Yes Ta Yes Ta n
477 .It \&Bt Ta \&No Ta \&No Ta 0
478 .It \&Bx Ta Yes Ta Yes Ta n
479 .It \&Cd Ta Yes Ta Yes Ta >0
480 .It \&Cm Ta Yes Ta Yes Ta n
481 .It \&Db Ta \&No Ta \&No Ta 1
482 .It \&Dd Ta \&No Ta \&No Ta >0
483 .It \&Dt Ta \&No Ta \&No Ta n
484 .It \&Dv Ta Yes Ta Yes Ta n
485 .It \&Dx Ta Yes Ta Yes Ta n
486 .It \&Em Ta Yes Ta Yes Ta >0
487 .It \&En Ta \&No Ta \&No Ta 0
488 .It \&Er Ta Yes Ta Yes Ta >0
489 .It \&Es Ta \&No Ta \&No Ta 0
490 .It \&Ev Ta Yes Ta Yes Ta n
491 .It \&Ex Ta \&No Ta \&No Ta n
492 .It \&Fa Ta Yes Ta Yes Ta n
493 .It \&Fd Ta \&No Ta \&No Ta >0
494 .It \&Fl Ta Yes Ta Yes Ta n
495 .It \&Fn Ta Yes Ta Yes Ta >0
496 .It \&Fr Ta \&No Ta \&No Ta n
497 .It \&Ft Ta Yes Ta Yes Ta n
498 .It \&Fx Ta Yes Ta Yes Ta n
499 .It \&Hf Ta \&No Ta \&No Ta n
500 .It \&Ic Ta Yes Ta Yes Ta >0
501 .It \&In Ta \&No Ta \&No Ta n
502 .It \&Lb Ta \&No Ta \&No Ta 1
503 .It \&Li Ta Yes Ta Yes Ta n
504 .It \&Lk Ta Yes Ta Yes Ta n
505 .It \&Lp Ta \&No Ta \&No Ta 0
506 .It \&Ms Ta Yes Ta Yes Ta >0
507 .It \&Mt Ta Yes Ta Yes Ta >0
508 .It \&Nm Ta Yes Ta Yes Ta n
509 .It \&No Ta Yes Ta Yes Ta 0
510 .It \&Ns Ta Yes Ta Yes Ta 0
511 .It \&Nx Ta Yes Ta Yes Ta n
512 .It \&Os Ta \&No Ta \&No Ta n
513 .It \&Ot Ta \&No Ta \&No Ta n
514 .It \&Ox Ta Yes Ta Yes Ta n
515 .It \&Pa Ta Yes Ta Yes Ta n
516 .It \&Pf Ta \&No Ta Yes Ta 1
517 .It \&Pp Ta \&No Ta \&No Ta 0
518 .It \&Rv Ta \&No Ta \&No Ta n
519 .It \&Sm Ta \&No Ta \&No Ta 1
520 .It \&St Ta \&No Ta Yes Ta 1
521 .It \&Sx Ta Yes Ta Yes Ta >0
522 .It \&Sy Ta Yes Ta Yes Ta >0
523 .It \&Tn Ta Yes Ta Yes Ta >0
524 .It \&Ud Ta \&No Ta \&No Ta 0
525 .It \&Ux Ta Yes Ta Yes Ta n
526 .It \&Va Ta Yes Ta Yes Ta n
527 .It \&Vt Ta Yes Ta Yes Ta >0
528 .It \&Xr Ta Yes Ta Yes Ta >0, <3
529 .It \&br Ta \&No Ta \&No Ta 0
530 .It \&sp Ta \&No Ta \&No Ta 1
535 This section documents compatibility with other roff implementations, at
540 refers to those versions before the
543 .Pq somewhere between 1.15 and 1.19 .
554 applies to the whole document, not just to the current section as it
557 In quoted literals, groff allowed pair-wise double-quotes to produce a
558 standalone double-quote in formatted output. This idiosyncratic
559 behaviour is no longer applicable.
563 macro does not accept negative numbers.
565 Blocks of whitespace are stripped from both macro and free-form text
566 lines (except when in literal mode), while groff would retain whitespace
567 in free-form text lines.
569 Historic groff has many un-callable macros. Most of these (excluding
570 some block-level macros) are now callable, conforming to the
571 non-historic groff version.
577 but is a proper delimiter in this implementation.
580 is assumed for all lists (it wasn't in historic groff): any list may be
583 lists will restart the sequence only for the sub-list.
586 syntax where column widths may be preceded by other arguments (instead
587 of proceeded) is not supported.
591 macro only accepts a single parameter.
595 incorrectly by following it with a reserved character and expecting the
596 delimiter to render. This is not supported.
600 macro only produces the first parameter. This is no longer the case.
612 reference was written by
613 .An Kristaps Dzonsons Aq kristaps@kth.se .
617 There are many ambiguous parts of mdoc.
625 as function arguments are variables.
630 as function return types are still types. Furthermore, the
632 should be removed and
634 which ostensibly follows it, should follow the same convention as
638 should formalise that only one or two arguments are acceptable: a
639 variable name and optional, preceding type.
642 is ambiguous. It's commonly used to indicate an include file in the
645 should be used, instead.
651 makes sense. The remaining ones should be removed.
657 macros should be deprecated.
661 macro lacks clarity. It should be absolutely clear which title will
662 render when formatting the manual page.
666 should be provided for Linux (\(`a la
671 There's no way to refer to references in
675 The \-split and \-nosplit dictates via
677 are re-set when entering and leaving the AUTHORS section.
git.ckatri.com / mandoc.git / blob