1 .\" $Id: mdoc.7,v 1.15 2009/03/23 16:02:56 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 23 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.
52 Macros are two- or three-character sequences whose scope rules, rules
53 that dictate handling of subsequent-line or same-line arguments, are
54 governed by one of five classifications described in this document.
58 documents may contain only graphable 7-bit ASCII characters, the space
61 and, in certain circumstances, the tab character
67 The only time a blank line is acceptable is within
75 are only acceptable when delimiting
83 .Ss Reserved Characters
84 Within a macro line, the following characters are reserved:
85 .Bl -tag -width 12n -offset XXXX -compact
109 Use of reserved characters is described in
111 For general non-reserved use, characters must either be escaped with a
114 or, if applicable, an appropriate escape-sequence used.
116 .Ss Special Characters
117 Special character sequences begin with the escape character
119 followed by either an open-parenthesis
121 for two-character sequences; an open-bracket
123 for n-character sequences (terminated at a close-bracket
125 or a single one-character sequence.
127 Characters may alternatively be escaped by a slash-asterisk,
129 with the same combinations as described above. This form is deprecated.
131 The following is a table of all available escapes.
134 .Bl -tag -width 12n -offset "XXXX" -compact
152 .Pq upside-down exclamation
154 .Pq upside-down question
159 .Bl -tag -width 12n -offset "XXXX" -compact
187 .Pq left double-quote
189 .Pq left double-quote, deprecated
191 .Pq right double-quote
193 .Pq right double-quote, deprecated
195 .Pq left single-quote
197 .Pq right single-quote
199 .Pq right low double-quote
201 .Pq right low single-quote
206 .Bl -tag -width 12n -offset "XXXX" -compact
218 .Pq left double-arrow
220 .Pq right double-arrow
224 .Pq down double-arrow
226 .Pq left-right double-arrow
231 .Bl -tag -width 12n -offset "XXXX" -compact
241 .Pq partial differential
267 .Pq existential quantifier
269 .Pq universal quantifier
283 .Pq approximately equals
287 .Pq greater-than, deprecated
289 .Pq less-than, deprecated
293 .Pq less-than-equal, deprecated
295 .Pq greater-than-equal
297 .Pq greater-than-equal
303 .Pq not equal, deprecated
307 .Pq infinity, deprecated
309 .Pq NaN , an extension
315 .Pq plus-minus, deprecated
322 .Bl -tag -width 12n -offset "XXXX" -compact
346 Diacritics and letters:
347 .Bl -tag -width 12n -offset "XXXX" -compact
359 .Pq circumflex accent
383 .Pq upper-case acute A
385 .Pq upper-case acute E
387 .Pq upper-case acute I
389 .Pq upper-case acute O
391 .Pq upper-case acute U
393 .Pq lower-case acute a
395 .Pq lower-case acute e
397 .Pq lower-case acute i
399 .Pq lower-case acute o
401 .Pq lower-case acute u
403 .Pq upper-case grave A
405 .Pq upper-case grave E
407 .Pq upper-case grave I
409 .Pq upper-case grave O
411 .Pq upper-case grave U
413 .Pq lower-case grave a
415 .Pq lower-case grave e
417 .Pq lower-case grave i
419 .Pq lower-case grave o
421 .Pq lower-case grave u
423 .Pq upper-case tilde A
425 .Pq upper-case tilde N
427 .Pq upper-case tilde O
429 .Pq lower-case tilde a
431 .Pq lower-case tilde n
433 .Pq lower-case tilde o
435 .Pq upper-case dieresis A
437 .Pq upper-case dieresis E
439 .Pq upper-case dieresis I
441 .Pq upper-case dieresis O
443 .Pq upper-case dieresis U
445 .Pq lower-case dieresis a
447 .Pq lower-case dieresis e
449 .Pq lower-case dieresis i
451 .Pq lower-case dieresis o
453 .Pq lower-case dieresis u
455 .Pq lower-case dieresis y
457 .Pq upper-case circumflex A
459 .Pq upper-case circumflex E
461 .Pq upper-case circumflex I
463 .Pq upper-case circumflex O
465 .Pq upper-case circumflex U
467 .Pq lower-case circumflex a
469 .Pq lower-case circumflex e
471 .Pq lower-case circumflex i
473 .Pq lower-case circumflex o
475 .Pq lower-case circumflex u
477 .Pq upper-case cedilla C
479 .Pq lower-case cedilla c
481 .Pq upper-case stroke L
483 .Pq lower-case stroke l
485 .Pq upper-case stroke O
487 .Pq lower-case stroke o
489 .Pq upper-case ring A
491 .Pq lower-case ring a
496 .Bl -tag -width 12n -offset "XXXX" -compact
513 .Bl -tag -width 12n -offset "XXXX" -compact
539 .Pq non-breaking space
543 .Pq ampersand, deprecated
547 Macros are classified in an ontology described by their scope rules.
548 Some macros are allowed to deviate from their classifications to
549 preserve backward-compatibility with old macro combinations still found
550 in the manual corpus. These are specifically noted on a per-macro
557 macros enclose other block macros, in-line macros or text, and
558 may span multiple lines.
559 .Bl -inset -offset XXXX
562 macros always span multiple lines. They consist of zero or
565 subsequent macros or text on the same line following invocation; an
568 which spans subsequent lines of text or macros; and an optional
570 macros or text on the same line following closure.
573 macros may span multiple lines. They consists of a optional
575 text immediately following invocation; always a
577 text or macros following the head on the same and subsequent lines; and
580 text immediately following closure.
583 macros may only enclose text and span at most a single line.
588 Closure of a macro's scope depends first on its classification, then
589 on whether it's parsable. In this table,
591 refers to block full-explicit and so on.
594 .Bl -tag -width 12n -offset XXXX -compact
596 corresponding explicit closure macro
598 end-of-file or a corresponding implicit closure macro
600 end-of-line (body may be closed by >0 space-separated
601 .Sx Reserved Characters ,
602 although block scope will still be open)
608 If a macro (block or in-line) is parsable, it may also be closed out by
609 one of the following scenarios (unless specifically noted otherwise):
612 .Bl -dash -offset XXXX -compact
614 a sequence of >0 space-separated
615 .Sx Reserved Characters ,
621 completion of a set number of arguments.
625 If >0 space-separated
626 .Sx Reserved Characters
627 are followed by non-reserved characters, the behaviour differs per
628 macro. In general, scope of the macro is closed and re-opened:
629 subsequent tokens are interpreted as if the scope had just been opened.
630 In other circumstances, scope is simply closed out.
633 Macros are generally two and at times three characters in length. The
634 syntax of macro invocation depends on its classification.
636 refers to the macro arguments (which may contain zero or more values).
637 In these illustrations,
639 opens the scope of a macro, and if specified,
641 closes it out (closure may be implicit at end-of-line or end-of-file).
644 Block full-explicit (may contain head, body, tail).
645 .Bd -literal -offset XXXX
646 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
648 \&.Yc \(lBtail...\(rB
652 Block full-implicit (may contain zero or more heads, body, no tail).
653 .Bd -literal -offset XXXX
654 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
660 Block partial-explicit (may contain head, multi-line body, tail).
661 .Bd -literal -offset XXXX
662 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB
664 \&.Yc \(lBtail...\(rB
666 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBhead...\(rB \
667 \(lBbody...\(rB \&Yc \(lBtail...\(rB
671 Block partial-implicit (no head, body, no tail). Note that the body
672 section may be followed by zero or more
674 These are in the block scope, but not in the body scope.
675 .Bd -literal -offset XXXX
676 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBreserved...\(rB
680 In-lines have \(>=0 scoped arguments.
681 .Bd -literal -offset XXX
682 \&.Yy \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB
684 \&.Yy \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
688 This section contains a complete list of all
690 macros, arranged ontologically. A
692 macro is may be invoked subsequent to the initial macro-line macro. A
694 macro may be followed by further (ostensibly callable) macros.
696 .Ss Block full-implicit
697 The head of these macros follows invocation; the body is the content of
698 subsequent lines prior to closure. None of these macros have tails;
709 .Bl -column "MacroX" "CallableX" "ParsableX" "Closing" -compact -offset XXXX
710 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Closing
711 .It \&.Sh Ta \&No Ta \&No Ta \&.Sh
712 .It \&.Ss Ta \&No Ta \&No Ta \&.Sh, \&.Ss
713 .It \&.It Ta \&No Ta Yes Ta \&.It, \&.El
716 .Ss Block full-explicit
717 None of these macros are callable or parsed. The last column indicates
718 the explicit scope rules. All contains bodies, some may contain heads
721 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXX" -compact -offset XXXX
722 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
723 .It \&.Bd Ta \&No Ta \&No Ta closed by \&.Ed
724 .It \&.Ed Ta \&No Ta \&No Ta opened by \&.Bd
725 .It \&.Bl Ta \&No Ta \&No Ta closed by \&.El
726 .It \&.El Ta \&No Ta \&No Ta opened by \&.Bl
727 .It \&.Bf Ta \&No Ta \&No Ta closed by \&.Ef
728 .It \&.Ef Ta \&No Ta \&No Ta opened by \&.Bf
729 .It \&.Bk Ta \&No Ta \&No Ta closed by \&.Ek
730 .It \&.Ek Ta \&No Ta \&No Ta opened by \&.Bk
733 .Ss Block partial-implicit
734 All of these are callable and parsed for further macros. Their scopes
735 close at the invocation's end-of-line.
737 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset XXXX
738 .It Em Macro Ta Em Callable Ta Em Parsable
739 .It \&.Aq Ta Yes Ta Yes
740 .It \&.Op Ta Yes Ta Yes
741 .It \&.Bq Ta Yes Ta Yes
742 .It \&.Dq Ta Yes Ta Yes
743 .It \&.Pq Ta Yes Ta Yes
744 .It \&.Qq Ta Yes Ta Yes
745 .It \&.Sq Ta Yes Ta Yes
746 .It \&.Brq Ta Yes Ta Yes
747 .It \&.D1 Ta \&No Ta \&Yes
748 .It \&.Dl Ta \&No Ta Yes
749 .It \&.Ql Ta Yes Ta Yes
755 may be broken by \&Oc as in the following example:
756 .Bd -literal -offset XXXX
761 In the above example, the scope of
763 is technically broken by
765 however, due to the overwhelming existence of this sequence, it's
768 .Ss Block partial-explicit
769 Each of these contains at least a body and, in limited circumstances, a
771 .Pq So \&Fo Sc , So \&Eo Sc
775 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset XXXX
776 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
777 .It \&.Ao Ta Yes Ta Yes Ta closed by \&.Ac
778 .It \&.Ac Ta Yes Ta Yes Ta opened by \&.Ao
779 .It \&.Bc Ta Yes Ta Yes Ta closed by \&.Bo
780 .It \&.Bo Ta Yes Ta Yes Ta opened by \&.Bc
781 .It \&.Pc Ta Yes Ta Yes Ta closed by \&.Po
782 .It \&.Po Ta Yes Ta Yes Ta opened by \&.Pc
783 .It \&.Do Ta Yes Ta Yes Ta closed by \&.Dc
784 .It \&.Dc Ta Yes Ta Yes Ta opened by \&.Do
785 .It \&.Xo Ta Yes Ta Yes Ta closed by \&.Xc
786 .It \&.Xc Ta Yes Ta Yes Ta opened by \&.Xo
787 .It \&.Bro Ta Yes Ta Yes Ta closed by \&.Brc
788 .It \&.Brc Ta Yes Ta Yes Ta opened by \&.Bro
789 .It \&.Oc Ta Yes Ta Yes Ta closed by \&.Oo
790 .It \&.Oo Ta Yes Ta Yes Ta opened by \&.Oc
791 .It \&.So Ta Yes Ta Yes Ta closed by \&.Sc
792 .It \&.Sc Ta Yes Ta Yes Ta opened by \&.So
793 .It \&.Fc Ta Yes Ta Yes Ta opened by \&.Fo
794 .It \&.Fo Ta \&No Ta \&No Ta closed by \&.Fc
795 .It \&.Ec Ta Yes Ta Yes Ta opened by \&.Eo
796 .It \&.Eo Ta Yes Ta Yes Ta closed by \&.Ec
797 .It \&.Qc Ta Yes Ta Yes Ta opened by \&.Oo
798 .It \&.Qo Ta Yes Ta Yes Ta closed by \&.Oc
799 .It \&.Re Ta \&No Ta \&No Ta opened by \&.Rs
800 .It \&.Rs Ta \&No Ta \&No Ta closed by \&.Re
804 In-line macros have only text children. If a number (or inequality) of
807 then the macro accepts an arbitrary number of arguments.
809 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset XXXX
810 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
811 .It \&.Dd Ta \&No Ta \&No Ta >0
812 .It \&.Dt Ta \&No Ta \&No Ta n
813 .It \&.Os Ta \&No Ta \&No Ta n
814 .It \&.Pp Ta \&No Ta \&No Ta 0
815 .It \&.Ad Ta Yes Ta Yes Ta n
816 .It \&.An Ta \&No Ta Yes Ta n
817 .It \&.Ar Ta Yes Ta Yes Ta n
818 .It \&.Cd Ta Yes Ta \&No Ta >0
819 .It \&.Cm Ta Yes Ta Yes Ta n
820 .It \&.Dv Ta Yes Ta Yes Ta n
821 .It \&.Er Ta Yes Ta Yes Ta >0
822 .It \&.Ev Ta Yes Ta Yes Ta n
823 .It \&.Ex Ta \&No Ta \&No Ta 0
824 .It \&.Fa Ta Yes Ta Yes Ta n
825 .It \&.Fd Ta \&No Ta \&No Ta >0
826 .It \&.Fl Ta Yes Ta Yes Ta n
827 .It \&.Fn Ta Yes Ta Yes Ta >0
828 .It \&.Ft Ta \&No Ta Yes Ta n
829 .It \&.Ic Ta Yes Ta Yes Ta >0
830 .It \&.In Ta \&No Ta \&No Ta n
831 .It \&.Li Ta Yes Ta Yes Ta n
832 .It \&.Nd Ta \&No Ta \&No Ta n
833 .It \&.Nm Ta Yes Ta Yes Ta n
834 .It \&.Ot Ta \&No Ta \&No Ta n
835 .It \&.Pa Ta Yes Ta Yes Ta n
836 .It \&.Rv Ta \&No Ta \&No Ta 0
837 .It \&.St Ta \&No Ta Yes Ta 1
838 .It \&.Va Ta Yes Ta Yes Ta n
839 .It \&.Vt Ta Yes Ta Yes Ta >0
840 .It \&.Xr Ta Yes Ta Yes Ta >0, <3
841 .It \&.%A Ta \&No Ta \&No Ta >0
842 .It \&.%B Ta \&No Ta \&No Ta >0
843 .It \&.%C Ta \&No Ta \&No Ta >0
844 .It \&.%D Ta \&No Ta \&No Ta >0
845 .It \&.%I Ta \&No Ta \&No Ta >0
846 .It \&.%J Ta \&No Ta \&No Ta >0
847 .It \&.%N Ta \&No Ta \&No Ta >0
848 .It \&.%O Ta \&No Ta \&No Ta >0
849 .It \&.%P Ta \&No Ta \&No Ta >0
850 .It \&.%R Ta \&No Ta \&No Ta >0
851 .It \&.%T Ta \&No Ta \&No Ta >0
852 .It \&.%V Ta \&No Ta \&No Ta >0
853 .It \&.At Ta Yes Ta Yes Ta 1
854 .It \&.Bsx Ta Yes Ta Yes Ta n
855 .It \&.Bx Ta Yes Ta Yes Ta n
856 .It \&.Db Ta \&No Ta \&No Ta 1
857 .It \&.Em Ta Yes Ta Yes Ta n
858 .It \&.Fx Ta Yes Ta Yes Ta n
859 .It \&.Ms Ta \&No Ta Yes Ta >0
860 .It \&.No Ta Yes Ta Yes Ta 0
861 .It \&.Ns Ta Yes Ta Yes Ta 0
862 .It \&.Nx Ta Yes Ta Yes Ta n
863 .It \&.Ox Ta Yes Ta Yes Ta n
864 .It \&.Pf Ta \&No Ta Yes Ta 1
865 .It \&.Sm Ta \&No Ta \&No Ta 1
866 .It \&.Sx Ta Yes Ta Yes Ta >0
867 .It \&.Sy Ta Yes Ta Yes Ta >0
868 .It \&.Tn Ta Yes Ta Yes Ta >0
869 .It \&.Ux Ta Yes Ta Yes Ta n
870 .It \&.Dx Ta Yes Ta Yes Ta n
871 .It \&.Bt Ta \&No Ta \&No Ta 0
872 .It \&.Hf Ta \&No Ta \&No Ta n
873 .It \&.Fr Ta \&No Ta \&No Ta n
874 .It \&.Ud Ta \&No Ta \&No Ta 0
875 .It \&.Lb Ta \&No Ta \&No Ta 1
876 .It \&.Ap Ta Yes Ta Yes Ta 0
877 .It \&.Lp Ta \&No Ta \&No Ta 0
878 .It \&.Lk Ta \&No Ta Yes Ta >0
879 .It \&.Mt Ta \&No Ta Yes Ta >0
880 .It \&.Es Ta \&No Ta \&No Ta 0
881 .It \&.En Ta \&No Ta \&No Ta 0
893 The mdoc language was traditionally a
895 macro package; most existing manuals were written with mdoc syntax
896 dictated by system-dependent roff installations. This section documents
897 compatibility with these systems.
905 historically weren't always callable. Both are now correctly callable.
909 is assumed for all lists: any list may be nested and
911 lists will restart the sequence only for the sub-list.
915 syntax where column widths may be preceeded by other arguments (instead
916 of proceeded) is not supported.
921 macro only accepts a single parameter.
924 The system-name macros (
938 incorrectly by following it with a reserved character and expecting the
939 delimiter to render. This is not supported.
952 utility was written by
953 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
956 There are several ambiguous parts of mdoc.
964 as function arguments are variables.
970 as function return types are still types. Furthermore, the
972 should be removed and
974 which ostensibly follows it, should follow the same convention as
979 should formalise that only one or two arguments are acceptable: a
980 variable name and optional, preceeding type.
984 is ambiguous. It's commonly used to indicate an include file in the
987 should be used, instead.
994 makes sense. The remaining ones should be removed.
1001 macros should be deprecated.
1006 macro lacks clarity. It should be absolutely clear which title will
1007 render when formatting the manual page.
1012 should be provided for Linux (\(`a la
1018 There's no way to refer to references in
git.ckatri.com / mandoc.git / blob