1 .\" $Id: mdoc.7,v 1.18 2009/03/27 13:44:24 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 27 2009 $
25 .Nd mdoc language reference
30 language is used to format
33 manuals. In this reference document, we describe the syntax, ontology
41 document follows simple rules: lines beginning with the control
44 are parsed for macros. Other lines are interpreted within the scope of
46 .Bd -literal -offset XXX
47 \&.Sh Macro lines change control state.
48 Other lines are interpreted within the current state.
53 documents may contain only graphable 7-bit ASCII characters, the space
56 and, in certain circumstances, the tab character
62 The only time a blank line is acceptable is within
66 .Sq \&.Bd \-unfilled .
70 are only acceptable when delimiting
78 .Ss Reserved Characters
79 Within a macro line, the following characters are reserved:
80 .Bl -tag -width 12n -offset XXXX -compact
104 Use of reserved characters is described in
106 For general non-reserved use, characters must either be escaped with a
109 or, if applicable, an appropriate escape-sequence used.
111 .Ss Special Characters
112 Special character 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.
122 Characters may alternatively be escaped by a slash-asterisk,
124 with the same combinations as described above. This form is deprecated.
126 The following is a table of all available escapes.
129 .Bl -tag -width 12n -offset "XXXX" -compact
147 .Pq upside-down exclamation
149 .Pq upside-down question
154 .Bl -tag -width 12n -offset "XXXX" -compact
182 .Pq left double-quote
184 .Pq left double-quote, deprecated
186 .Pq right double-quote
188 .Pq right double-quote, deprecated
190 .Pq left single-quote
192 .Pq right single-quote
194 .Pq right low double-quote
196 .Pq right low single-quote
201 .Bl -tag -width 12n -offset "XXXX" -compact
213 .Pq left double-arrow
215 .Pq right double-arrow
219 .Pq down double-arrow
221 .Pq left-right double-arrow
226 .Bl -tag -width 12n -offset "XXXX" -compact
236 .Pq partial differential
262 .Pq existential quantifier
264 .Pq universal quantifier
278 .Pq approximately equals
282 .Pq greater-than, deprecated
284 .Pq less-than, deprecated
288 .Pq less-than-equal, deprecated
290 .Pq greater-than-equal
292 .Pq greater-than-equal
298 .Pq not equal, deprecated
302 .Pq infinity, deprecated
304 .Pq NaN , an extension
310 .Pq plus-minus, deprecated
317 .Bl -tag -width 12n -offset "XXXX" -compact
341 Diacritics and letters:
342 .Bl -tag -width 12n -offset "XXXX" -compact
354 .Pq circumflex accent
378 .Pq upper-case acute A
380 .Pq upper-case acute E
382 .Pq upper-case acute I
384 .Pq upper-case acute O
386 .Pq upper-case acute U
388 .Pq lower-case acute a
390 .Pq lower-case acute e
392 .Pq lower-case acute i
394 .Pq lower-case acute o
396 .Pq lower-case acute u
398 .Pq upper-case grave A
400 .Pq upper-case grave E
402 .Pq upper-case grave I
404 .Pq upper-case grave O
406 .Pq upper-case grave U
408 .Pq lower-case grave a
410 .Pq lower-case grave e
412 .Pq lower-case grave i
414 .Pq lower-case grave o
416 .Pq lower-case grave u
418 .Pq upper-case tilde A
420 .Pq upper-case tilde N
422 .Pq upper-case tilde O
424 .Pq lower-case tilde a
426 .Pq lower-case tilde n
428 .Pq lower-case tilde o
430 .Pq upper-case dieresis A
432 .Pq upper-case dieresis E
434 .Pq upper-case dieresis I
436 .Pq upper-case dieresis O
438 .Pq upper-case dieresis U
440 .Pq lower-case dieresis a
442 .Pq lower-case dieresis e
444 .Pq lower-case dieresis i
446 .Pq lower-case dieresis o
448 .Pq lower-case dieresis u
450 .Pq lower-case dieresis y
452 .Pq upper-case circumflex A
454 .Pq upper-case circumflex E
456 .Pq upper-case circumflex I
458 .Pq upper-case circumflex O
460 .Pq upper-case circumflex U
462 .Pq lower-case circumflex a
464 .Pq lower-case circumflex e
466 .Pq lower-case circumflex i
468 .Pq lower-case circumflex o
470 .Pq lower-case circumflex u
472 .Pq upper-case cedilla C
474 .Pq lower-case cedilla c
476 .Pq upper-case stroke L
478 .Pq lower-case stroke l
480 .Pq upper-case stroke O
482 .Pq lower-case stroke o
484 .Pq upper-case ring A
486 .Pq lower-case ring a
491 .Bl -tag -width 12n -offset "XXXX" -compact
508 .Bl -tag -width 12n -offset "XXXX" -compact
536 .Pq non-breaking space
540 .Pq ampersand, deprecated
544 Macros are classified in an ontology described by their scope rules.
545 Some macros are allowed to deviate from their classifications to
546 preserve backward-compatibility with old macro combinations still found
547 in the manual corpus. These are specifically noted on a per-macro
554 macros enclose other block macros, in-line macros or text, and
555 may span multiple lines.
556 .Bl -inset -offset XXXX
559 macros always span multiple lines. They consist of zero or
562 subsequent macros or text on the same line following invocation; an
565 which spans subsequent lines of text or macros; and an optional
567 macros or text on the same line following closure.
570 macros may span multiple lines. They consists of a optional
572 text immediately following invocation; always a
574 text or macros following the head on the same and subsequent lines; and
577 text immediately following closure.
580 macros may only enclose text and span at most a single line.
585 Closure of a macro's scope depends first on its classification, then
586 on whether it's parsable. In this table,
588 refers to block full-explicit and so on.
591 .Bl -tag -width 12n -offset XXXX -compact
593 corresponding explicit closure macro
595 end-of-file or a corresponding implicit closure macro
597 end-of-line (body may be closed by >0 space-separated
598 .Sx Reserved Characters ,
599 although block scope will still be open)
605 If a macro (block or in-line) is parsable, it may also be closed out by
606 one of the following scenarios (unless specifically noted otherwise):
609 .Bl -dash -offset XXXX -compact
611 a sequence of >0 space-separated
612 .Sx Reserved Characters ,
618 completion of a set number of arguments.
622 If >0 space-separated
623 .Sx Reserved Characters
624 are followed by non-reserved characters, the behaviour differs per
625 macro. In general, scope of the macro is closed and re-opened:
626 subsequent tokens are interpreted as if the scope had just been opened.
627 In other circumstances, scope is simply closed out.
630 Macros are two or three characters in length. The syntax of macro
631 invocation depends on its classification.
633 refers to the macro arguments (which may contain zero or more values).
634 In these illustrations,
636 opens the scope of a macro, and if specified,
638 closes it out (closure may be implicit at end-of-line or end-of-file).
641 Block full-explicit (may contain head, body, tail).
642 .Bd -literal -offset XXXX
643 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
645 \&.Yc \(lBtail...\(rB
649 Block full-implicit (may contain zero or more heads, body, no tail).
650 .Bd -literal -offset XXXX
651 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
657 Block partial-explicit (may contain head, multi-line body, tail).
658 .Bd -literal -offset XXXX
659 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
661 \&.Yc \(lBtail...\(rB
663 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
664 \(lBbody...\(rB \&Yc \(lBtail...\(rB
668 Block partial-implicit (no head, body, no tail). Note that the body
669 section may be followed by zero or more
671 These are in the block scope, but not in the body scope.
672 .Bd -literal -offset XXXX
673 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
677 In-lines have \(>=0 scoped arguments.
678 .Bd -literal -offset XXX
679 \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
681 \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
685 This section contains a complete list of all
687 macros, arranged ontologically. A
689 macro is invoked subsequent to the initial macro-line macro. A
691 macro may be followed by further (ostensibly callable) macros.
693 .Ss Block full-implicit
694 The head of these macros follows invocation; the body is the content of
695 subsequent lines prior to closure. None of these macros have tails;
706 .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
707 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
708 .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
709 .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
710 .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
713 .Ss Block full-explicit
714 None of these macros are callable or parsed. The last column indicates
715 the explicit scope rules. All contains bodies, some may contain heads
718 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
719 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
720 .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
721 .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
722 .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
723 .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
724 .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
725 .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
726 .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
727 .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
730 .Ss Block partial-implicit
731 All of these are callable and parsed for further macros. Their scopes
732 close at the invocation's end-of-line.
734 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
735 .It Em Macro Ta Em Callable Ta Em Parsable
736 .It \&.Aq Ta Yes Ta Yes
737 .It \&.Op Ta Yes Ta Yes
738 .It \&.Bq Ta Yes Ta Yes
739 .It \&.Dq Ta Yes Ta Yes
740 .It \&.Pq Ta Yes Ta Yes
741 .It \&.Qq Ta Yes Ta Yes
742 .It \&.Sq Ta Yes Ta Yes
743 .It \&.Brq Ta Yes Ta Yes
744 .It \&.D1 Ta \&No Ta \&Yes
745 .It \&.Dl Ta \&No Ta Yes
746 .It \&.Ql Ta Yes Ta Yes
754 as in the following example:
755 .Bd -literal -offset XXXX
760 In the above example, the scope of
762 is technically broken by
764 however, due to the overwhelming existence of this sequence, it's
767 .Ss Block partial-explicit
768 Each of these contains at least a body and, in limited circumstances, a
770 .Pq So \&.Fo Sc , So \&.Eo Sc
774 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
775 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
776 .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
777 .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
778 .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
779 .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
780 .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
781 .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
782 .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
783 .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
784 .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
785 .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
786 .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
787 .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
788 .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
789 .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
790 .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
791 .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
792 .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
793 .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
794 .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
795 .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
796 .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
797 .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
798 .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
799 .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
803 In-line macros have only text children. If a number (or inequality) of
806 then the macro accepts an arbitrary number of arguments.
808 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
809 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
810 .It \&.Dd Ta \&No Ta \&No Ta >0
811 .It \&.Dt Ta \&No Ta \&No Ta n
812 .It \&.Os Ta \&No Ta \&No Ta n
813 .It \&.Pp Ta \&No Ta \&No Ta 0
814 .It \&.Ad Ta Yes Ta Yes Ta n
815 .It \&.An Ta \&No Ta Yes Ta n
816 .It \&.Ar Ta Yes Ta Yes Ta n
817 .It \&.Cd Ta Yes Ta \&No Ta >0
818 .It \&.Cm Ta Yes Ta Yes Ta n
819 .It \&.Dv Ta Yes Ta Yes Ta n
820 .It \&.Er Ta Yes Ta Yes Ta >0
821 .It \&.Ev Ta Yes Ta Yes Ta n
822 .It \&.Ex Ta \&No Ta \&No Ta 0
823 .It \&.Fa Ta Yes Ta Yes Ta n
824 .It \&.Fd Ta \&No Ta \&No Ta >0
825 .It \&.Fl Ta Yes Ta Yes Ta n
826 .It \&.Fn Ta Yes Ta Yes Ta >0
827 .It \&.Ft Ta \&No Ta Yes Ta n
828 .It \&.Ic Ta Yes Ta Yes Ta >0
829 .It \&.In Ta \&No Ta \&No Ta n
830 .It \&.Li Ta Yes Ta Yes Ta n
831 .It \&.Nd Ta \&No Ta \&No Ta n
832 .It \&.Nm Ta Yes Ta Yes Ta n
833 .It \&.Ot Ta \&No Ta \&No Ta n
834 .It \&.Pa Ta Yes Ta Yes Ta n
835 .It \&.Rv Ta \&No Ta \&No Ta 0
836 .It \&.St Ta \&No Ta Yes Ta 1
837 .It \&.Va Ta Yes Ta Yes Ta n
838 .It \&.Vt Ta Yes Ta Yes Ta >0
839 .It \&.Xr Ta Yes Ta Yes Ta >0, <3
840 .It \&.%A Ta \&No Ta \&No Ta >0
841 .It \&.%B Ta \&No Ta \&No Ta >0
842 .It \&.%C Ta \&No Ta \&No Ta >0
843 .It \&.%D Ta \&No Ta \&No Ta >0
844 .It \&.%I Ta \&No Ta \&No Ta >0
845 .It \&.%J Ta \&No Ta \&No Ta >0
846 .It \&.%N Ta \&No Ta \&No Ta >0
847 .It \&.%O Ta \&No Ta \&No Ta >0
848 .It \&.%P Ta \&No Ta \&No Ta >0
849 .It \&.%R Ta \&No Ta \&No Ta >0
850 .It \&.%T Ta \&No Ta \&No Ta >0
851 .It \&.%V Ta \&No Ta \&No Ta >0
852 .It \&.At Ta Yes Ta Yes Ta 1
853 .It \&.Bsx Ta Yes Ta Yes Ta n
854 .It \&.Bx Ta Yes Ta Yes Ta n
855 .It \&.Db Ta \&No Ta \&No Ta 1
856 .It \&.Em Ta Yes Ta Yes Ta n
857 .It \&.Fx Ta Yes Ta Yes Ta n
858 .It \&.Ms Ta \&No Ta Yes Ta >0
859 .It \&.No Ta Yes Ta Yes Ta 0
860 .It \&.Ns Ta Yes Ta Yes Ta 0
861 .It \&.Nx Ta Yes Ta Yes Ta n
862 .It \&.Ox Ta Yes Ta Yes Ta n
863 .It \&.Pf Ta \&No Ta Yes Ta 1
864 .It \&.Sm Ta \&No Ta \&No Ta 1
865 .It \&.Sx Ta Yes Ta Yes Ta >0
866 .It \&.Sy Ta Yes Ta Yes Ta >0
867 .It \&.Tn Ta Yes Ta Yes Ta >0
868 .It \&.Ux Ta Yes Ta Yes Ta n
869 .It \&.Dx Ta Yes Ta Yes Ta n
870 .It \&.Bt Ta \&No Ta \&No Ta 0
871 .It \&.Hf Ta \&No Ta \&No Ta n
872 .It \&.Fr Ta \&No Ta \&No Ta n
873 .It \&.Ud Ta \&No Ta \&No Ta 0
874 .It \&.Lb Ta \&No Ta \&No Ta 1
875 .It \&.Ap Ta Yes Ta Yes Ta 0
876 .It \&.Lp Ta \&No Ta \&No Ta 0
877 .It \&.Lk Ta \&No Ta Yes Ta >0
878 .It \&.Mt Ta \&No Ta Yes Ta >0
879 .It \&.Es Ta \&No Ta \&No Ta 0
880 .It \&.En Ta \&No Ta \&No Ta 0
892 The mdoc language was traditionally a
894 macro package; most existing manuals were written with mdoc syntax
895 dictated by system-dependent roff installations. This section documents
896 compatibility with these systems.
904 historically weren't always callable. Both are now correctly callable.
908 is assumed for all lists: any list may be nested and
910 lists will restart the sequence only for the sub-list.
914 syntax where column widths may be preceeded by other arguments (instead
915 of proceeded) is not supported.
920 macro only accepts a single parameter.
923 The system-name macros (
937 incorrectly by following it with a reserved character and expecting the
938 delimiter to render. This is not supported.
951 utility was written by
952 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
955 There are several ambiguous parts of mdoc.
963 as function arguments are variables.
969 as function return types are still types. Furthermore, the
971 should be removed and
973 which ostensibly follows it, should follow the same convention as
978 should formalise that only one or two arguments are acceptable: a
979 variable name and optional, preceeding type.
983 is ambiguous. It's commonly used to indicate an include file in the
986 should be used, instead.
993 makes sense. The remaining ones should be removed.
1000 macros should be deprecated.
1005 macro lacks clarity. It should be absolutely clear which title will
1006 render when formatting the manual page.
1011 should be provided for Linux (\(`a la
1017 There's no way to refer to references in
git.ckatri.com / mandoc.git / blob