1 .\" $Id: mdoc.7,v 1.11 2009/03/21 13:37:31 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 21 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 The only time a blank line is acceptable is within
60 are only acceptable when delimiting
68 .Ss Reserved Characters
69 Within a macro line, the following characters are reserved:
70 .Bl -tag -width 12n -offset XXXX -compact
94 Use of reserved characters is described in
96 For general non-reserved use, characters must either be escaped with a
99 or, if applicable, an appropriate escape-sequence used.
101 .Ss Special Characters
102 Special character sequences begin with the escape character
104 followed by either an open-parenthesis
106 for two-character sequences; an open-bracket
108 for n-character sequences (terminated at a close-bracket
110 or a single one-character sequence.
112 Characters may alternatively be escaped by a slash-asterisk,
114 with the same combinations as described above. This form is deprecated.
116 The following is a table of all available escapes.
119 .Bl -tag -width 12n -offset "XXXX" -compact
137 .Pq upside-down exclamation
139 .Pq upside-down question
144 .Bl -tag -width 12n -offset "XXXX" -compact
172 .Pq left double-quote
174 .Pq left double-quote, deprecated
176 .Pq right double-quote
178 .Pq right double-quote, deprecated
180 .Pq left single-quote
182 .Pq right single-quote
184 .Pq right low double-quote
186 .Pq right low single-quote
191 .Bl -tag -width 12n -offset "XXXX" -compact
203 .Pq left double-arrow
205 .Pq right double-arrow
209 .Pq down double-arrow
211 .Pq left-right double-arrow
216 .Bl -tag -width 12n -offset "XXXX" -compact
226 .Pq partial differential
252 .Pq existential quantifier
254 .Pq universal quantifier
268 .Pq approximately equals
272 .Pq greater-than, deprecated
274 .Pq less-than, deprecated
278 .Pq less-than-equal, deprecated
280 .Pq greater-than-equal
282 .Pq greater-than-equal
288 .Pq not equal, deprecated
292 .Pq infinity, deprecated
294 .Pq NaN , an extension
300 .Pq plus-minus, deprecated
307 .Bl -tag -width 12n -offset "XXXX" -compact
331 Diacritics and letters:
332 .Bl -tag -width 12n -offset "XXXX" -compact
344 .Pq circumflex accent
368 .Pq upper-case acute A
370 .Pq upper-case acute E
372 .Pq upper-case acute I
374 .Pq upper-case acute O
376 .Pq upper-case acute U
378 .Pq lower-case acute a
380 .Pq lower-case acute e
382 .Pq lower-case acute i
384 .Pq lower-case acute o
386 .Pq lower-case acute u
388 .Pq upper-case grave A
390 .Pq upper-case grave E
392 .Pq upper-case grave I
394 .Pq upper-case grave O
396 .Pq upper-case grave U
398 .Pq lower-case grave a
400 .Pq lower-case grave e
402 .Pq lower-case grave i
404 .Pq lower-case grave o
406 .Pq lower-case grave u
408 .Pq upper-case tilde A
410 .Pq upper-case tilde N
412 .Pq upper-case tilde O
414 .Pq lower-case tilde a
416 .Pq lower-case tilde n
418 .Pq lower-case tilde o
420 .Pq upper-case dieresis A
422 .Pq upper-case dieresis E
424 .Pq upper-case dieresis I
426 .Pq upper-case dieresis O
428 .Pq upper-case dieresis U
430 .Pq lower-case dieresis a
432 .Pq lower-case dieresis e
434 .Pq lower-case dieresis i
436 .Pq lower-case dieresis o
438 .Pq lower-case dieresis u
440 .Pq lower-case dieresis y
442 .Pq upper-case circumflex A
444 .Pq upper-case circumflex E
446 .Pq upper-case circumflex I
448 .Pq upper-case circumflex O
450 .Pq upper-case circumflex U
452 .Pq lower-case circumflex a
454 .Pq lower-case circumflex e
456 .Pq lower-case circumflex i
458 .Pq lower-case circumflex o
460 .Pq lower-case circumflex u
462 .Pq upper-case cedilla C
464 .Pq lower-case cedilla c
466 .Pq upper-case stroke L
468 .Pq lower-case stroke l
470 .Pq upper-case stroke O
472 .Pq lower-case stroke o
474 .Pq upper-case ring A
476 .Pq lower-case ring a
481 .Bl -tag -width 12n -offset "XXXX" -compact
498 .Bl -tag -width 12n -offset "XXXX" -compact
524 .Pq non-breaking space
528 .Pq ampersand, deprecated
532 Macros are classified in an ontology described by scope rules.
538 macros enclose other block macros, in-line macros or text, and
539 may span multiple lines.
540 .Bl -inset -offset XXXX
543 macros always span multiple lines. They consist of zero or
546 subsequent macros or text on the same line following invocation; an
549 which spans subsequent lines of text or macros; and an optional
551 macros or text on the same line following closure.
554 macros may span multiple lines. They consists of a optional
556 text immediately following invocation; always a
558 text or macros following the head on the same and subsequent lines; and
561 text immediately following closure.
564 macros may only enclose text and span at most a single line.
569 Closure of a macro's scope depends first on its classification, then
570 on whether it's parsable. In this table,
572 refers to block full-explicit and so on.
575 .Bl -tag -width 12n -offset XXXX -compact
577 corresponding explicit closure macro
579 end-of-file or a corresponding implicit closure macro
581 end-of-line (body may be closed by >0 space-separated
582 .Sx Reserved Characters ,
583 although block scope will still be open)
589 If a macro (block or in-line) is parsable, it may also be closed out by
590 one of the following scenarios (unless specifically noted otherwise):
593 .Bl -dash -offset XXXX -compact
595 a sequence of >0 space-separated
596 .Sx Reserved Characters ,
602 completion of a set number of arguments.
606 If >0 space-separated
607 .Sx Reserved Characters
608 are followed by non-reserved characters, the behaviour differs per
609 macro. In general, scope of the macro is closed and re-opened:
610 subsequent tokens are interpreted as if the scope had just been opened.
611 In other circumstances, scope is simply closed out.
614 Macros are generally two and at times three characters in length. The
615 syntax of macro invocation depends on its classification.
617 refers to the macro arguments (which may contain zero or more values).
618 In these illustrations,
620 opens the scope of a macro, and if specified,
622 closes it out (closure may be implicit at end-of-line or end-of-file).
625 Block full-explicit (may contain head, body, tail).
626 .Bd -literal -offset XXXX
627 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
629 \&.Yc \(lBtail...\(rB
633 Block full-implicit (may contain zero or more heads, body, no tail).
634 .Bd -literal -offset XXXX
635 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
641 Block partial-explicit (may contain head, multi-line body, tail).
642 .Bd -literal -offset XXXX
643 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
645 \&.Yc \(lBtail...\(rB
647 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
648 \(lBbody...\(rB \&Yc \(lBtail...\(rB
652 Block partial-implicit (no head, body, no tail). Note that the body
653 section may be followed by zero or more
655 These are in the block scope, but not in the body scope.
656 .Bd -literal -offset XXXX
657 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
661 In-lines have \(>=0 scoped arguments.
662 .Bd -literal -offset XXX
663 \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
665 \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
669 This section contains a complete list of all
671 macros, arranged ontologically. A
673 macro is may be invoked subsequent to the initial macro-line macro. A
675 macro may be followed by further (ostensibly callable) macros.
677 .Ss Block full-implicit
678 The head of these macros follows invocation; the body is the content of
679 subsequent lines prior to closure. None of these macros have tails;
690 .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
691 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
692 .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
693 .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
694 .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
697 .Ss Block full-explicit
698 None of these macros are callable or parsed. The last column indicates
699 the explicit scope rules. All contains bodies, some may contain heads
702 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
703 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
704 .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
705 .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
706 .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
707 .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
708 .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
709 .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
710 .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
711 .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
714 .Ss Block partial-implicit
715 All of these are callable and parsed for further macros. Their scopes
716 close at the invocation's end-of-line.
718 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
719 .It Em Macro Ta Em Callable Ta Em Parsable
720 .It \&.Aq Ta Yes Ta Yes
721 .It \&.Op Ta Yes Ta Yes
722 .It \&.Bq Ta Yes Ta Yes
723 .It \&.Dq Ta Yes Ta Yes
724 .It \&.Pq Ta Yes Ta Yes
725 .It \&.Qq Ta Yes Ta Yes
726 .It \&.Sq Ta Yes Ta Yes
727 .It \&.Brq Ta Yes Ta Yes
728 .It \&.D1 Ta \&No Ta \&Yes
729 .It \&.Dl Ta \&No Ta Yes
730 .It \&.Ql Ta Yes Ta Yes
733 .Ss Block partial-explicit
734 Each of these contains at least a body and, in limited circumstances, a
736 .Pq So \&Fo Sc , So \&Eo Sc
740 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
741 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
742 .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
743 .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
744 .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
745 .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
746 .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
747 .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
748 .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
749 .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
750 .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
751 .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
752 .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
753 .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
754 .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
755 .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
756 .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
757 .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
758 .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
759 .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
760 .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
761 .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
762 .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
763 .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
764 .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
765 .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
769 In-line macros have only text children. If a number (or inequality) of
772 then the macro accepts an arbitrary number of arguments.
774 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
775 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
776 .It \&.Dd Ta \&No Ta \&No Ta >0
777 .It \&.Dt Ta \&No Ta \&No Ta n
778 .It \&.Os Ta \&No Ta \&No Ta n
779 .It \&.Pp Ta \&No Ta \&No Ta 0
780 .It \&.Ad Ta Yes Ta Yes Ta n
781 .It \&.An Ta \&No Ta Yes Ta n
782 .It \&.Ar Ta Yes Ta Yes Ta n
783 .It \&.Cd Ta Yes Ta \&No Ta >0
784 .It \&.Cm Ta Yes Ta Yes Ta n
785 .It \&.Dv Ta Yes Ta Yes Ta n
786 .It \&.Er Ta Yes Ta Yes Ta >0
787 .It \&.Ev Ta Yes Ta Yes Ta n
788 .It \&.Ex Ta \&No Ta \&No Ta 0
789 .It \&.Fa Ta Yes Ta Yes Ta >0
790 .It \&.Fd Ta \&No Ta \&No Ta >0
791 .It \&.Fl Ta Yes Ta Yes Ta n
792 .It \&.Fn Ta Yes Ta Yes Ta >0
793 .It \&.Ft Ta \&No Ta Yes Ta n
794 .It \&.Ic Ta Yes Ta Yes Ta >0
795 .It \&.In Ta \&No Ta \&No Ta n
796 .It \&.Li Ta Yes Ta Yes Ta n
797 .It \&.Nd Ta \&No Ta \&No Ta n
798 .It \&.Nm Ta Yes Ta Yes Ta n
799 .It \&.Ot Ta \&No Ta \&No Ta n
800 .It \&.Pa Ta Yes Ta Yes Ta n
801 .It \&.Rv Ta \&No Ta \&No Ta 0
802 .It \&.St Ta \&No Ta Yes Ta 1
803 .It \&.Va Ta Yes Ta Yes Ta n
804 .It \&.Vt Ta Yes Ta Yes Ta >0
805 .It \&.Xr Ta Yes Ta Yes Ta >0, <3
806 .It \&.%A Ta \&No Ta \&No Ta >0
807 .It \&.%B Ta \&No Ta \&No Ta >0
808 .It \&.%C Ta \&No Ta \&No Ta >0
809 .It \&.%D Ta \&No Ta \&No Ta >0
810 .It \&.%I Ta \&No Ta \&No Ta >0
811 .It \&.%J Ta \&No Ta \&No Ta >0
812 .It \&.%N Ta \&No Ta \&No Ta >0
813 .It \&.%O Ta \&No Ta \&No Ta >0
814 .It \&.%P Ta \&No Ta \&No Ta >0
815 .It \&.%R Ta \&No Ta \&No Ta >0
816 .It \&.%T Ta \&No Ta \&No Ta >0
817 .It \&.%V Ta \&No Ta \&No Ta >0
818 .It \&.At Ta Yes Ta Yes Ta 1
819 .It \&.Bsx Ta Yes Ta Yes Ta n
820 .It \&.Bx Ta Yes Ta Yes Ta n
821 .It \&.Db Ta \&No Ta \&No Ta 1
822 .It \&.Em Ta Yes Ta Yes Ta n
823 .It \&.Fx Ta Yes Ta Yes Ta n
824 .It \&.Ms Ta \&No Ta Yes Ta >0
825 .It \&.No Ta Yes Ta Yes Ta 0
826 .It \&.Ns Ta Yes Ta Yes Ta 0
827 .It \&.Nx Ta Yes Ta Yes Ta n
828 .It \&.Ox Ta Yes Ta Yes Ta n
829 .It \&.Pf Ta \&No Ta Yes Ta 1
830 .It \&.Sm Ta \&No Ta \&No Ta 1
831 .It \&.Sx Ta Yes Ta Yes Ta >0
832 .It \&.Sy Ta Yes Ta Yes Ta >0
833 .It \&.Tn Ta Yes Ta Yes Ta >0
834 .It \&.Ux Ta Yes Ta Yes Ta n
835 .It \&.Dx Ta Yes Ta Yes Ta n
836 .It \&.Bt Ta \&No Ta \&No Ta 0
837 .It \&.Hf Ta \&No Ta \&No Ta n
838 .It \&.Fr Ta \&No Ta \&No Ta n
839 .It \&.Ud Ta \&No Ta \&No Ta 0
840 .It \&.Lb Ta \&No Ta \&No Ta 1
841 .It \&.Ap Ta Yes Ta Yes Ta 0
842 .It \&.Lp Ta \&No Ta \&No Ta 0
843 .It \&.Lk Ta \&No Ta Yes Ta >0
844 .It \&.Mt Ta \&No Ta Yes Ta >0
845 .It \&.Es Ta \&No Ta \&No Ta 0
846 .It \&.En Ta \&No Ta \&No Ta 0
858 The mdoc language was traditionally a
860 macro package; most existing manuals were written with mdoc syntax
861 dictated by system-dependent roff installations. This section documents
862 compatibility with these systems.
870 historically weren't always callable. Both are now correctly callable.
874 is assumed for all lists: any list may be nested and
876 lists will restart the sequence only for the sub-list.
880 syntax where column widths may be preceeded by other arguments (instead
881 of proceeded) is not supported.
886 macro only accepts a single parameter.
889 The system-name macros (
903 incorrectly by following it with a reserved character and expecting the
904 delimiter to render. This is not supported.
920 utility was written by
921 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
924 There are several ambiguous parts of mdoc.
932 as function arguments are variables.
938 as function return types are still types. Furthermore, the
940 should be removed and
942 which ostensibly follows it, should follow the same convention as
947 should formalise that only one or two arguments are acceptable: a
948 variable name and optional, preceeding type.
952 is ambiguous. It's commonly used to indicate an include file in the
955 should be used, instead.
962 makes sense. The remaining ones should be removed.
969 macros should be deprecated.
974 macro lacks clarity. It should be absolutely clear which title will
975 render when formatting the manual page.
980 should be provided for Linux (\(`a la
git.ckatri.com / mandoc.git / blob