1 .\" $Id: mdoc.7,v 1.139 2010/07/19 15:43:10 kristaps Exp $
3 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 .Dd $Mdocdate: July 19 2010 $
23 .Nd mdoc language reference
27 language is used to format
31 In this reference document, we describe its syntax, structure, and
33 Our reference implementation is mandoc; the
35 section describes compatibility with other troff \-mdoc implementations.
39 document follows simple rules: lines beginning with the control
42 are parsed for macros.
43 Other lines are interpreted within the scope of
45 .Bd -literal -offset indent
46 \&.Sh Macro lines change control state.
47 Other lines are interpreted within the current state.
51 documents may contain only graphable 7-bit ASCII characters, the space
52 character, and, in certain circumstances, the tab character.
59 whether in a macro or free-form text line, is ignored to the end of
61 A macro line with only a control character and comment escape,
64 Macro lines with only a control character and optionally whitespace are
66 .Ss Reserved Characters
67 Within a macro line, the following characters are reserved:
69 .Bl -tag -width Ds -offset indent -compact
94 Use of reserved characters is described in
96 For general use in macro lines, these characters must either be escaped
97 with a non-breaking space
99 or, if applicable, an appropriate escape sequence used.
100 .Ss Special Characters
101 Special characters may occur in both macro and free-form lines.
102 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.
121 Terms may be text-decorated using the
123 escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
124 (revert to previous mode):
126 .D1 \efBbold\efR \efIitalic\efP
128 A numerical representation 3, 2, or 1 (bold, italic, and Roman,
129 respectively) may be used instead.
130 A text decoration is valid within
131 the current font scope only: if a macro opens a font scope alongside
132 its own scope, such as
135 in-scope invocations of
137 are only valid within the font scope of the macro.
140 is specified outside of any font scope, such as in unenclosed, free-form
141 text, it will affect the remainder of the document.
147 which encourages semantic annotation.
148 .Ss Predefined Strings
151 also defined a set of package-specific
152 .Dq predefined strings ,
154 .Sx Special Characters ,
155 mark special output characters and strings by way of input codes.
156 Predefined strings are escaped with the slash-asterisk,
174 Whitespace consists of the space character.
175 In free-form lines, whitespace is preserved within a line; un-escaped
176 trailing spaces are stripped from input (unless in a literal context).
177 Blank free-form lines, which may include whitespace, are only permitted
178 within literal contexts.
180 In macro lines, whitespace delimits arguments and is discarded.
181 If arguments are quoted, whitespace within the quotes is retained.
183 Macro arguments may be quoted with a double-quote to group
184 space-delimited terms or to retain blocks of whitespace.
185 A quoted argument begins with a double-quote preceded by whitespace.
186 The next double-quote not pair-wise adjacent to another double-quote
187 terminates the literal, regardless of surrounding whitespace.
195 Note that any quoted term, be it argument or macro, is indiscriminately
196 considered literal text.
197 Thus, the following produces
199 .Bd -literal -offset indent
203 In free-form mode, quotes are regarded as opaque text.
205 There are several macros in
207 that require a date argument.
208 The canonical form for dates is the American format:
210 .D1 Cm Month Day , Year
214 value is an optionally zero-padded numeral.
217 value is the full month name.
220 value is the full four-digit year.
222 Reduced form dates are broken-down canonical form dates:
227 Some examples of valid dates follow:
229 .D1 "May, 2009" Pq reduced form
230 .D1 "2009" Pq reduced form
231 .D1 "May 20, 2009" Pq canonical form
233 Many macros support scaled widths for their arguments, such as
234 stipulating a two-inch list indentation with the following:
235 .Bd -literal -offset indent
239 The syntax for scaled widths is
240 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
241 where a decimal must be preceded or proceeded by at least one digit.
242 Negative numbers, while accepted, are truncated to zero.
243 The following scaling units are accepted:
245 .Bl -tag -width Ds -offset indent -compact
258 default vertical span
270 default horizontal span
275 Using anything other than
281 is necessarily non-portable across output media.
285 When composing a manual, make sure that your sentences end at the end of
287 By doing so, front-ends will be able to apply the proper amount of
288 spacing after the end of sentence (unescaped) period, exclamation mark,
289 or question mark followed by zero or more non-sentence closing
296 The proper spacing is also intelligently preserved if a sentence ends at
297 the boundary of a macro line, e.g.,
300 .D1 \&Fl T \&Ns \&Cm ascii \.
304 document consists of a document prologue followed by one or more
307 The prologue, which consists of (in order) the
312 macros, is required for every document.
314 The first section (sections are denoted by
316 must be the NAME section, consisting of at least one
321 Following that, convention dictates specifying at least the
325 sections, although this varies between manual sections.
327 The following is a well-formed skeleton
330 .Bd -literal -offset indent
336 \&.Nd a description goes here
337 \&.\e\*q The next is for sections 2, 3, & 9 only.
346 utility processes files ...
347 \&.\e\*q .Sh IMPLEMENTATION NOTES
348 \&.\e\*q The next is for sections 2, 3, & 9 only.
349 \&.\e\*q .Sh RETURN VALUES
350 \&.\e\*q The next is for sections 1, 6, 7, & 8 only.
351 \&.\e\*q .Sh ENVIRONMENT
353 \&.\e\*q The next is for sections 1 & 8 only.
354 \&.\e\*q .Sh EXIT STATUS
355 \&.\e\*q .Sh EXAMPLES
356 \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
357 \&.\e\*q .Sh DIAGNOSTICS
358 \&.\e\*q The next is for sections 2, 3, & 9 only.
360 \&.\e\*q .Sh SEE ALSO
361 \&.\e\*q .Xr foobar 1
362 \&.\e\*q .Sh STANDARDS
367 \&.\e\*q .Sh SECURITY CONSIDERATIONS
372 document are conventionally ordered as they appear above.
373 Sections should be composed as follows:
374 .Bl -ohang -offset Ds
376 The name(s) and a short description of the documented material.
377 The syntax for this as follows:
378 .Bd -literal -offset indent
382 \&.Nd a short description
387 macro(s) must precede the
396 The name of the library containing the documented material, which is
397 assumed to be a function in a section 2, 3, or 9 manual.
398 The syntax for this is as follows:
399 .Bd -literal -offset indent
406 Documents the utility invocation syntax, function call syntax, or device
409 For the first, utilities (sections 1, 6, and 8), this is
410 generally structured as follows:
411 .Bd -literal -offset indent
422 For the second, function calls (sections 2, 3, 9):
423 .Bd -literal -offset indent
424 \&.Vt extern const char *global;
427 \&.Fn foo "const char *src"
429 \&.Fn bar "const char *src"
432 And for the third, configurations (section 4):
433 .Bd -literal -offset indent
434 \&.Cd \*qit* at isa? port 0x2e\*q
435 \&.Cd \*qit* at isa? port 0x4e\*q
438 Manuals not in these sections generally don't need a
441 Some macros are displayed differently in the
443 section, particularly
453 All of these macros are output on their own line.
454 If two such dissimilar macros are pair-wise invoked (except for
460 they are separated by a vertical space, unless in the case of
465 which are always separated by vertical space.
467 When text and macros following an
469 macro starting an input line span multiple output lines,
470 all output lines but the first will be indented to align
471 with the text immediately following the
473 macro, up to the next
478 macro or the end of an enclosing block, whichever comes first.
480 This expands upon the brief, one-line description in
482 It usually contains a break-down of the options (if documenting a
484 .Bd -literal -offset indent
485 The arguments are as follows:
486 \&.Bl \-tag \-width Ds
488 Print verbose information.
492 Manuals not documenting a command won't include the above fragment.
493 .It Em IMPLEMENTATION NOTES
494 Implementation-specific notes should be kept here.
495 This is useful when implementing standard functions that may have side
496 effects or notable algorithmic implications.
498 This section is the dual of
500 which is used for commands.
501 It documents the return values of functions in sections 2, 3, and 9.
506 Documents any usages of environment variables, e.g.,
512 Documents files used.
513 It's helpful to document both the file and a short description of how
514 the file is used (created, modified, etc.).
519 Command exit status for section 1, 6, and 8 manuals.
520 This section is the dual of
522 which is used for functions.
523 Historically, this information was described in
525 a practise that is now discouraged.
531 This often contains snippets of well-formed, well-tested invocations.
532 Make doubly sure that your examples work properly!
534 Documents error conditions.
535 This is most useful in section 4 manuals.
536 Historically, this section was used in place of
538 for manuals in sections 1, 6, and 8; however, this practise is
545 Documents error handling in sections 2, 3, and 9.
550 References other manuals with related topics.
551 This section should exist for most manuals.
552 Cross-references should conventionally be ordered first by section, then
558 References any standards implemented or used.
559 If not adhering to any standards, the
561 section should be used instead.
566 The history of any manual without a
568 section should be described in this section.
570 Credits to authors, if applicable, should appear in this section.
571 Authors should generally be noted by both name and an e-mail address.
576 Explanations of common misuses and misunderstandings should be explained
579 Extant bugs should be described in this section.
580 .It Em SECURITY CONSIDERATIONS
581 Documents any security precautions that operators should consider.
584 Macros are one to three three characters in length and begin with a
587 at the beginning of the line.
588 An arbitrary amount of whitespace may sit between the control character
590 Thus, the following are equivalent:
591 .Bd -literal -offset indent
596 The syntax of a macro depends on its classification.
599 refers to macro arguments, which may be followed by zero or more
603 opens the scope of a macro; and if specified,
609 column indicates that the macro may be called subsequent to the initial
611 If a macro is not callable, then its invocation after the initial line
612 macro is interpreted as opaque text, such that
619 column indicates whether the macro may be followed by further
620 (ostensibly callable) macros.
621 If a macro is not parsable, subsequent macro invocations on the line
622 will be interpreted as opaque text.
626 column, if applicable, describes closure rules.
627 .Ss Block full-explicit
628 Multi-line scope closed by an explicit closing macro.
629 All macros contains bodies; only
632 .Bd -literal -offset indent
633 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
638 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
639 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
640 .It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
641 .It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
642 .It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
643 .It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
644 .It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
645 .It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
646 .It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
647 .It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
649 .Ss Block full-implicit
650 Multi-line scope closed by end-of-file or implicitly by another macro.
651 All macros have bodies; some
659 don't have heads; only one
664 .Bd -literal -offset indent
665 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
669 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
670 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
671 .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
672 .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
673 .It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
674 .It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh
675 .It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss
681 .Sx Block full-implicit
682 macro only when invoked as the first macro
685 section line, else it is
687 .Ss Block partial-explicit
688 Like block full-explicit, but also with single-line scope.
689 Each has at least a body and, in limited circumstances, a head
696 .Bd -literal -offset indent
697 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
699 \&.Yc \(lBtail...\(rB
701 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
702 \(lBbody...\(rB \&Yc \(lBtail...\(rB
705 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
706 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
707 .It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
708 .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
709 .It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
710 .It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
711 .It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
712 .It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
713 .It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
714 .It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
715 .It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
716 .It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
717 .It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
718 .It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
719 .It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
720 .It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
721 .It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
722 .It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
723 .It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
724 .It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
725 .It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
726 .It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
727 .It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
728 .It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
729 .It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
730 .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
732 .Ss Block partial-implicit
733 Like block full-implicit, but with single-line scope closed by
734 .Sx Reserved Characters
736 .Bd -literal -offset indent
737 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
740 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
741 .It Em Macro Ta Em Callable Ta Em Parsable
742 .It Sx \&Aq Ta Yes Ta Yes
743 .It Sx \&Bq Ta Yes Ta Yes
744 .It Sx \&Brq Ta Yes Ta Yes
745 .It Sx \&D1 Ta \&No Ta \&Yes
746 .It Sx \&Dl Ta \&No Ta Yes
747 .It Sx \&Dq Ta Yes Ta Yes
748 .It Sx \&Op Ta Yes Ta Yes
749 .It Sx \&Pq Ta Yes Ta Yes
750 .It Sx \&Ql Ta Yes Ta Yes
751 .It Sx \&Qq Ta Yes Ta Yes
752 .It Sx \&Sq Ta Yes Ta Yes
753 .It Sx \&Vt Ta Yes Ta Yes
759 .Sx Block partial-implicit
760 only when invoked as the first macro
763 section line, else it is
767 .Sx Reserved Characters ,
768 end of line, fixed argument lengths, and/or subsequent macros.
769 In-line macros have only text children.
770 If a number (or inequality) of arguments is
772 then the macro accepts an arbitrary number of arguments.
773 .Bd -literal -offset indent
774 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
776 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
778 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
781 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
782 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
783 .It Sx \&%A Ta \&No Ta \&No Ta >0
784 .It Sx \&%B Ta \&No Ta \&No Ta >0
785 .It Sx \&%C Ta \&No Ta \&No Ta >0
786 .It Sx \&%D Ta \&No Ta \&No Ta >0
787 .It Sx \&%I Ta \&No Ta \&No Ta >0
788 .It Sx \&%J Ta \&No Ta \&No Ta >0
789 .It Sx \&%N Ta \&No Ta \&No Ta >0
790 .It Sx \&%O Ta \&No Ta \&No Ta >0
791 .It Sx \&%P Ta \&No Ta \&No Ta >0
792 .It Sx \&%Q Ta \&No Ta \&No Ta >0
793 .It Sx \&%R Ta \&No Ta \&No Ta >0
794 .It Sx \&%T Ta \&No Ta \&No Ta >0
795 .It Sx \&%U Ta \&No Ta \&No Ta >0
796 .It Sx \&%V Ta \&No Ta \&No Ta >0
797 .It Sx \&Ad Ta Yes Ta Yes Ta n
798 .It Sx \&An Ta Yes Ta Yes Ta n
799 .It Sx \&Ap Ta Yes Ta Yes Ta 0
800 .It Sx \&Ar Ta Yes Ta Yes Ta n
801 .It Sx \&At Ta Yes Ta Yes Ta 1
802 .It Sx \&Bsx Ta Yes Ta Yes Ta n
803 .It Sx \&Bt Ta \&No Ta \&No Ta 0
804 .It Sx \&Bx Ta Yes Ta Yes Ta n
805 .It Sx \&Cd Ta Yes Ta Yes Ta >0
806 .It Sx \&Cm Ta Yes Ta Yes Ta n
807 .It Sx \&Db Ta \&No Ta \&No Ta 1
808 .It Sx \&Dd Ta \&No Ta \&No Ta >0
809 .It Sx \&Dt Ta \&No Ta \&No Ta n
810 .It Sx \&Dv Ta Yes Ta Yes Ta n
811 .It Sx \&Dx Ta Yes Ta Yes Ta n
812 .It Sx \&Em Ta Yes Ta Yes Ta >0
813 .It Sx \&En Ta \&No Ta \&No Ta 0
814 .It Sx \&Er Ta Yes Ta Yes Ta >0
815 .It Sx \&Es Ta \&No Ta \&No Ta 0
816 .It Sx \&Ev Ta Yes Ta Yes Ta n
817 .It Sx \&Ex Ta \&No Ta \&No Ta n
818 .It Sx \&Fa Ta Yes Ta Yes Ta n
819 .It Sx \&Fd Ta \&No Ta \&No Ta >0
820 .It Sx \&Fl Ta Yes Ta Yes Ta n
821 .It Sx \&Fn Ta Yes Ta Yes Ta >0
822 .It Sx \&Fr Ta \&No Ta \&No Ta n
823 .It Sx \&Ft Ta Yes Ta Yes Ta n
824 .It Sx \&Fx Ta Yes Ta Yes Ta n
825 .It Sx \&Hf Ta \&No Ta \&No Ta n
826 .It Sx \&Ic Ta Yes Ta Yes Ta >0
827 .It Sx \&In Ta \&No Ta \&No Ta n
828 .It Sx \&Lb Ta \&No Ta \&No Ta 1
829 .It Sx \&Li Ta Yes Ta Yes Ta n
830 .It Sx \&Lk Ta Yes Ta Yes Ta n
831 .It Sx \&Lp Ta \&No Ta \&No Ta 0
832 .It Sx \&Ms Ta Yes Ta Yes Ta >0
833 .It Sx \&Mt Ta Yes Ta Yes Ta >0
834 .It Sx \&Nm Ta Yes Ta Yes Ta n
835 .It Sx \&No Ta Yes Ta Yes Ta 0
836 .It Sx \&Ns Ta Yes Ta Yes Ta 0
837 .It Sx \&Nx Ta Yes Ta Yes Ta n
838 .It Sx \&Os Ta \&No Ta \&No Ta n
839 .It Sx \&Ot Ta \&No Ta \&No Ta n
840 .It Sx \&Ox Ta Yes Ta Yes Ta n
841 .It Sx \&Pa Ta Yes Ta Yes Ta n
842 .It Sx \&Pf Ta Yes Ta Yes Ta 1
843 .It Sx \&Pp Ta \&No Ta \&No Ta 0
844 .It Sx \&Rv Ta \&No Ta \&No Ta n
845 .It Sx \&Sm Ta \&No Ta \&No Ta 1
846 .It Sx \&St Ta \&No Ta Yes Ta 1
847 .It Sx \&Sx Ta Yes Ta Yes Ta >0
848 .It Sx \&Sy Ta Yes Ta Yes Ta >0
849 .It Sx \&Tn Ta Yes Ta Yes Ta >0
850 .It Sx \&Ud Ta \&No Ta \&No Ta 0
851 .It Sx \&Ux Ta Yes Ta Yes Ta n
852 .It Sx \&Va Ta Yes Ta Yes Ta n
853 .It Sx \&Vt Ta Yes Ta Yes Ta >0
854 .It Sx \&Xr Ta Yes Ta Yes Ta >0
855 .It Sx \&br Ta \&No Ta \&No Ta 0
856 .It Sx \&sp Ta \&No Ta \&No Ta 1
859 This section is a canonical reference of all macros, arranged
861 For the scoping of individual macros, see
867 Multiple authors should each be accorded their own
870 Author names should be ordered with full or abbreviated forename(s)
871 first, then full surname.
876 This macro may also be used in a non-bibliographic context when
877 referring to book titles.
879 Publication city or location of an
884 this macro is not implemented in
887 Publication date of an
890 This should follow the reduced or canonical form syntax described in
893 Publisher or issuer name of an
901 Issue number (usually for journals) of an
905 Optional information of an
909 Book or journal page number of an
913 Institutional author (school, government, etc.) of an
916 Multiple institutional authors should each be accorded their own
920 Technical report name of an
927 This macro may also be used in a non-bibliographical context when
928 referring to article titles.
930 URI of reference document.
939 Does not have any tail arguments.
941 Address construct: usually in the context of an computational address in
942 memory, not a physical (post) address.
949 This macro may alternatively accepts the following arguments, although
950 these may not be specified along with a parameter:
951 .Bl -tag -width 12n -offset indent
953 Renders a line break before each author listing.
959 In the AUTHORS section, the default is not to split the first author
960 listing, but all subsequent author listings, whether or not they're
961 interspersed by other macros or text, are split.
964 will cause the first listing also to be split.
965 If not in the AUTHORS section, the default is not to split.
969 .D1 \&.An J. D. Ullman .
976 are re-set when entering the AUTHORS section, so if one specifies
978 in the general document body, it must be re-specified in the AUTHORS
981 Begins a block enclosed by angled brackets.
982 Does not have any head arguments.
985 .D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
990 Inserts an apostrophe without any surrounding whitespace.
991 This is generally used as a grammatical device when referring to the verb
993 .Bd -literal -offset indent
997 Encloses its arguments in angled brackets.
1000 .D1 \&.Fl -key= \&Ns \&Aq \&Ar val
1003 this macro is often abused for rendering URIs, which should instead use
1007 or to note pre-processor
1009 statements, which should use
1016 If an argument is not provided, the string
1018 is used as a default.
1021 .D1 \&.Fl o \&Ns \&Ar file1
1023 .D1 \&.Ar arg1 , arg2 .
1025 Formats an AT&T version.
1026 Accepts at most one parameter:
1027 .Bl -tag -width 12n -offset indent
1036 Note that these parameters do not begin with a hyphen.
1055 Does not have any tail arguments.
1057 Begins a display block.
1058 Its syntax is as follows:
1059 .Bd -ragged -offset indent
1062 .Op Fl offset Ar width
1066 A display is collection of macros or text which may be collectively
1067 offset or justified in a manner different from that
1068 of the enclosing context.
1069 By default, the block is preceded by a vertical space.
1071 Each display is associated with a type, which must be one of the
1072 following arguments:
1073 .Bl -tag -width 12n -offset indent
1075 Only left-justify the block.
1077 Do not justify the block at all.
1079 Left- and right-justify the block.
1084 Centre-justify each line.
1087 The type must be provided first.
1088 Secondary arguments are as follows:
1089 .Bl -tag -width 12n -offset indent
1090 .It Fl offset Ar val
1091 Offset by the value of
1093 which is interpreted as one of the following, specified in order:
1096 As one of the pre-defined strings
1098 the width of standard indentation;
1103 which has no effect;
1105 which justifies to the right margin; and
1107 which aligns around an imagined centre axis.
1109 As a precalculated width for a named macro.
1110 The most popular is the imaginary macro
1115 As a scaling unit following the syntax described in
1116 .Sx Scaling Widths .
1118 As the calculated string length of the opaque string.
1121 If not provided an argument, it will be ignored.
1123 Do not assert a vertical space before the block.
1127 .Bd -literal -offset indent
1128 \&.Bd \-unfilled \-offset two-indent \-compact
1138 Change the font mode for a scoped block of text.
1139 Its syntax is as follows:
1140 .Bd -ragged -offset indent
1143 .Fl emphasis | literal | symbolic |
1144 .Cm \&Em | \&Li | \&Sy
1152 argument are equivalent, as are
1160 Without an argument, this macro does nothing.
1161 The font mode continues until broken by a new font mode in a nested
1172 Begins a collection of macros or text not breaking the line.
1173 Its syntax is as follows:
1175 .D1 Pf \. Sx \&Bk Fl words
1177 Subsequent arguments are ignored.
1180 argument is required.
1182 Each line within a keep block is kept intact, so the following example
1183 will not break within each
1186 .Bd -literal -offset indent
1189 \&.Op Fl o Ar output
1193 Be careful in using over-long lines within a keep block!
1194 Doing so will clobber the right margin.
1196 Begins a list composed of one or more list entries.
1197 Its syntax is as follows:
1198 .Bd -ragged -offset indent
1202 .Op Fl offset Ar val
1207 A list is associated with a type, which is a required argument.
1210 defined per-type as accepting a literal or
1214 also accepting a literal or
1216 value setting the list's global offset; and
1218 suppressing the default vertical space printed before each list entry.
1219 A list entry is specified by the
1221 macro, which consists of a head and optional body (depending on the list
1223 A list must specify one of the following list types:
1224 .Bl -tag -width 12n -offset indent
1226 A list offset by a bullet.
1227 The head of list entries must be empty.
1228 List entry bodies are positioned after the bullet.
1231 argument varies the width of list bodies' left-margins.
1236 argument has no effect.
1237 The number of columns is specified as parameters to the
1240 These dictate the width of columns either as
1243 If the initial macro of a
1249 context spanning each line is implied until an
1251 line macro is encountered, at which point list bodies are interpreted as
1256 A list offset by a dash (hyphen).
1257 The head of list entries must be empty.
1258 List entry bodies are positioned past the dash.
1261 argument varies the width of list bodies' left-margins.
1265 but with additional formatting to the head.
1268 argument varies the width of list bodies' left-margins.
1270 An enumerated list offset by the enumeration from 1.
1271 The head of list entries must be empty.
1272 List entry bodies are positioned after the enumeration.
1275 argument varies the width of list bodies' left-margins.
1279 but instead of list bodies positioned after the head, they trail the
1283 argument varies the width of list bodies' left-margins.
1288 List bodies follow the list head.
1291 argument is ignored.
1293 This produces blocks of text.
1294 The head of list entries must be empty.
1297 argument is ignored.
1299 List bodies are positioned on the line following the head.
1302 argument is ignored.
1304 A list offset by list entry heads.
1305 List entry bodies are positioned after the head as specified by the
1313 Begins a block enclosed by square brackets.
1314 Does not have any head arguments.
1317 .Bd -literal -offset indent
1325 Encloses its arguments in square brackets.
1328 .D1 \&.Bq 1 , \&Dv BUFSIZ
1331 this macro is sometimes abused to emulate optional arguments for
1332 commands; the correct macros to use for this purpose are
1344 Does not have any tail arguments.
1346 Begins a block enclosed by curly braces.
1347 Does not have any head arguments.
1350 .Bd -literal -offset indent
1358 Encloses its arguments in curly braces.
1361 .D1 \&.Brq 1 , ... , \&Va n
1366 Format the BSD/OS version provided as an argument, or a default value if
1367 no argument is provided.
1384 .Dq is currently in beta test.
1386 Format the BSD version provided as an argument, or a default value if no
1387 argument is provided.
1403 Configuration declaration.
1404 This denotes strings accepted by
1408 .D1 \&.Cd device le0 at scode?
1411 this macro is commonly abused by using quoted literals to retain
1412 whitespace and align consecutive
1415 This practise is discouraged.
1418 Useful when specifying configuration options or keys.
1421 .D1 \&.Cm ControlPath
1422 .D1 \&.Cm ControlMaster
1427 One-line indented display.
1428 This is formatted by the default rules and is useful for simple indented
1430 It is followed by a newline.
1433 .D1 \&.D1 \&Fl abcdefgh
1440 Start a debugging context.
1441 This macro is parsed, but generally ignored.
1442 Its syntax is as follows:
1444 .D1 Pf \. Sx \&Db Cm on | off
1449 Does not have any tail arguments.
1452 This is the mandatory first macro of any
1455 Its syntax is as follows:
1457 .D1 Pf \. Sx \&Dd Cm date
1463 which signifies the current manual revision date dictated by
1465 or instead a valid canonical date as specified by
1467 If a date does not conform, the current date is used instead.
1470 .D1 \&.Dd $\&Mdocdate$
1471 .D1 \&.Dd $\&Mdocdate: July 21 2007$
1472 .D1 \&.Dd July 21, 2007
1479 One-line intended display.
1480 This is formatted as literal text and is useful for commands and
1482 It is followed by a newline.
1485 .D1 \&.Dl % mandoc mdoc.7 | less
1492 Begins a block enclosed by double quotes.
1493 Does not have any head arguments.
1496 .D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot
1501 Encloses its arguments in
1506 .Bd -literal -offset indent -compact
1507 \&.Dq April is the cruellest month
1518 This is the mandatory second macro of any
1521 Its syntax is as follows:
1522 .Bd -ragged -offset indent
1528 .Op Cm volume | arch
1533 Its arguments are as follows:
1534 .Bl -tag -width Ds -offset Ds
1536 The document's title (name), defaulting to
1539 It should be capitalised.
1550 .Pq Perl libraries ,
1560 .Pq system utilities ,
1562 .Pq kernel functions ,
1564 .Pq X Window System ,
1566 .Pq X Window System ,
1576 It should correspond to the manual's filename suffix and defaults to
1580 This overrides the volume inferred from
1582 This field is optional, and if specified, must be one of
1584 .Pq users' supplementary documents ,
1586 .Pq programmers' supplementary documents ,
1588 .Pq administrators' supplementary documents ,
1590 .Pq system managers' manuals ,
1592 .Pq users' reference manuals ,
1594 .Pq programmers' reference manuals ,
1596 .Pq kernel manuals ,
1607 .Pq contributed manuals .
1609 This specifies a specific relevant architecture.
1612 is not provided, it may be used in its place, else it may be used
1614 It, too, is optional.
1649 .D1 \&.Dt FOO 9 i386
1656 Defined variables such as preprocessor constants.
1660 .D1 \&.Dv STDOUT_FILENO
1665 Format the DragonFly BSD version provided as an argument, or a default
1666 value if no argument is provided.
1682 Close a scope started by
1684 Its syntax is as follows:
1686 .D1 Pf \. Sx \&Ec Op Cm TERM
1690 argument is used as the enclosure tail, for example, specifying \e(rq
1694 End a display context started by
1697 Ends a font mode context started by
1700 Ends a keep context started by
1703 Ends a list context started by
1711 Denotes text that should be emphasised.
1712 Note that this is a presentation term and should not be used for
1713 stylistically decorating technical terms.
1725 This macro is obsolete and not implemented.
1727 An arbitrary enclosure.
1728 Its syntax is as follows:
1730 .D1 Pf \. Sx \&Eo Op Cm TERM
1734 argument is used as the enclosure head, for example, specifying \e(lq
1738 Display error constants.
1747 This macro is obsolete and not implemented.
1749 Environmental variables such as those specified in
1756 Inserts text regarding a utility's exit value.
1757 This macro must consist of the
1759 argument followed by an optional
1763 is not provided, the document's name as stipulated in
1771 Its syntax is as follows:
1772 .Bd -ragged -offset indent
1778 This may be invoked for names with or without the corresponding type.
1779 It is also used to specify the field name of a structure.
1782 macro is used in the
1786 section when documenting multi-line function prototypes.
1787 If invoked with multiple arguments, the arguments are separated by a
1789 Furthermore, if the following macro is another
1791 the last argument will also have a trailing comma.
1794 .D1 \&.Fa \(dqconst char *p\(dq
1795 .D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
1801 Ends a function context started by
1804 Historically used to document include files.
1805 This usage has been deprecated in favour of
1807 Do not use this macro.
1810 .Sx MANUAL STRUCTURE
1815 Used when listing arguments to command-line utilities.
1816 Prints a fixed-width hyphen
1818 directly followed by each argument.
1819 If no arguments are provided, a hyphen is printed followed by a space.
1820 If the argument is a macro, a hyphen is prefixed to the subsequent macro
1827 .D1 \&.Op \&Fl o \&Ns \&Ar file
1833 Its syntax is as follows:
1834 .Bd -ragged -offset indent
1838 .Op Oo Cm argtype Oc Cm argname
1841 Function arguments are surrounded in parenthesis and
1842 are delimited by commas.
1843 If no arguments are specified, blank parenthesis are output.
1846 .D1 \&.Fn "int funcname" "int arg0" "int arg1"
1847 .D1 \&.Fn funcname "int arg0"
1848 .D1 \&.Fn funcname arg0
1849 .Bd -literal -offset indent -compact
1855 .Sx MANUAL STRUCTURE
1859 Begin a function block.
1860 This is a multi-line version of
1862 Its syntax is as follows:
1864 .D1 Pf \. Sx \&Fo Cm funcname
1866 Invocations usually occur in the following context:
1867 .Bd -ragged -offset indent
1868 .Pf \. Sx \&Ft Cm functype
1870 .Pf \. Sx \&Fo Cm funcname
1872 .Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname
1884 .Sx MANUAL STRUCTURE ,
1891 Its syntax is as follows:
1893 .D1 Pf \. Sx \&Ft Cm functype
1897 .Bd -literal -offset indent -compact
1903 .Sx MANUAL STRUCTURE ,
1908 Format the FreeBSD version provided as an argument, or a default value
1909 if no argument is provided.
1925 This macro is obsolete and not implemented.
1927 Designate an internal or interactive command.
1930 but used for instructions rather than values.
1937 .Sx \&Bd No Fl literal
1940 is preferred for displaying code; the
1942 macro is used when referring to specific instructions.
1949 section (only if invoked as the line macro), the first argument is
1952 the arguments is enclosed in angled braces.
1958 .Sx MANUAL STRUCTURE .
1961 The syntax of this macro depends on the list type.
1970 have the following syntax:
1972 .D1 Pf \. Sx \&It Cm args
1981 have the following syntax:
1985 with subsequent lines interpreted within the scope of the
1987 until either a closing
1994 list has the following syntax:
1996 .D1 Pf \. Sx \&It Op Cm args
1998 Subsequent lines are interpreted as with
2001 The line arguments correspond to the list's left-hand side; body
2002 arguments correspond to the list's contents.
2006 list is the most complicated.
2007 Its syntax is as follows:
2009 .D1 Pf \. Sx \&It Op Cm args
2013 are phrases, a mix of macros and text corresponding to a line column,
2014 delimited by tabs or the special
2017 Lines subsequent the
2019 are interpreted within the scope of the last phrase.
2020 Calling the pseudo-macro
2022 will open a new phrase scope (this must occur on a macro line to be
2023 interpreted as a macro).
2024 Note that the tab phrase delimiter may only be used within the
2027 Subsequent this, only the
2029 pseudo-macro may be used to delimit phrases.
2030 Furthermore, note that quoted sections propagate over tab-delimited
2035 .D1 .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
2037 will preserve the semicolon whitespace except for the last.
2043 The syntax is as follows:
2045 .D1 Pf \. Sx \&Lb Cm library
2049 parameter may be a system library, such as
2053 in which case a small library description is printed next to the linker
2054 invocation; or a custom library, in which case the library name is
2056 This is most commonly used in the
2058 section as described in
2059 .Sx MANUAL STRUCTURE .
2065 Denotes text that should be in a literal font mode.
2066 Note that this is a presentation term and should not be used for
2067 stylistically decorating technical terms.
2076 Its syntax is as follows:
2078 .D1 Pf \. Sx \&Lk Cm uri Op Cm name
2081 .D1 \&.Lk http://bsd.lv "The BSD.lv Project"
2082 .D1 \&.Lk http://bsd.lv
2090 Display a mathematical symbol.
2099 Its syntax is as follows:
2101 .D1 Pf \. Sx \&Mt Cm address
2104 .D1 \&.Mt discuss@manpages.bsd.lv
2106 A one-line description of the manual's content.
2107 This may only be invoked in the
2109 section subsequent the
2114 .D1 \&.Sx \&Nd mdoc language reference
2115 .D1 \&.Sx \&Nd format and display UNIX manuals
2119 macro technically accepts child macros and terminates with a subsequent
2122 Do not assume this behaviour: some
2124 database generators are not smart enough to parse more than the line
2125 arguments and will display macros verbatim.
2130 The name of the manual page, or \(em in particular in section 1, 6,
2131 and 8 pages \(em of an additional command or feature documented in
2133 When first invoked, the
2135 macro expects a single argument, the name of the manual page.
2136 Usually, the first invocation happens in the
2138 section of the page.
2139 The specified name will be remembered and used whenever the macro is
2140 called again without arguments later in the page.
2144 .Sx Block full-implicit
2145 semantics when invoked as the first macro on an input line in the
2147 section; otherwise, it uses ordinary
2152 .Bd -literal -offset indent
2161 of section 2, 3 and 9 manual pages, use the
2165 to mark up the name of the manual page.
2169 macro used to terminate prior macro contexts.
2172 .D1 \&.Sx \&Fl ab \&No cd \&Fl ef
2175 Following invocation, text is interpreted as free-form text until a
2176 macro is encountered.
2179 .D1 \&.Fl o \&Ns \&Ar output
2186 Format the NetBSD version provided as an argument, or a default value if
2187 no argument is provided.
2207 Multi-line version of
2211 .Bd -literal -offset indent -compact
2213 \&.Op Fl flag Ns Ar value
2217 Command-line option.
2218 Used when listing options to command-line utilities.
2219 Prints the argument(s) in brackets.
2222 .D1 \&.Op \&Fl a \&Ar b
2223 .D1 \&.Op \&Ar a | b
2228 Document operating system version.
2229 This is the mandatory third macro of
2233 Its syntax is as follows:
2235 .D1 Pf \. Sx \&Os Op Cm system
2239 parameter specifies the relevant operating system or environment.
2240 Left unspecified, it defaults to the local operating system version.
2241 This is the suggested form.
2245 .D1 \&.Os KTH/CSC/TCS
2256 this macro has been deprecated.
2258 Format the OpenBSD version provided as an argument, or a default value
2259 if no argument is provided.
2278 .D1 \&.Pa /usr/bin/mandoc
2279 .D1 \&.Pa /usr/share/man/man7/mdoc.7
2284 Close parenthesised context opened by
2289 between its arguments.
2290 Its syntax is as follows:
2292 .D1 Pf \. \&Pf Cm prefix suffix
2296 argument may be a macro.
2299 .D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix
2301 Multi-line version of
2305 This will assert vertical space between prior and subsequent macros
2308 Parenthesised enclosure.
2313 Close quoted context opened by
2316 Format a single-quoted literal.
2322 Multi-line version of
2325 Encloses its arguments in
2340 Does not have any tail arguments.
2342 Begins a bibliographic
2345 Does not have any head arguments.
2346 The block macro may only contain
2362 child macros (at least one must be specified).
2365 .Bd -literal -offset indent -compact
2367 \&.%A J. E. Hopcroft
2369 \&.%B Introduction to Automata Theory, Languages, and Computation
2370 \&.%I Addison-Wesley
2371 \&.%C Reading, Massachusettes
2378 block is used within a SEE ALSO section, a vertical space is asserted
2379 before the rendered output, else the block continues on the current
2382 Inserts text regarding a function call's return value.
2383 This macro must consist of the
2385 argument followed by an optional
2389 is not provided, the document's name as stipulated by the first
2396 Close single-quoted context opened by
2399 Begin a new section.
2400 For a list of conventional manual sections, see
2401 .Sx MANUAL STRUCTURE .
2402 These sections should be used unless it's absolutely necessary that
2403 custom sections be used.
2405 Section names should be unique so that they may be keyed by
2414 Switches the spacing mode for output generated from macros.
2415 Its syntax is as follows:
2417 .D1 Pf \. Sx \&Sm Cm on | off
2419 By default, spacing is
2423 no white space is inserted between macro arguments and between the
2424 output generated from adjacent macros, but free-form text lines
2425 still get normal spacing between words and sentences.
2427 Multi-line version of
2430 Encloses its arguments in
2440 Begin a new sub-section.
2443 there's no convention for sub-sections.
2444 Conventional sections, as described in
2445 .Sx MANUAL STRUCTURE ,
2446 rarely have sub-sections.
2448 Sub-section names should be unique so that they may be keyed by
2457 Replace an abbreviation for a standard with the full form.
2458 The following standards are recognised:
2460 .Bl -tag -width "-p1003.1g-2000X" -compact
2554 Reference a section or sub-section.
2555 The referenced section or sub-section name must be identical to the
2556 enclosed argument, including whitespace.
2559 .D1 \&.Sx MANUAL STRUCTURE
2561 Format enclosed arguments in symbolic
2563 Note that this is a presentation term and should not be used for
2564 stylistically decorating technical terms.
2578 .Dq currently under development.
2580 Format the UNIX name.
2581 Accepts no argument.
2600 .D1 \&.Va const char *bar ;
2603 This is also used for indicating global variables in the
2605 section, in which case a variable name is also specified.
2606 Note that it accepts
2607 .Sx Block partial-implicit
2608 syntax when invoked as the first macro in the
2610 section, else it accepts ordinary
2614 Note that this should not be confused with
2616 which is used for function return types.
2619 .D1 \&.Vt unsigned char
2620 .D1 \&.Vt extern const char * const sys_signame[] \&;
2623 .Sx MANUAL STRUCTURE
2627 Close a scope opened by
2630 Open an extension scope.
2631 This macro originally existed to extend the 9-argument limit of troff;
2632 since this limit has been lifted, the macro has been deprecated.
2634 Link to another manual
2635 .Pq Qq cross-reference .
2636 Its syntax is as follows:
2638 .D1 Pf \. Sx \&Xr Cm name section
2644 are the name and section of the linked manual.
2647 is followed by non-punctuation, an
2649 is inserted into the token stream.
2650 This behaviour is for compatibility with
2655 .D1 \&.Xr mandoc 1 \&;
2656 .D1 \&.Xr mandoc 1 \&Ns s behaviour
2660 This section documents compatibility between mandoc and other other
2661 troff implementations, at this time limited to GNU troff
2665 refers to groff versions before the
2668 .Pq somewhere between 1.15 and 1.19 .
2670 Heirloom troff, the other significant troff implementation accepting
2671 \-mdoc, is similar to historic groff.
2675 The \es (font size), \em (font colour), and \eM (font filling colour)
2676 font decoration escapes are all discarded in mandoc.
2678 Old groff fails to assert a newline before
2679 .Sx \&Bd Fl ragged compact .
2681 groff behaves inconsistently when encountering
2685 regarding spacing between arguments.
2686 In mandoc, this is not the case: each argument is consistently followed
2687 by a single space and the trailing
2689 suppresses prior spacing.
2691 groff behaves inconsistently when encountering
2697 at times newline(s) are suppressed depending on whether a prior
2700 In mandoc, this is not the case.
2705 for the normalised behaviour.
2707 Historic groff does not break before an
2709 when not invoked as the line macro in the
2713 Historic groff formats the
2715 badly: trailing arguments are trashed and
2717 is not specially treated.
2719 groff does not accept the
2721 pseudo-macro as a line macro.
2726 is no longer accepted.
2730 macro does not format its arguments when used in the FILES section under
2734 Historic groff does not print a dash for empty
2737 mandoc and newer groff implementations do.
2739 groff behaves irregularly when specifying
2742 within line-macro scopes.
2743 mandoc follows a consistent system.
2745 In mandoc, negative scaling units are truncated to zero; groff would
2746 move to prior lines.
2749 scaling unit, while accepted, is rendered as the default unit.
2751 In quoted literals, groff allowed pair-wise double-quotes to produce a
2752 standalone double-quote in formatted output.
2753 This idiosyncratic behaviour is not applicable in mandoc.
2757 .Fl offset Ar center
2760 are disregarded in mandoc.
2761 Furthermore, troff specifies a
2763 argument that is not supported in mandoc.
2764 Lastly, since text is not right-justified in mandoc (or even groff),
2773 Historic groff has many un-callable macros.
2774 Most of these (excluding some block-level macros) are now callable.
2780 but has been a proper delimiter since then.
2783 is assumed for all lists (it wasn't in historic groff): any list may be
2786 lists will restart the sequence only for the sub-list.
2790 incorrectly by following it with a reserved character and expecting the
2791 delimiter to render.
2792 This is not supported in mandoc.
2800 macros were stipulated only to occur in certain manual sections.
2801 mandoc does not have these restrictions.
2803 Newer groff and mandoc print
2805 prior to unknown arguments of
2807 older groff did nothing.
2815 reference was written by
2816 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
git.ckatri.com / mandoc.git / blob