1 .\" $Id: mdoc.7,v 1.6 2009/03/16 23:37:28 kristaps Exp $
3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the
7 .\" above copyright notice and this permission notice appear in all
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
11 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
12 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
13 .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
14 .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
15 .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
16 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17 .\" PERFORMANCE OF THIS SOFTWARE.
19 .Dd $Mdocdate: March 16 2009 $
25 .Nd mdoc macro reference
30 language is used to format
35 document follows simple rules: lines beginning with the control
38 are parsed for macros. Other lines are interpreted within the scope of
39 prior macros. This document describes the encoding, ontology and syntax
42 .Sh CHARACTER ENCODING
44 documents may contain only printable characters, the space character
46 and, in certain circumstances, the tab character
52 .Ss Reserved Characters
53 Within a macro line, the following characters are reserved:
54 .Bl -tag -width 12n -offset XXXX -compact
78 Use of reserved characters is described in
80 For general non-reserved use, characters must either be escaped with a
83 or, if applicable, an appropriate escape-sequence used.
85 .Ss Special Characters
86 Special character sequences begin with the escape character
88 followed by either an open-parenthesis
90 for two-character sequences; an open-bracket
92 for n-character sequences (terminated at a close-bracket
94 or a single one-character sequence.
96 Characters may alternatively be escaped by a slash-asterisk,
98 with the same combinations as described above. This form is deprecated.
100 The following is a table of all available escapes.
103 .Bl -tag -width 12n -offset "XXXX" -compact
124 .Bl -tag -width 12n -offset "XXXX" -compact
148 .Pq left double-quote
150 .Pq left double-quote, deprecated
152 .Pq right double-quote
154 .Pq right double-quote, deprecated
156 .Pq left single-quote
158 .Pq right single-quote
163 .Bl -tag -width 12n -offset "XXXX" -compact
175 .Pq left double-arrow
177 .Pq right double-arrow
181 .Pq down double-arrow
183 .Pq left-right double-arrow
188 .Bl -tag -width 12n -offset "XXXX" -compact
190 .Pq greater-than, deprecated
192 .Pq less-than, deprecated
196 .Pq less-than-equal, deprecated
198 .Pq greater-than-equal
200 .Pq greater-than-equal
206 .Pq not equal, deprecated
210 .Pq infinity, deprecated
212 .Pq NaN , an extension
218 .Pq plus-minus, deprecated
224 Diacritics and letter combinations:
225 .Bl -tag -width 12n -offset "XXXX" -compact
243 .Pq upper-case acute A
245 .Pq upper-case acute E
247 .Pq upper-case acute I
249 .Pq upper-case acute O
251 .Pq upper-case acute U
253 .Pq lower-case acute a
255 .Pq lower-case acute e
257 .Pq lower-case acute i
259 .Pq lower-case acute o
261 .Pq lower-case acute u
263 .Pq upper-case grave A
265 .Pq upper-case grave E
267 .Pq upper-case grave I
269 .Pq upper-case grave O
271 .Pq upper-case grave U
273 .Pq lower-case grave a
275 .Pq lower-case grave e
277 .Pq lower-case grave i
279 .Pq lower-case grave o
281 .Pq lower-case grave u
283 .Pq upper-case tilde A
285 .Pq upper-case tilde N
287 .Pq upper-case tilde O
289 .Pq lower-case tilde a
291 .Pq lower-case tilde n
293 .Pq lower-case tilde o
295 .Pq upper-case dieresis A
297 .Pq upper-case dieresis E
299 .Pq upper-case dieresis I
301 .Pq upper-case dieresis O
303 .Pq upper-case dieresis U
305 .Pq lower-case dieresis a
307 .Pq lower-case dieresis e
309 .Pq lower-case dieresis i
311 .Pq lower-case dieresis o
313 .Pq lower-case dieresis u
315 .Pq lower-case dieresis y
320 .Bl -tag -width 12n -offset "XXXX" -compact
334 .Pq non-breaking space
338 .Pq ampersand, deprecated
342 Macros are classified in an ontology described by scope rules.
348 macros enclose other block macros, in-line macros or text, and
349 may span multiple lines.
350 .Bl -inset -offset XXXX
353 macros always span multiple lines. They consist of zero or
356 subsequent macros or text on the same line following invocation; an
359 which spans subsequent lines of text or macros; and an optional
361 macros or text on the same line following closure.
364 macros may span multiple lines. They consists of a optional
366 text immediately following invocation; always a
368 text or macros following the head on the same and subsequent lines; and
371 text immediately following closure.
374 macros may only enclose text and span at most a single line.
379 Closure of a macro's scope depends first on its classification, then
380 on whether it's parsable. In this table,
382 refers to block full-explicit and so on.
385 .Bl -tag -width 12n -offset XXXX -compact
387 corresponding explicit closure macro
389 end-of-file or a corresponding implicit closure macro
391 end-of-line (body may be closed by >0 space-separated
392 .Sx Reserved Characters ,
393 although block scope will still be open)
399 If a macro (block or in-line) is parsable, it may also be closed out by
400 one of the following scenarios (unless specifically noted otherwise):
403 .Bl -dash -offset XXXX -compact
405 a sequence of >0 space-separated
406 .Sx Reserved Characters ,
412 completion of a set number of arguments.
416 If >0 space-separated
417 .Sx Reserved Characters
418 are followed by non-reserved characters, the behaviour differs per
419 macro. In general, scope of the macro is closed and re-opened:
420 subsequent tokens are interpreted as if the scope had just been opened.
421 In other circumstances, scope is simply closed out.
424 Macros are generally two and at times three characters in length. The
425 syntax of macro invocation depends on its classification.
427 refers to the macro arguments (which may contain zero or more values).
428 In these illustrations,
430 opens the scope of a macro, and if specified,
432 closes it out (closure may be implicit at end-of-line or end-of-file).
435 Block full-explicit (may contain head, body, tail).
436 .Bd -literal -offset XXXX
437 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
439 \&.Yc \(lBtail...\(rB
443 Block full-implicit (may contain zero or more heads, body, no tail).
444 .Bd -literal -offset XXXX
445 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
451 Block partial-explicit (may contain head, multi-line body, tail).
452 .Bd -literal -offset XXXX
453 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
455 \&.Yc \(lBtail...\(rB
457 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
458 \(lBbody...\(rB \&Yc \(lBtail...\(rB
462 Block partial-implicit (no head, body, no tail). Note that the body
463 section may be followed by zero or more
465 These are in the block scope, but not in the body scope.
466 .Bd -literal -offset XXXX
467 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
471 In-lines have \(>=0 scoped arguments.
472 .Bd -literal -offset XXX
473 \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
475 \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
479 This section contains a complete list of all
481 macros, arranged ontologically. A
483 macro is may be invoked subsequent to the initial macro-line macro. A
485 macro may be followed by further (ostensibly callable) macros.
487 .Ss Block full-implicit
488 The head of these macros follows invocation; the body is the content of
489 subsequent lines prior to closure. None of these macros have tails;
500 .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
501 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
502 .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
503 .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
504 .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
507 .Ss Block full-explicit
508 None of these macros are callable or parsed. The last column indicates
509 the explicit scope rules. All contains bodies, some may contain heads
512 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
513 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
514 .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
515 .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
516 .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
517 .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
518 .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
519 .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
520 .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
521 .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
524 .Ss Block partial-implicit
525 All of these are callable and parsed for further macros. Their scopes
526 close at the invocation's end-of-line.
528 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
529 .It Em Macro Ta Em Callable Ta Em Parsable
530 .It \&.Aq Ta Yes Ta Yes
531 .It \&.Op Ta Yes Ta Yes
532 .It \&.Bq Ta Yes Ta Yes
533 .It \&.Dq Ta Yes Ta Yes
534 .It \&.Pq Ta Yes Ta Yes
535 .It \&.Qq Ta Yes Ta Yes
536 .It \&.Sq Ta Yes Ta Yes
537 .It \&.Brq Ta Yes Ta Yes
538 .It \&.D1 Ta \&No Ta \&Yes
539 .It \&.Dl Ta \&No Ta Yes
540 .It \&.Ql Ta Yes Ta Yes
543 .Ss Block partial-explicit
544 Each of these contains at least a body and, in limited circumstances, a
546 .Pq So \&Fo Sc , So \&Eo Sc
550 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
551 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
552 .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
553 .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
554 .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
555 .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
556 .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
557 .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
558 .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
559 .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
560 .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
561 .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
562 .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
563 .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
564 .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
565 .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
566 .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
567 .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
568 .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
569 .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
570 .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
571 .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
572 .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
573 .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
574 .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
575 .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
579 In-line macros have only text children. If a number (or inequality) of
582 then the macro accepts an arbitrary number of arguments.
584 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
585 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
586 .It \&.Dd Ta \&No Ta \&No Ta >0
587 .It \&.Dt Ta \&No Ta \&No Ta n
588 .It \&.Os Ta \&No Ta \&No Ta n
589 .It \&.Pp Ta \&No Ta \&No Ta 0
590 .It \&.Ad Ta Yes Ta Yes Ta n
591 .It \&.An Ta \&No Ta Yes Ta n
592 .It \&.Ar Ta Yes Ta Yes Ta n
593 .It \&.Cd Ta Yes Ta \&No Ta >0
594 .It \&.Cm Ta Yes Ta Yes Ta n
595 .It \&.Dv Ta Yes Ta Yes Ta >0
596 .It \&.Er Ta Yes Ta Yes Ta >0
597 .It \&.Ev Ta Yes Ta Yes Ta >0
598 .It \&.Ex Ta \&No Ta \&No Ta 0
599 .It \&.Fa Ta Yes Ta Yes Ta >0
600 .It \&.Fd Ta \&No Ta \&No Ta >0
601 .It \&.Fl Ta Yes Ta Yes Ta n
602 .It \&.Fn Ta Yes Ta Yes Ta >0
603 .It \&.Ft Ta \&No Ta Yes Ta n
604 .It \&.Ic Ta Yes Ta Yes Ta >0
605 .It \&.In Ta \&No Ta \&No Ta n
606 .It \&.Li Ta Yes Ta Yes Ta >0
607 .It \&.Nd Ta \&No Ta \&No Ta n
608 .It \&.Nm Ta Yes Ta Yes Ta n
609 .It \&.Ot Ta \&No Ta \&No Ta n
610 .It \&.Pa Ta Yes Ta Yes Ta n
611 .It \&.Rv Ta \&No Ta \&No Ta 0
612 .It \&.St Ta \&No Ta Yes Ta 1
613 .It \&.Va Ta Yes Ta Yes Ta >0
614 .It \&.Vt Ta Yes Ta Yes Ta >0
615 .It \&.Xr Ta Yes Ta Yes Ta >0, <3
616 .It \&.%A Ta \&No Ta \&No Ta >0
617 .It \&.%B Ta \&No Ta \&No Ta >0
618 .It \&.%C Ta \&No Ta \&No Ta >0
619 .It \&.%D Ta \&No Ta \&No Ta >0
620 .It \&.%I Ta \&No Ta \&No Ta >0
621 .It \&.%J Ta \&No Ta \&No Ta >0
622 .It \&.%N Ta \&No Ta \&No Ta >0
623 .It \&.%O Ta \&No Ta \&No Ta >0
624 .It \&.%P Ta \&No Ta \&No Ta >0
625 .It \&.%R Ta \&No Ta \&No Ta >0
626 .It \&.%T Ta \&No Ta \&No Ta >0
627 .It \&.%V Ta \&No Ta \&No Ta >0
628 .It \&.At Ta Yes Ta Yes Ta 1
629 .It \&.Bsx Ta Yes Ta Yes Ta n
630 .It \&.Bx Ta Yes Ta Yes Ta n
631 .It \&.Db Ta \&No Ta \&No Ta 1
632 .It \&.Em Ta Yes Ta Yes Ta >0
633 .It \&.Fx Ta Yes Ta Yes Ta n
634 .It \&.Ms Ta \&No Ta Yes Ta >0
635 .It \&.No Ta Yes Ta Yes Ta 0
636 .It \&.Ns Ta Yes Ta Yes Ta 0
637 .It \&.Nx Ta Yes Ta Yes Ta n
638 .It \&.Ox Ta Yes Ta Yes Ta n
639 .It \&.Pf Ta \&No Ta Yes Ta 1
640 .It \&.Sm Ta \&No Ta \&No Ta 1
641 .It \&.Sx Ta Yes Ta Yes Ta >0
642 .It \&.Sy Ta Yes Ta Yes Ta >0
643 .It \&.Tn Ta Yes Ta Yes Ta >0
644 .It \&.Ux Ta Yes Ta Yes Ta n
645 .It \&.Dx Ta Yes Ta Yes Ta n
646 .It \&.Bt Ta \&No Ta \&No Ta 0
647 .It \&.Hf Ta \&No Ta \&No Ta n
648 .It \&.Fr Ta \&No Ta \&No Ta n
649 .It \&.Ud Ta \&No Ta \&No Ta 0
650 .It \&.Lb Ta \&No Ta \&No Ta 1
651 .It \&.Ap Ta Yes Ta Yes Ta 0
652 .It \&.Lp Ta \&No Ta \&No Ta 0
653 .It \&.Lk Ta \&No Ta Yes Ta >0
654 .It \&.Mt Ta \&No Ta Yes Ta >0
655 .It \&.Es Ta \&No Ta \&No Ta 0
656 .It \&.En Ta \&No Ta \&No Ta 0
668 The mdoc language was traditionally a
670 macro package; most existing manuals were written with mdoc syntax
671 dictated by system-dependent roff installations. This section documents
672 compatibility with these systems.
680 historically weren't always callable. Both are now correctly callable.
684 is assumed for all lists: any list may be nested and
686 lists will restart the sequence only for the sub-list.
690 syntax where column widths may be preceeded by other arguments (instead
691 of proceeded) is not supported.
696 macro only accepts a single parameter.
699 The system-name macros (
713 incorrectly by following it with a reserved character and expecting the
714 delimiter to render. This is not supported.
730 utility was written by
731 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
734 There are several ambiguous parts of mdoc.
742 as function arguments are variables.
748 as function return types are still types. Furthermore, the
750 should be removed and
752 which ostensibly follows it, should follow the same convention as
757 should formalise that only one or two arguments are acceptable: a
758 variable name and optional, preceeding type.
762 is ambiguous. It's commonly used to indicate an include file in the
765 should be used, instead.
772 makes sense. The remaining ones should be removed.
779 macros should be deprecated.
784 macro lacks clarity. It should be absolutely clear which title will
785 render when formatting the manual page.
790 should be provided for Linux (\(`a la
git.ckatri.com / mandoc.git / blob