1 .\" $Id: mdoc.7,v 1.7 2009/03/19 11:49:00 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 19 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
154 .Pq left double-quote
156 .Pq left double-quote, deprecated
158 .Pq right double-quote
160 .Pq right double-quote, deprecated
162 .Pq left single-quote
164 .Pq right single-quote
169 .Bl -tag -width 12n -offset "XXXX" -compact
181 .Pq left double-arrow
183 .Pq right double-arrow
187 .Pq down double-arrow
189 .Pq left-right double-arrow
194 .Bl -tag -width 12n -offset "XXXX" -compact
196 .Pq greater-than, deprecated
198 .Pq less-than, deprecated
202 .Pq less-than-equal, deprecated
204 .Pq greater-than-equal
206 .Pq greater-than-equal
212 .Pq not equal, deprecated
216 .Pq infinity, deprecated
218 .Pq NaN , an extension
224 .Pq plus-minus, deprecated
231 .Bl -tag -width 12n -offset "XXXX" -compact
255 Diacritics and letters:
256 .Bl -tag -width 12n -offset "XXXX" -compact
266 .Pq circumflex accent
290 .Pq upper-case acute A
292 .Pq upper-case acute E
294 .Pq upper-case acute I
296 .Pq upper-case acute O
298 .Pq upper-case acute U
300 .Pq lower-case acute a
302 .Pq lower-case acute e
304 .Pq lower-case acute i
306 .Pq lower-case acute o
308 .Pq lower-case acute u
310 .Pq upper-case grave A
312 .Pq upper-case grave E
314 .Pq upper-case grave I
316 .Pq upper-case grave O
318 .Pq upper-case grave U
320 .Pq lower-case grave a
322 .Pq lower-case grave e
324 .Pq lower-case grave i
326 .Pq lower-case grave o
328 .Pq lower-case grave u
330 .Pq upper-case tilde A
332 .Pq upper-case tilde N
334 .Pq upper-case tilde O
336 .Pq lower-case tilde a
338 .Pq lower-case tilde n
340 .Pq lower-case tilde o
342 .Pq upper-case dieresis A
344 .Pq upper-case dieresis E
346 .Pq upper-case dieresis I
348 .Pq upper-case dieresis O
350 .Pq upper-case dieresis U
352 .Pq lower-case dieresis a
354 .Pq lower-case dieresis e
356 .Pq lower-case dieresis i
358 .Pq lower-case dieresis o
360 .Pq lower-case dieresis u
362 .Pq lower-case dieresis y
364 .Pq upper-case circumflex A
366 .Pq upper-case circumflex E
368 .Pq upper-case circumflex I
370 .Pq upper-case circumflex O
372 .Pq upper-case circumflex U
374 .Pq lower-case circumflex a
376 .Pq lower-case circumflex e
378 .Pq lower-case circumflex i
380 .Pq lower-case circumflex o
382 .Pq lower-case circumflex u
384 .Pq upper-case cedilla C
386 .Pq lower-case cedilla c
388 .Pq upper-case stroke L
390 .Pq lower-case stroke l
392 .Pq upper-case stroke O
394 .Pq lower-case stroke o
396 .Pq upper-case ring A
398 .Pq lower-case ring a
403 .Bl -tag -width 12n -offset "XXXX" -compact
420 .Bl -tag -width 12n -offset "XXXX" -compact
434 .Pq non-breaking space
438 .Pq ampersand, deprecated
442 Macros are classified in an ontology described by scope rules.
448 macros enclose other block macros, in-line macros or text, and
449 may span multiple lines.
450 .Bl -inset -offset XXXX
453 macros always span multiple lines. They consist of zero or
456 subsequent macros or text on the same line following invocation; an
459 which spans subsequent lines of text or macros; and an optional
461 macros or text on the same line following closure.
464 macros may span multiple lines. They consists of a optional
466 text immediately following invocation; always a
468 text or macros following the head on the same and subsequent lines; and
471 text immediately following closure.
474 macros may only enclose text and span at most a single line.
479 Closure of a macro's scope depends first on its classification, then
480 on whether it's parsable. In this table,
482 refers to block full-explicit and so on.
485 .Bl -tag -width 12n -offset XXXX -compact
487 corresponding explicit closure macro
489 end-of-file or a corresponding implicit closure macro
491 end-of-line (body may be closed by >0 space-separated
492 .Sx Reserved Characters ,
493 although block scope will still be open)
499 If a macro (block or in-line) is parsable, it may also be closed out by
500 one of the following scenarios (unless specifically noted otherwise):
503 .Bl -dash -offset XXXX -compact
505 a sequence of >0 space-separated
506 .Sx Reserved Characters ,
512 completion of a set number of arguments.
516 If >0 space-separated
517 .Sx Reserved Characters
518 are followed by non-reserved characters, the behaviour differs per
519 macro. In general, scope of the macro is closed and re-opened:
520 subsequent tokens are interpreted as if the scope had just been opened.
521 In other circumstances, scope is simply closed out.
524 Macros are generally two and at times three characters in length. The
525 syntax of macro invocation depends on its classification.
527 refers to the macro arguments (which may contain zero or more values).
528 In these illustrations,
530 opens the scope of a macro, and if specified,
532 closes it out (closure may be implicit at end-of-line or end-of-file).
535 Block full-explicit (may contain head, body, tail).
536 .Bd -literal -offset XXXX
537 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
539 \&.Yc \(lBtail...\(rB
543 Block full-implicit (may contain zero or more heads, body, no tail).
544 .Bd -literal -offset XXXX
545 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
551 Block partial-explicit (may contain head, multi-line body, tail).
552 .Bd -literal -offset XXXX
553 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
555 \&.Yc \(lBtail...\(rB
557 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
558 \(lBbody...\(rB \&Yc \(lBtail...\(rB
562 Block partial-implicit (no head, body, no tail). Note that the body
563 section may be followed by zero or more
565 These are in the block scope, but not in the body scope.
566 .Bd -literal -offset XXXX
567 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
571 In-lines have \(>=0 scoped arguments.
572 .Bd -literal -offset XXX
573 \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
575 \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
579 This section contains a complete list of all
581 macros, arranged ontologically. A
583 macro is may be invoked subsequent to the initial macro-line macro. A
585 macro may be followed by further (ostensibly callable) macros.
587 .Ss Block full-implicit
588 The head of these macros follows invocation; the body is the content of
589 subsequent lines prior to closure. None of these macros have tails;
600 .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
601 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
602 .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
603 .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
604 .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
607 .Ss Block full-explicit
608 None of these macros are callable or parsed. The last column indicates
609 the explicit scope rules. All contains bodies, some may contain heads
612 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
613 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
614 .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
615 .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
616 .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
617 .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
618 .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
619 .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
620 .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
621 .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
624 .Ss Block partial-implicit
625 All of these are callable and parsed for further macros. Their scopes
626 close at the invocation's end-of-line.
628 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
629 .It Em Macro Ta Em Callable Ta Em Parsable
630 .It \&.Aq Ta Yes Ta Yes
631 .It \&.Op Ta Yes Ta Yes
632 .It \&.Bq Ta Yes Ta Yes
633 .It \&.Dq Ta Yes Ta Yes
634 .It \&.Pq Ta Yes Ta Yes
635 .It \&.Qq Ta Yes Ta Yes
636 .It \&.Sq Ta Yes Ta Yes
637 .It \&.Brq Ta Yes Ta Yes
638 .It \&.D1 Ta \&No Ta \&Yes
639 .It \&.Dl Ta \&No Ta Yes
640 .It \&.Ql Ta Yes Ta Yes
643 .Ss Block partial-explicit
644 Each of these contains at least a body and, in limited circumstances, a
646 .Pq So \&Fo Sc , So \&Eo Sc
650 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
651 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
652 .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
653 .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
654 .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
655 .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
656 .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
657 .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
658 .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
659 .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
660 .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
661 .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
662 .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
663 .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
664 .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
665 .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
666 .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
667 .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
668 .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
669 .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
670 .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
671 .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
672 .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
673 .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
674 .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
675 .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
679 In-line macros have only text children. If a number (or inequality) of
682 then the macro accepts an arbitrary number of arguments.
684 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
685 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
686 .It \&.Dd Ta \&No Ta \&No Ta >0
687 .It \&.Dt Ta \&No Ta \&No Ta n
688 .It \&.Os Ta \&No Ta \&No Ta n
689 .It \&.Pp Ta \&No Ta \&No Ta 0
690 .It \&.Ad Ta Yes Ta Yes Ta n
691 .It \&.An Ta \&No Ta Yes Ta n
692 .It \&.Ar Ta Yes Ta Yes Ta n
693 .It \&.Cd Ta Yes Ta \&No Ta >0
694 .It \&.Cm Ta Yes Ta Yes Ta n
695 .It \&.Dv Ta Yes Ta Yes Ta >0
696 .It \&.Er Ta Yes Ta Yes Ta >0
697 .It \&.Ev Ta Yes Ta Yes Ta >0
698 .It \&.Ex Ta \&No Ta \&No Ta 0
699 .It \&.Fa Ta Yes Ta Yes Ta >0
700 .It \&.Fd Ta \&No Ta \&No Ta >0
701 .It \&.Fl Ta Yes Ta Yes Ta n
702 .It \&.Fn Ta Yes Ta Yes Ta >0
703 .It \&.Ft Ta \&No Ta Yes Ta n
704 .It \&.Ic Ta Yes Ta Yes Ta >0
705 .It \&.In Ta \&No Ta \&No Ta n
706 .It \&.Li Ta Yes Ta Yes Ta >0
707 .It \&.Nd Ta \&No Ta \&No Ta n
708 .It \&.Nm Ta Yes Ta Yes Ta n
709 .It \&.Ot Ta \&No Ta \&No Ta n
710 .It \&.Pa Ta Yes Ta Yes Ta n
711 .It \&.Rv Ta \&No Ta \&No Ta 0
712 .It \&.St Ta \&No Ta Yes Ta 1
713 .It \&.Va Ta Yes Ta Yes Ta >0
714 .It \&.Vt Ta Yes Ta Yes Ta >0
715 .It \&.Xr Ta Yes Ta Yes Ta >0, <3
716 .It \&.%A Ta \&No Ta \&No Ta >0
717 .It \&.%B Ta \&No Ta \&No Ta >0
718 .It \&.%C Ta \&No Ta \&No Ta >0
719 .It \&.%D Ta \&No Ta \&No Ta >0
720 .It \&.%I Ta \&No Ta \&No Ta >0
721 .It \&.%J Ta \&No Ta \&No Ta >0
722 .It \&.%N Ta \&No Ta \&No Ta >0
723 .It \&.%O Ta \&No Ta \&No Ta >0
724 .It \&.%P Ta \&No Ta \&No Ta >0
725 .It \&.%R Ta \&No Ta \&No Ta >0
726 .It \&.%T Ta \&No Ta \&No Ta >0
727 .It \&.%V Ta \&No Ta \&No Ta >0
728 .It \&.At Ta Yes Ta Yes Ta 1
729 .It \&.Bsx Ta Yes Ta Yes Ta n
730 .It \&.Bx Ta Yes Ta Yes Ta n
731 .It \&.Db Ta \&No Ta \&No Ta 1
732 .It \&.Em Ta Yes Ta Yes Ta >0
733 .It \&.Fx Ta Yes Ta Yes Ta n
734 .It \&.Ms Ta \&No Ta Yes Ta >0
735 .It \&.No Ta Yes Ta Yes Ta 0
736 .It \&.Ns Ta Yes Ta Yes Ta 0
737 .It \&.Nx Ta Yes Ta Yes Ta n
738 .It \&.Ox Ta Yes Ta Yes Ta n
739 .It \&.Pf Ta \&No Ta Yes Ta 1
740 .It \&.Sm Ta \&No Ta \&No Ta 1
741 .It \&.Sx Ta Yes Ta Yes Ta >0
742 .It \&.Sy Ta Yes Ta Yes Ta >0
743 .It \&.Tn Ta Yes Ta Yes Ta >0
744 .It \&.Ux Ta Yes Ta Yes Ta n
745 .It \&.Dx Ta Yes Ta Yes Ta n
746 .It \&.Bt Ta \&No Ta \&No Ta 0
747 .It \&.Hf Ta \&No Ta \&No Ta n
748 .It \&.Fr Ta \&No Ta \&No Ta n
749 .It \&.Ud Ta \&No Ta \&No Ta 0
750 .It \&.Lb Ta \&No Ta \&No Ta 1
751 .It \&.Ap Ta Yes Ta Yes Ta 0
752 .It \&.Lp Ta \&No Ta \&No Ta 0
753 .It \&.Lk Ta \&No Ta Yes Ta >0
754 .It \&.Mt Ta \&No Ta Yes Ta >0
755 .It \&.Es Ta \&No Ta \&No Ta 0
756 .It \&.En Ta \&No Ta \&No Ta 0
768 The mdoc language was traditionally a
770 macro package; most existing manuals were written with mdoc syntax
771 dictated by system-dependent roff installations. This section documents
772 compatibility with these systems.
780 historically weren't always callable. Both are now correctly callable.
784 is assumed for all lists: any list may be nested and
786 lists will restart the sequence only for the sub-list.
790 syntax where column widths may be preceeded by other arguments (instead
791 of proceeded) is not supported.
796 macro only accepts a single parameter.
799 The system-name macros (
813 incorrectly by following it with a reserved character and expecting the
814 delimiter to render. This is not supported.
830 utility was written by
831 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
834 There are several ambiguous parts of mdoc.
842 as function arguments are variables.
848 as function return types are still types. Furthermore, the
850 should be removed and
852 which ostensibly follows it, should follow the same convention as
857 should formalise that only one or two arguments are acceptable: a
858 variable name and optional, preceeding type.
862 is ambiguous. It's commonly used to indicate an include file in the
865 should be used, instead.
872 makes sense. The remaining ones should be removed.
879 macros should be deprecated.
884 macro lacks clarity. It should be absolutely clear which title will
885 render when formatting the manual page.
890 should be provided for Linux (\(`a la
git.ckatri.com / mandoc.git / blob