1 .\" $Id: mdoc.7,v 1.207 2011/08/30 13:14:01 kristaps Exp $
3 .\" Copyright (c) 2009, 2010, 2011 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: August 30 2011 $
23 .Nd mdoc language reference
27 language is used to format
31 This reference document describes its syntax, structure, and
33 The reference implementation for
39 section describes compatibility with other implementations.
43 document follows simple rules: lines beginning with the control
46 are parsed for macros.
47 Lines not beginning with the control character are
48 interpreted within the scope of prior macros:
49 .Bd -literal -offset indent
50 \&.Sh Macro lines change control state.
51 Text lines are interpreted within the current state.
55 documents may contain only graphable 7-bit ASCII characters, the space
56 character, and, in certain circumstances, the tab character.
57 The back-space character
59 indicates the start of an escape sequence for
61 .Sx Predefined Strings ,
63 .Sx Special Characters .
65 Text following an escaped double-quote
67 whether in a macro or text line, is ignored to the end of
69 A macro line beginning with a control character and comment escape
73 macro lines with only a control character and optional trailing
78 .Bd -literal -offset indent -compact
79 \&.\e\(dq This is a comment line.
80 \&.\e\(dq The next line is ignored:
82 \&.Em Emphasis \e\(dq This is also a comment.
84 .Ss Special Characters
85 Special characters are used to encode special glyphs and are rendered
86 differently across output media.
87 They may occur in both macro and text lines.
88 Sequences begin with the escape character
90 followed by either an open-parenthesis
92 for two-character sequences; an open-bracket
94 for n-character sequences (terminated at a close-bracket
96 or a single one character sequence.
99 .Bl -tag -width Ds -offset indent -compact
101 Two-letter em dash escape.
103 One-letter backslash escape.
110 Terms may be text-decorated using the
112 escape followed by an indicator: B (bold), I (italic), R (regular), or P
113 (revert to previous mode).
114 A numerical representation 3, 2, or 1 (bold, italic, and regular,
115 respectively) may be used instead.
116 If a macro opens a font scope after calling
122 mode will be restored upon exiting the
127 .Bl -tag -width Ds -offset indent -compact
129 Write in bold, then switch to regular font mode.
130 .It Li \efIitalic\efP
131 Write in italic, then return to previous font mode.
138 which encourages semantic annotation.
139 .Ss Predefined Strings
140 Predefined strings, like
141 .Sx Special Characters ,
142 mark special output glyphs.
143 Predefined strings are escaped with the slash-asterisk,
153 .Bl -tag -width Ds -offset indent -compact
155 Two-letter ampersand predefined string.
157 One-letter double-quote predefined string.
160 These strings are set using
164 consists of several pre-set escapes listed in
167 Whitespace consists of the space character.
168 In text lines, whitespace is preserved within a line.
169 In macro lines, whitespace delimits arguments and is discarded.
171 Unescaped trailing spaces are stripped from text line input unless in a
173 In general, trailing whitespace on any input line is discouraged for
174 reasons of portability.
175 In the rare case that a blank character is needed at the end of an
176 input line, it may be forced by
179 In general, space characters can be rendered as literal
180 characters by using non-breaking space escapes or
183 Blank text lines, which may include whitespace, are only permitted
184 within literal contexts.
185 If the first character of a text line is a space, that line is printed
186 with a leading newline.
188 Macro arguments may be quoted with double-quotes to so that the
189 enclosed text is one literal term.
190 Quoted text, even if whitespace or if it would cause a macro invocation
191 when unquoted, is considered literal text.
193 A quoted argument begins with a double-quote preceded by whitespace.
194 The next double-quote not pairwise adjacent to another double-quote
195 terminates the literal, regardless of surrounding whitespace.
198 .Bl -tag -width Ds -offset indent -compact
199 .It Li .Fn strlen \(dqconst char *s\(dq
202 into one function argument.
208 would be considered separate arguments.
210 .It Li .Op \(dqFl a\(dq
213 as literal text instead of a flag macro.
214 .Pq Aee Sx \&Op , \&Fl .
217 Many macros support scaled widths for their arguments.
218 The syntax for a scaled width is
219 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
220 where a decimal must be preceded or proceeded by at least one digit.
221 Negative numbers, while accepted, are truncated to zero.
223 The following scaling units are accepted:
225 .Bl -tag -width Ds -offset indent -compact
238 default vertical span
250 default horizontal span
255 Using anything other than
261 is necessarily non-portable across output media.
266 .Bl -tag -width Ds -offset indent -compact
267 .It Li \&.Bl -tag -width 2i
268 two-inch tagged list indentation
275 Sentences should terminate at the end of an input line.
276 By doing this, a formatter will be able to apply the proper amount of
277 spacing after the end of sentence (unescaped) period, exclamation mark,
278 or question mark followed by zero or more non-sentence closing
287 The proper spacing is also intelligently preserved if a sentence ends at
288 the boundary of a macro line.
291 .Bd -literal -offset indent -compact
292 Do not end sentences mid-line like this. Instead,
293 end a sentence like this.
294 A macro would end like this:
300 document consists of a document prologue followed by one or more
303 The prologue, which consists of the
308 macros in that order, is required for every document.
310 The first section (sections are denoted by
312 must be the NAME section, consisting of at least one
317 Following that, convention dictates specifying at least the
321 sections, although this varies between manual sections.
323 The following is a well-formed skeleton
327 .Bd -literal -offset indent
329 \&.Dt PROGNAME section
333 \&.Nd one line about what it does
334 \&.\e\(dq .Sh LIBRARY
335 \&.\e\(dq For sections 2, 3, & 9 only.
336 \&.\e\(dq Not used in OpenBSD.
344 utility processes files ...
345 \&.\e\(dq .Sh IMPLEMENTATION NOTES
346 \&.\e\(dq Not used in OpenBSD.
347 \&.\e\(dq .Sh RETURN VALUES
348 \&.\e\(dq For sections 2, 3, & 9 only.
349 \&.\e\(dq .Sh ENVIRONMENT
350 \&.\e\(dq For sections 1, 6, 7, & 8 only.
352 \&.\e\(dq .Sh EXIT STATUS
353 \&.\e\(dq For sections 1, 6, & 8 only.
354 \&.\e\(dq .Sh EXAMPLES
355 \&.\e\(dq .Sh DIAGNOSTICS
356 \&.\e\(dq For sections 1, 4, 6, 7, & 8 only.
358 \&.\e\(dq For sections 2, 3, & 9 only.
359 \&.\e\(dq .Sh SEE ALSO
360 \&.\e\(dq .Xr foobar 1
361 \&.\e\(dq .Sh STANDARDS
362 \&.\e\(dq .Sh HISTORY
363 \&.\e\(dq .Sh AUTHORS
364 \&.\e\(dq .Sh CAVEATS
366 \&.\e\(dq .Sh SECURITY CONSIDERATIONS
367 \&.\e\(dq Not used in OpenBSD.
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 one line description of the documented material.
377 The syntax for this as follows:
378 .Bd -literal -offset indent
382 \&.Nd a one line description
387 names should be separated by commas.
391 macro(s) must precede the
400 The name of the library containing the documented material, which is
401 assumed to be a function in a section 2, 3, or 9 manual.
402 The syntax for this is as follows:
403 .Bd -literal -offset indent
410 Documents the utility invocation syntax, function call syntax, or device
413 For the first, utilities (sections 1, 6, and 8), this is
414 generally structured as follows:
415 .Bd -literal -offset indent
426 Commands should be ordered alphabetically.
428 For the second, function calls (sections 2, 3, 9):
429 .Bd -literal -offset indent
431 \&.Vt extern const char *global;
433 \&.Fn foo "const char *src"
435 \&.Fn bar "const char *src"
444 macros should follow C header-file conventions.
446 And for the third, configurations (section 4):
447 .Bd -literal -offset indent
448 \&.Cd \(dqit* at isa? port 0x2e\(dq
449 \&.Cd \(dqit* at isa? port 0x4e\(dq
452 Manuals not in these sections generally don't need a
455 Some macros are displayed differently in the
457 section, particularly
467 All of these macros are output on their own line.
468 If two such dissimilar macros are pairwise invoked (except for
474 they are separated by a vertical space, unless in the case of
479 which are always separated by vertical space.
481 When text and macros following an
483 macro starting an input line span multiple output lines,
484 all output lines but the first will be indented to align
485 with the text immediately following the
487 macro, up to the next
492 macro or the end of an enclosing block, whichever comes first.
494 This begins with an expansion of the brief, one line description in
496 .Bd -literal -offset indent
499 utility does this, that, and the other.
502 It usually follows with a breakdown of the options (if documenting a
504 .Bd -literal -offset indent
505 The arguments are as follows:
506 \&.Bl \-tag \-width Ds
508 Print verbose information.
512 Manuals not documenting a command won't include the above fragment.
516 section usually contains most of the text of a manual, longer manuals
519 macro to form subsections.
520 In very long manuals, the
522 may be split into multiple sections, each started by an
524 macro followed by a non-standard section name, and each having
525 several subsections, like in the present
528 .It Em IMPLEMENTATION NOTES
529 Implementation-specific notes should be kept here.
530 This is useful when implementing standard functions that may have side
531 effects or notable algorithmic implications.
533 This section documents the
534 return values of functions in sections 2, 3, and 9.
539 Lists the environment variables used by the utility,
540 and explains the syntax and semantics of their values.
543 manual provides examples of typical content and formatting.
548 Documents files used.
549 It's helpful to document both the file name and a short description of how
550 the file is used (created, modified, etc.).
555 This section documents the
556 command exit status for section 1, 6, and 8 utilities.
557 Historically, this information was described in
559 a practise that is now discouraged.
565 This often contains snippets of well-formed, well-tested invocations.
566 Make sure that examples work properly!
568 Documents error conditions.
569 This is most useful in section 4 manuals.
570 Historically, this section was used in place of
572 for manuals in sections 1, 6, and 8; however, this practise is
579 Documents error handling in sections 2, 3, and 9.
584 References other manuals with related topics.
585 This section should exist for most manuals.
586 Cross-references should conventionally be ordered first by section, then
589 References to other documentation concerning the topic of the manual page,
590 for example authoritative books or journal articles, may also be
591 provided in this section.
598 References any standards implemented or used.
599 If not adhering to any standards, the
601 section should be used instead.
606 A brief history of the subject, including where it was first implemented,
607 and when it was ported to or reimplemented for the operating system at hand.
609 Credits to the person or persons who wrote the code and/or documentation.
610 Authors should generally be noted by both name and email address.
615 Common misuses and misunderstandings should be explained
618 Known bugs, limitations, and work-arounds should be described
620 .It Em SECURITY CONSIDERATIONS
621 Documents any security precautions that operators should consider.
624 Macros are one to three three characters in length and begin with a
627 at the beginning of the line.
628 An arbitrary amount of whitespace may sit between the control character
630 Thus, the following are equivalent:
631 .Bd -literal -offset indent
636 The syntax of a macro depends on its classification.
639 refers to macro arguments, which may be followed by zero or more
643 opens the scope of a macro; and if specified,
649 column indicates that the macro may also be called by passing its name
650 as an argument to another macro.
652 .Sq \&.Op \&Fl O \&Ar file
654 .Sq Op Fl O Ar file .
655 To prevent a macro call and render the macro name literally,
656 escape it by prepending a zero-width space,
662 If a macro is not callable but its name appears as an argument
663 to another macro, it is interpreted as opaque text.
671 column indicates whether the macro may call other macros by receiving
672 their names as arguments.
673 If a macro is not parsed but the name of another macro appears
674 as an argument, it is interpreted as opaque text.
678 column, if applicable, describes closure rules.
679 .Ss Block full-explicit
680 Multi-line scope closed by an explicit closing macro.
681 All macros contains bodies; only
687 .Bd -literal -offset indent
688 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
692 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
693 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
694 .It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
695 .It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
696 .It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
697 .It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
698 .It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
699 .It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
700 .It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
701 .It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
703 .Ss Block full-implicit
704 Multi-line scope closed by end-of-file or implicitly by another macro.
705 All macros have bodies; some
713 don't have heads; only one
720 .Bd -literal -offset indent
721 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
724 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
725 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
726 .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
727 .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
728 .It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
729 .It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh
730 .It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss
736 .Sx Block full-implicit
737 macro only when invoked as the first macro
740 section line, else it is
742 .Ss Block partial-explicit
743 Like block full-explicit, but also with single-line scope.
744 Each has at least a body and, in limited circumstances, a head
751 .Bd -literal -offset indent
752 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
754 \&.Yc \(lBtail...\(rB
756 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
757 \(lBbody...\(rB \&Yc \(lBtail...\(rB
759 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
760 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
761 .It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
762 .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
763 .It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
764 .It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
765 .It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
766 .It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
767 .It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
768 .It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
769 .It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
770 .It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
771 .It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
772 .It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
773 .It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
774 .It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
775 .It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
776 .It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
777 .It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
778 .It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
779 .It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
780 .It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
781 .It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
782 .It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
783 .It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
784 .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
786 .Ss Block partial-implicit
787 Like block full-implicit, but with single-line scope closed by the
789 .Bd -literal -offset indent
790 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
792 .Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
793 .It Em Macro Ta Em Callable Ta Em Parsed
794 .It Sx \&Aq Ta Yes Ta Yes
795 .It Sx \&Bq Ta Yes Ta Yes
796 .It Sx \&Brq Ta Yes Ta Yes
797 .It Sx \&D1 Ta \&No Ta \&Yes
798 .It Sx \&Dl Ta \&No Ta Yes
799 .It Sx \&Dq Ta Yes Ta Yes
800 .It Sx \&Op Ta Yes Ta Yes
801 .It Sx \&Pq Ta Yes Ta Yes
802 .It Sx \&Ql Ta Yes Ta Yes
803 .It Sx \&Qq Ta Yes Ta Yes
804 .It Sx \&Sq Ta Yes Ta Yes
805 .It Sx \&Vt Ta Yes Ta Yes
811 .Sx Block partial-implicit
812 only when invoked as the first macro
815 section line, else it is
817 .Ss Special block macro
820 macro can only be used below
825 It delimits blocks representing table cells;
826 these blocks have bodies, but no heads.
827 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
828 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
829 .It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It
832 Closed by the end of the line, fixed argument lengths,
833 and/or subsequent macros.
834 In-line macros have only text children.
835 If a number (or inequality) of arguments is
837 then the macro accepts an arbitrary number of arguments.
838 .Bd -literal -offset indent
839 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
841 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
843 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
845 .Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
846 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
847 .It Sx \&%A Ta \&No Ta \&No Ta >0
848 .It Sx \&%B Ta \&No Ta \&No Ta >0
849 .It Sx \&%C Ta \&No Ta \&No Ta >0
850 .It Sx \&%D Ta \&No Ta \&No Ta >0
851 .It Sx \&%I Ta \&No Ta \&No Ta >0
852 .It Sx \&%J Ta \&No Ta \&No Ta >0
853 .It Sx \&%N Ta \&No Ta \&No Ta >0
854 .It Sx \&%O Ta \&No Ta \&No Ta >0
855 .It Sx \&%P Ta \&No Ta \&No Ta >0
856 .It Sx \&%Q Ta \&No Ta \&No Ta >0
857 .It Sx \&%R Ta \&No Ta \&No Ta >0
858 .It Sx \&%T Ta \&No Ta \&No Ta >0
859 .It Sx \&%U Ta \&No Ta \&No Ta >0
860 .It Sx \&%V Ta \&No Ta \&No Ta >0
861 .It Sx \&Ad Ta Yes Ta Yes Ta >0
862 .It Sx \&An Ta Yes Ta Yes Ta >0
863 .It Sx \&Ap Ta Yes Ta Yes Ta 0
864 .It Sx \&Ar Ta Yes Ta Yes Ta n
865 .It Sx \&At Ta Yes Ta Yes Ta 1
866 .It Sx \&Bsx Ta Yes Ta Yes Ta n
867 .It Sx \&Bt Ta \&No Ta \&No Ta 0
868 .It Sx \&Bx Ta Yes Ta Yes Ta n
869 .It Sx \&Cd Ta Yes Ta Yes Ta >0
870 .It Sx \&Cm Ta Yes Ta Yes Ta >0
871 .It Sx \&Db Ta \&No Ta \&No Ta 1
872 .It Sx \&Dd Ta \&No Ta \&No Ta n
873 .It Sx \&Dt Ta \&No Ta \&No Ta n
874 .It Sx \&Dv Ta Yes Ta Yes Ta >0
875 .It Sx \&Dx Ta Yes Ta Yes Ta n
876 .It Sx \&Em Ta Yes Ta Yes Ta >0
877 .It Sx \&En Ta \&No Ta \&No Ta 0
878 .It Sx \&Er Ta Yes Ta Yes Ta >0
879 .It Sx \&Es Ta \&No Ta \&No Ta 0
880 .It Sx \&Ev Ta Yes Ta Yes Ta >0
881 .It Sx \&Ex Ta \&No Ta \&No Ta n
882 .It Sx \&Fa Ta Yes Ta Yes Ta >0
883 .It Sx \&Fd Ta \&No Ta \&No Ta >0
884 .It Sx \&Fl Ta Yes Ta Yes Ta n
885 .It Sx \&Fn Ta Yes Ta Yes Ta >0
886 .It Sx \&Fr Ta \&No Ta \&No Ta n
887 .It Sx \&Ft Ta Yes Ta Yes Ta >0
888 .It Sx \&Fx Ta Yes Ta Yes Ta n
889 .It Sx \&Hf Ta \&No Ta \&No Ta n
890 .It Sx \&Ic Ta Yes Ta Yes Ta >0
891 .It Sx \&In Ta \&No Ta \&No Ta 1
892 .It Sx \&Lb Ta \&No Ta \&No Ta 1
893 .It Sx \&Li Ta Yes Ta Yes Ta >0
894 .It Sx \&Lk Ta Yes Ta Yes Ta >0
895 .It Sx \&Lp Ta \&No Ta \&No Ta 0
896 .It Sx \&Ms Ta Yes Ta Yes Ta >0
897 .It Sx \&Mt Ta Yes Ta Yes Ta >0
898 .It Sx \&Nm Ta Yes Ta Yes Ta n
899 .It Sx \&No Ta Yes Ta Yes Ta 0
900 .It Sx \&Ns Ta Yes Ta Yes Ta 0
901 .It Sx \&Nx Ta Yes Ta Yes Ta n
902 .It Sx \&Os Ta \&No Ta \&No Ta n
903 .It Sx \&Ot Ta \&No Ta \&No Ta n
904 .It Sx \&Ox Ta Yes Ta Yes Ta n
905 .It Sx \&Pa Ta Yes Ta Yes Ta n
906 .It Sx \&Pf Ta Yes Ta Yes Ta 1
907 .It Sx \&Pp Ta \&No Ta \&No Ta 0
908 .It Sx \&Rv Ta \&No Ta \&No Ta n
909 .It Sx \&Sm Ta \&No Ta \&No Ta 1
910 .It Sx \&St Ta \&No Ta Yes Ta 1
911 .It Sx \&Sx Ta Yes Ta Yes Ta >0
912 .It Sx \&Sy Ta Yes Ta Yes Ta >0
913 .It Sx \&Tn Ta Yes Ta Yes Ta >0
914 .It Sx \&Ud Ta \&No Ta \&No Ta 0
915 .It Sx \&Ux Ta Yes Ta Yes Ta n
916 .It Sx \&Va Ta Yes Ta Yes Ta n
917 .It Sx \&Vt Ta Yes Ta Yes Ta >0
918 .It Sx \&Xr Ta Yes Ta Yes Ta >0
919 .It Sx \&br Ta \&No Ta \&No Ta 0
920 .It Sx \&sp Ta \&No Ta \&No Ta 1
923 When a macro argument consists of one single input character
924 considered as a delimiter, the argument gets special handling.
925 This does not apply when delimiters appear in arguments containing
926 more than one character.
927 Consequently, to prevent special handling and just handle it
928 like any other argument, a delimiter can be escaped by prepending
931 In text lines, delimiters never need escaping, but may be used
932 as normal punctuation.
934 For many macros, when the leading arguments are opening delimiters,
935 these delimiters are put before the macro scope,
936 and when the trailing arguments are closing delimiters,
937 these delimiters are put after the macro scope.
940 .D1 Pf \. \&Aq "( [ word ] ) ."
944 .D1 Aq ( [ word ] ) .
946 Opening delimiters are:
948 .Bl -tag -width Ds -offset indent -compact
955 Closing delimiters are:
957 .Bl -tag -width Ds -offset indent -compact
976 Note that even a period preceded by a backslash
978 gets this special handling; use
982 Many in-line macros interrupt their scope when they encounter
983 delimiters, and resume their scope when more arguments follow that
987 .D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e"
991 .D1 Fl a ( b | c \*(Ba d ) e
993 This applies to both opening and closing delimiters,
994 and also to the middle delimiter:
996 .Bl -tag -width Ds -offset indent -compact
1001 As a special case, the predefined string \e*(Ba is handled and rendered
1002 in the same way as a plain
1005 Using this predefined string is not recommended in new manuals.
1007 This section is a canonical reference of all macros, arranged
1009 For the scoping of individual macros, see
1015 Multiple authors should each be accorded their own
1018 Author names should be ordered with full or abbreviated forename(s)
1019 first, then full surname.
1024 This macro may also be used in a non-bibliographic context when
1025 referring to book titles.
1027 Publication city or location of an
1031 Publication date of an
1034 Recommended formats of arguments are
1035 .Ar month day , year
1039 Publisher or issuer name of an
1047 Issue number (usually for journals) of an
1051 Optional information of an
1055 Book or journal page number of an
1059 Institutional author (school, government, etc.) of an
1062 Multiple institutional authors should each be accorded their own
1066 Technical report name of an
1073 This macro may also be used in a non-bibliographical context when
1074 referring to article titles.
1076 URI of reference document.
1085 Does not have any tail arguments.
1088 Do not use this for postal addresses.
1092 .Dl \&.Ad 0x00000000
1095 Can be used both for the authors of the program, function, or driver
1096 documented in the manual, or for the authors of the manual itself.
1097 Requires either the name of an author or one of the following arguments:
1099 .Bl -tag -width "-nosplitX" -offset indent -compact
1101 Start a new output line before each subsequent invocation of
1110 The effect of selecting either of the
1112 modes ends at the beginning of the
1117 section, the default is
1119 for the first author listing and
1121 for all other author listings.
1125 .Dl \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv
1127 Begin a block enclosed by angle brackets.
1128 Does not have any head arguments.
1131 .Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
1136 Inserts an apostrophe without any surrounding whitespace.
1137 This is generally used as a grammatical device when referring to the verb
1141 .Dl \&.Fn execve \&Ap d
1143 Encloses its arguments in angle brackets.
1146 .Dl \&.Fl -key= \&Ns \&Aq \&Ar val
1149 this macro is often abused for rendering URIs, which should instead use
1153 or to note pre-processor
1155 statements, which should use
1162 If an argument is not provided, the string
1164 is used as a default.
1169 .Dl ".Ar arg1 , arg2 ."
1171 The arguments to the
1173 macro are names and placeholders for command arguments;
1174 for fixed strings to be passed verbatim as arguments, use
1179 Formats an AT&T version.
1180 Accepts one optional argument:
1182 .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
1193 Note that these arguments do not begin with a hyphen.
1213 Does not have any tail arguments.
1215 Begin a display block.
1216 Its syntax is as follows:
1217 .Bd -ragged -offset indent
1220 .Op Fl offset Ar width
1224 Display blocks are used to select a different indentation and
1225 justification than the one used by the surrounding text.
1226 They may contain both macro lines and text lines.
1227 By default, a display block is preceded by a vertical space.
1231 must be one of the following:
1232 .Bl -tag -width 13n -offset indent
1234 Produce one output line from each input line, and centre-justify each line.
1235 Using this display type is not recommended; many
1237 implementations render it poorly.
1239 Change the positions of line breaks to fill each line, and left- and
1240 right-justify the resulting block.
1242 Produce one output line from each input line,
1243 and do not justify the block at all.
1244 Preserve white space as it appears in the input.
1245 Always use a constant-width font.
1246 Use this for displaying source code.
1248 Change the positions of line breaks to fill each line, and left-justify
1249 the resulting block.
1253 but using the same font as for normal text, which is a variable width font
1254 if supported by the output device.
1259 must be provided first.
1260 Additional arguments may follow:
1261 .Bl -tag -width 13n -offset indent
1262 .It Fl offset Ar width
1263 Indent the display by the
1265 which may be one of the following:
1268 One of the pre-defined strings
1270 the width of a standard indentation (six constant width characters);
1275 which has no effect;
1277 which justifies to the right margin; or
1279 which aligns around an imagined centre axis.
1281 A macro invocation, which selects a predefined width
1282 associated with that macro.
1283 The most popular is the imaginary macro
1288 A width using the syntax described in
1289 .Sx Scaling Widths .
1291 An arbitrary string, which indents by the length of this string.
1294 When the argument is missing,
1298 Do not assert vertical space before the display.
1302 .Bd -literal -offset indent
1303 \&.Bd \-literal \-offset indent \-compact
1313 Change the font mode for a scoped block of text.
1314 Its syntax is as follows:
1315 .Bd -ragged -offset indent
1318 .Fl emphasis | literal | symbolic |
1319 .Cm \&Em | \&Li | \&Sy
1327 argument are equivalent, as are
1335 Without an argument, this macro does nothing.
1336 The font mode continues until broken by a new font mode in a nested
1348 For each macro, keep its output together on the same output line,
1349 until the end of the macro or the end of the input line is reached,
1350 whichever comes first.
1351 Line breaks in text lines are unaffected.
1352 The syntax is as follows:
1354 .D1 Pf \. Sx \&Bk Fl words
1358 argument is required; additional arguments are ignored.
1360 The following example will not break within each
1363 .Bd -literal -offset indent
1366 \&.Op Fl o Ar output
1370 Be careful in using over-long lines within a keep block!
1371 Doing so will clobber the right margin.
1374 Lists consist of items specified using the
1376 macro, containing a head or a body or both.
1377 The list syntax is as follows:
1378 .Bd -ragged -offset indent
1382 .Op Fl offset Ar val
1389 is mandatory and must be specified first.
1396 or use the length of the given string.
1399 is a global indentation for the whole list, affecting both item heads
1401 For those list types supporting it, the
1403 argument requests an additional indentation of item bodies,
1408 argument is specified, list entries are separated by vertical space.
1410 A list must specify one of the following list types:
1411 .Bl -tag -width 12n -offset indent
1413 No item heads can be specified, but a bullet will be printed at the head
1415 Item bodies start on the same output line as the bullet
1416 and are indented according to the
1423 argument has no effect; instead, each argument specifies the width
1424 of one column, using either the
1426 syntax or the string length of the argument.
1427 If the first line of the body of a
1433 contexts spanning one input line each are implied until an
1435 macro line is encountered, at which point items start being interpreted as
1442 except that dashes are used in place of bullets.
1446 except that item heads are not parsed for macro invocations.
1447 Most often used in the
1449 section with error constants in the item heads.
1452 No item heads can be specified.
1455 except that cardinal numbers are used in place of bullets,
1460 except that the first lines of item bodies are not indented, but follow
1461 the item heads like in
1468 Item bodies follow items heads on the same line, using normal inter-word
1470 Bodies are not indented, and the
1472 argument is ignored.
1474 No item heads can be specified, and none are printed.
1475 Bodies are not indented, and the
1477 argument is ignored.
1479 Item bodies start on the line following item heads and are not indented.
1482 argument is ignored.
1484 Item bodies are indented according to the
1487 When an item head fits inside the indentation, the item body follows
1488 this head on the same output line.
1489 Otherwise, the body starts on the output line following the head.
1492 Lists may be nested within lists and displays.
1497 lists may not be portable.
1504 Begin a block enclosed by square brackets.
1505 Does not have any head arguments.
1508 .Bd -literal -offset indent -compact
1516 Encloses its arguments in square brackets.
1519 .Dl \&.Bq 1 , \&Dv BUFSIZ
1522 this macro is sometimes abused to emulate optional arguments for
1523 commands; the correct macros to use for this purpose are
1535 Does not have any tail arguments.
1537 Begin a block enclosed by curly braces.
1538 Does not have any head arguments.
1541 .Bd -literal -offset indent -compact
1549 Encloses its arguments in curly braces.
1552 .Dl \&.Brq 1 , ... , \&Va n
1557 Format the BSD/OS version provided as an argument, or a default value if
1558 no argument is provided.
1575 .Dq is currently in beta test.
1577 Format the BSD version provided as an argument, or a default value if no
1578 argument is provided.
1595 Kernel configuration declaration.
1596 This denotes strings accepted by
1598 It is most often used in section 4 manual pages.
1601 .Dl \&.Cd device le0 at scode?
1604 this macro is commonly abused by using quoted literals to retain
1605 whitespace and align consecutive
1608 This practise is discouraged.
1611 Typically used for fixed strings passed as arguments, unless
1613 is more appropriate.
1614 Also useful when specifying configuration options or keys.
1617 .Dl ".Nm mt Fl f Ar device Cm rewind"
1618 .Dl ".Nm ps Fl o Cm pid , Ns Cm command"
1619 .Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
1620 .Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa"
1621 .Dl ".Cm LogLevel Dv DEBUG"
1623 One-line indented display.
1624 This is formatted by the default rules and is useful for simple indented
1626 It is followed by a newline.
1629 .Dl \&.D1 \&Fl abcdefgh
1636 Switch debugging mode.
1637 Its syntax is as follows:
1639 .D1 Pf \. Sx \&Db Cm on | off
1641 This macro is ignored by
1647 Does not have any tail arguments.
1650 This is the mandatory first macro of any
1653 Its syntax is as follows:
1655 .D1 Pf \. Sx \&Dd Ar month day , year
1659 is the full English month name, the
1661 is an optionally zero-padded numeral, and the
1663 is the full four-digit year.
1665 Other arguments are not portable; the
1667 utility handles them as follows:
1668 .Bl -dash -offset 3n -compact
1670 To have the date automatically filled in by the
1676 can be given as an argument.
1678 A few alternative date formats are accepted as well
1679 and converted to the standard form.
1681 If a date string cannot be parsed, it is used verbatim.
1683 If no date string is given, the current date is used.
1687 .Dl \&.Dd $\&Mdocdate$
1688 .Dl \&.Dd $\&Mdocdate: July 21 2007$
1689 .Dl \&.Dd July 21, 2007
1696 One-line intended display.
1697 This is formatted as literal text and is useful for commands and
1699 It is followed by a newline.
1702 .Dl \&.Dl % mandoc mdoc.7 \e(ba less
1709 Begin a block enclosed by double quotes.
1710 Does not have any head arguments.
1713 .Bd -literal -offset indent -compact
1715 April is the cruellest month
1723 Encloses its arguments in
1728 .Bd -literal -offset indent -compact
1729 \&.Dq April is the cruellest month
1740 This is the mandatory second macro of any
1743 Its syntax is as follows:
1744 .Bd -ragged -offset indent
1750 .Op Ar volume | arch
1755 Its arguments are as follows:
1756 .Bl -tag -width Ds -offset Ds
1758 The document's title (name), defaulting to
1761 It should be capitalised.
1772 .Pq Perl libraries ,
1782 .Pq system utilities ,
1784 .Pq kernel functions ,
1786 .Pq X Window System ,
1788 .Pq X Window System ,
1798 It should correspond to the manual's filename suffix and defaults to
1802 This overrides the volume inferred from
1804 This field is optional, and if specified, must be one of
1806 .Pq users' supplementary documents ,
1808 .Pq programmers' supplementary documents ,
1810 .Pq administrators' supplementary documents ,
1812 .Pq system managers' manuals ,
1814 .Pq users' reference manuals ,
1816 .Pq programmers' reference manuals ,
1818 .Pq kernel manuals ,
1829 .Pq contributed manuals .
1831 This specifies a specific relevant architecture.
1834 is not provided, it may be used in its place, else it may be used
1836 It, too, is optional.
1872 .Dl \&.Dt FOO 9 i386
1879 Defined variables such as preprocessor constants, constant symbols,
1880 enumeration values, and so on.
1885 .Dl \&.Dv STDOUT_FILENO
1891 for special-purpose constants and
1893 for variable symbols.
1895 Format the DragonFly BSD version provided as an argument, or a default
1896 value if no argument is provided.
1912 Close a scope started by
1914 Its syntax is as follows:
1916 .D1 Pf \. Sx \&Ec Op Ar TERM
1920 argument is used as the enclosure tail, for example, specifying \e(rq
1924 End a display context started by
1927 End a font mode context started by
1930 End a keep context started by
1933 End a list context started by
1941 Denotes text that should be
1943 Note that this is a presentation term and should not be used for
1944 stylistically decorating technical terms.
1945 Depending on the output device, this is usually represented
1946 using an italic font or underlined characters.
1959 This macro is obsolete and not implemented in
1962 An arbitrary enclosure.
1963 Its syntax is as follows:
1965 .D1 Pf \. Sx \&Eo Op Ar TERM
1969 argument is used as the enclosure head, for example, specifying \e(lq
1973 Error constants for definitions of the
1975 libc global variable.
1976 This is most often used in section 2 and 3 manual pages.
1984 for general constants.
1986 This macro is obsolete and not implemented.
1988 Environmental variables such as those specified in
1997 for general constants.
1999 Insert a standard sentence regarding command exit values of 0 on success
2001 This is most often used in section 1, 6, and 8 manual pages.
2002 Its syntax is as follows:
2004 .D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
2008 is not specified, the document's name set by
2013 arguments are treated as separate utilities.
2019 Its syntax is as follows:
2020 .Bd -ragged -offset indent
2026 This may be invoked for names with or without the corresponding type.
2027 It is also used to specify the field name of a structure.
2030 macro is used in the
2034 section when documenting multi-line function prototypes.
2035 If invoked with multiple arguments, the arguments are separated by a
2037 Furthermore, if the following macro is another
2039 the last argument will also have a trailing comma.
2042 .Dl \&.Fa \(dqconst char *p\(dq
2043 .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
2049 End a function context started by
2052 Historically used to document include files.
2053 This usage has been deprecated in favour of
2055 Do not use this macro.
2058 .Sx MANUAL STRUCTURE
2062 Command-line flag or option.
2063 Used when listing arguments to command-line utilities.
2064 Prints a fixed-width hyphen
2066 directly followed by each argument.
2067 If no arguments are provided, a hyphen is printed followed by a space.
2068 If the argument is a macro, a hyphen is prefixed to the subsequent macro
2072 .Dl ".Fl R Op Fl H | L | P"
2073 .Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
2074 .Dl ".Fl type Cm d Fl name Pa CVS"
2075 .Dl ".Fl Ar signal_number"
2082 Its syntax is as follows:
2083 .Bd -ragged -offset indent
2087 .Op Oo Ar argtype Oc Ar argname
2090 Function arguments are surrounded in parenthesis and
2091 are delimited by commas.
2092 If no arguments are specified, blank parenthesis are output.
2095 section, this macro starts a new output line,
2096 and a blank line is automatically inserted between function definitions.
2099 .Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
2100 .Dl \&.Fn funcname \(dqint arg0\(dq
2101 .Dl \&.Fn funcname arg0
2103 .Bd -literal -offset indent -compact
2108 When referring to a function documented in another manual page, use
2112 .Sx MANUAL STRUCTURE ,
2117 Begin a function block.
2118 This is a multi-line version of
2120 Its syntax is as follows:
2122 .D1 Pf \. Sx \&Fo Ar funcname
2124 Invocations usually occur in the following context:
2125 .Bd -ragged -offset indent
2126 .Pf \. Sx \&Ft Ar functype
2128 .Pf \. Sx \&Fo Ar funcname
2130 .Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname
2143 .Sx MANUAL STRUCTURE ,
2149 This macro is obsolete and not implemented in
2152 It was used to show function return values.
2155 .Dl Pf . Sx \&Fr Ar value
2158 Its syntax is as follows:
2160 .D1 Pf \. Sx \&Ft Ar functype
2164 section, a new output line is started after this macro.
2168 .Bd -literal -offset indent -compact
2174 .Sx MANUAL STRUCTURE ,
2181 version provided as an argument, or a default value
2182 if no argument is provided.
2198 This macro is not implemented in
2201 It was used to include the contents of a (header) file literally.
2204 .Dl Pf . Sx \&Hf Ar filename
2206 Designate an internal or interactive command.
2209 but used for instructions rather than values.
2220 is preferred for displaying code; the
2222 macro is used when referring to specific instructions.
2227 When invoked as the first macro on an input line in the
2229 section, the argument is displayed in angle brackets
2232 and a blank line is inserted in front if there is a preceding
2233 function declaration.
2234 This is most often used in section 2, 3, and 9 manual pages.
2237 .Dl \&.In sys/types.h
2240 .Sx MANUAL STRUCTURE .
2243 The syntax of this macro depends on the list type.
2252 have the following syntax:
2254 .D1 Pf \. Sx \&It Ar args
2263 have the following syntax:
2267 with subsequent lines interpreted within the scope of the
2269 until either a closing
2276 list has the following syntax:
2278 .D1 Pf \. Sx \&It Op Cm args
2280 Subsequent lines are interpreted as with
2283 The line arguments correspond to the list's left-hand side; body
2284 arguments correspond to the list's contents.
2288 list is the most complicated.
2289 Its syntax is as follows:
2291 .D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
2292 .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
2294 The arguments consist of one or more lines of text and macros
2295 representing a complete table line.
2296 Cells within the line are delimited by tabs or by the special
2299 The tab cell delimiter may only be used within the
2301 line itself; on following lines, only the
2303 macro can be used to delimit cells, and
2305 is only recognized as a macro when called by other macros,
2306 not as the first macro on a line.
2308 Note that quoted strings may span tab-delimited cells on an
2313 .Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
2315 will preserve the semicolon whitespace except for the last.
2321 The syntax is as follows:
2323 .D1 Pf \. Sx \&Lb Ar library
2327 parameter may be a system library, such as
2331 in which case a small library description is printed next to the linker
2332 invocation; or a custom library, in which case the library name is
2334 This is most commonly used in the
2336 section as described in
2337 .Sx MANUAL STRUCTURE .
2343 Denotes text that should be in a
2346 Note that this is a presentation term and should not be used for
2347 stylistically decorating technical terms.
2349 On terminal output devices, this is often indistinguishable from
2360 Its syntax is as follows:
2362 .D1 Pf \. Sx \&Lk Ar uri Op Ar name
2365 .Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
2366 .Dl \&.Lk http://bsd.lv
2374 Display a mathematical symbol.
2375 Its syntax is as follows:
2377 .D1 Pf \. Sx \&Ms Ar symbol
2386 Its syntax is as follows:
2388 .D1 Pf \. Sx \&Mt Ar address
2391 .Dl \&.Mt discuss@manpages.bsd.lv
2393 A one line description of the manual's content.
2394 This may only be invoked in the
2396 section subsequent the
2401 .Dl Pf . Sx \&Nd mdoc language reference
2402 .Dl Pf . Sx \&Nd format and display UNIX manuals
2406 macro technically accepts child macros and terminates with a subsequent
2409 Do not assume this behaviour: some
2411 database generators are not smart enough to parse more than the line
2412 arguments and will display macros verbatim.
2417 The name of the manual page, or \(em in particular in section 1, 6,
2418 and 8 pages \(em of an additional command or feature documented in
2420 When first invoked, the
2422 macro expects a single argument, the name of the manual page.
2423 Usually, the first invocation happens in the
2425 section of the page.
2426 The specified name will be remembered and used whenever the macro is
2427 called again without arguments later in the page.
2431 .Sx Block full-implicit
2432 semantics when invoked as the first macro on an input line in the
2434 section; otherwise, it uses ordinary
2439 .Bd -literal -offset indent
2448 of section 2, 3 and 9 manual pages, use the
2452 to mark up the name of the manual page.
2455 Closes the scope of any preceding in-line macro.
2456 When used after physical formatting macros like
2460 switches back to the standard font face and weight.
2461 Can also be used to embed plain text strings in macro lines
2462 using semantic annotation macros.
2465 .Dl ".Em italic , Sy bold , No and roman"
2467 .Bd -literal -offset indent -compact
2469 \&.Cm :C No / Ar pattern No / Ar replacement No /
2479 Suppress a space between the output of the preceding macro
2480 and the following text or macro.
2481 Following invocation, input is interpreted as normal text
2486 This has no effect when invoked at the start of a macro line.
2489 .Dl ".Ar name Ns = Ns Ar value"
2490 .Dl ".Cm :M Ns Ar pattern"
2491 .Dl ".Fl o Ns Ar output"
2500 version provided as an argument, or a default value if
2501 no argument is provided.
2521 Multi-line version of
2525 .Bd -literal -offset indent -compact
2527 \&.Op Fl flag Ns Ar value
2531 Optional part of a command line.
2532 Prints the argument(s) in brackets.
2533 This is most often used in the
2535 section of section 1 and 8 manual pages.
2538 .Dl \&.Op \&Fl a \&Ar b
2539 .Dl \&.Op \&Ar a | b
2544 Document operating system version.
2545 This is the mandatory third macro of
2549 Its syntax is as follows:
2551 .D1 Pf \. Sx \&Os Op Ar system Op Ar version
2555 parameter specifies the relevant operating system or environment.
2556 Left unspecified, it defaults to the local operating system version.
2557 This is the suggested form.
2561 .Dl \&.Os KTH/CSC/TCS
2569 This macro is obsolete and not implemented in
2574 packages described it as
2575 .Dq "old function type (FORTRAN)" .
2579 version provided as an argument, or a default value
2580 if no argument is provided.
2596 An absolute or relative file system path, or a file or directory name.
2597 If an argument is not provided, the character
2599 is used as a default.
2602 .Dl \&.Pa /usr/bin/mandoc
2603 .Dl \&.Pa /usr/share/man/man7/mdoc.7
2608 Close parenthesised context opened by
2611 Removes the space between its argument
2613 and the following macro.
2614 Its syntax is as follows:
2616 .D1 .Pf Ar prefix macro arguments ...
2618 This is equivalent to:
2620 .D1 .No Ar prefix No \&Ns Ar macro arguments ...
2623 .Dl ".Pf $ Ar variable_name"
2624 .Dl ".Pf 0x Ar hex_digits"
2631 Multi-line version of
2635 This will assert vertical space between prior and subsequent macros
2638 Paragraph breaks are not needed before or after
2642 macros or before displays
2650 Parenthesised enclosure.
2655 Close quoted context opened by
2658 Format a single-quoted literal.
2664 Multi-line version of
2667 Encloses its arguments in
2682 Does not have any tail arguments.
2684 Begin a bibliographic
2687 Does not have any head arguments.
2688 The block macro may only contain
2704 child macros (at least one must be specified).
2707 .Bd -literal -offset indent -compact
2709 \&.%A J. E. Hopcroft
2711 \&.%B Introduction to Automata Theory, Languages, and Computation
2712 \&.%I Addison-Wesley
2713 \&.%C Reading, Massachusettes
2720 block is used within a SEE ALSO section, a vertical space is asserted
2721 before the rendered output, else the block continues on the current
2724 Insert a standard sentence regarding a function call's return value of 0
2725 on success and \-1 on error, with the
2727 libc global variable set on error.
2728 Its syntax is as follows:
2730 .D1 Pf \. Sx \&Rv Fl std Op Ar function ...
2734 is not specified, the document's name set by
2739 arguments are treated as separate functions.
2744 Close single-quoted context opened by
2747 Begin a new section.
2748 For a list of conventional manual sections, see
2749 .Sx MANUAL STRUCTURE .
2750 These sections should be used unless it's absolutely necessary that
2751 custom sections be used.
2753 Section names should be unique so that they may be keyed by
2755 Although this macro is parsed, it should not consist of child node or it
2756 may not be linked with
2765 Switches the spacing mode for output generated from macros.
2766 Its syntax is as follows:
2768 .D1 Pf \. Sx \&Sm Cm on | off
2770 By default, spacing is
2774 no white space is inserted between macro arguments and between the
2775 output generated from adjacent macros, but text lines
2776 still get normal spacing between words and sentences.
2778 Multi-line version of
2781 Encloses its arguments in
2791 Begin a new subsection.
2794 there is no convention for the naming of subsections.
2797 the conventional sections described in
2798 .Sx MANUAL STRUCTURE
2799 rarely have subsections.
2801 Sub-section names should be unique so that they may be keyed by
2803 Although this macro is parsed, it should not consist of child node or it
2804 may not be linked with
2813 Replace an abbreviation for a standard with the full form.
2814 The following standards are recognised:
2816 .Bl -tag -width "-p1003.1g-2000X" -compact
2911 Reference a section or subsection in the same manual page.
2912 The referenced section or subsection name must be identical to the
2913 enclosed argument, including whitespace.
2916 .Dl \&.Sx MANUAL STRUCTURE
2923 Format enclosed arguments in symbolic
2925 Note that this is a presentation term and should not be used for
2926 stylistically decorating technical terms.
2935 Table cell separator in
2937 lists; can only be used below
2942 Since this macro is often implemented to use a small caps font,
2943 it has historically been used for acronyms (like ASCII) as well.
2944 Such usage is not recommended because it would use the same macro
2945 sometimes for semantical annotation, sometimes for physical formatting.
2951 .Dq currently under development.
2953 Format the UNIX name.
2954 Accepts no argument.
2973 .Dl \&.Va const char *bar ;
2976 This is also used for indicating global variables in the
2978 section, in which case a variable name is also specified.
2979 Note that it accepts
2980 .Sx Block partial-implicit
2981 syntax when invoked as the first macro on an input line in the
2983 section, else it accepts ordinary
2986 In the former case, this macro starts a new output line,
2987 and a blank line is inserted in front if there is a preceding
2988 function definition or include directive.
2990 Note that this should not be confused with
2992 which is used for function return types.
2995 .Dl \&.Vt unsigned char
2996 .Dl \&.Vt extern const char * const sys_signame[] \&;
2999 .Sx MANUAL STRUCTURE
3003 Close a scope opened by
3006 Extend the header of an
3008 macro or the body of a partial-implicit block macro
3009 beyond the end of the input line.
3010 This macro originally existed to work around the 9-argument limit
3014 Link to another manual
3015 .Pq Qq cross-reference .
3016 Its syntax is as follows:
3018 .D1 Pf \. Sx \&Xr Ar name section
3024 are the name and section of the linked manual.
3027 is followed by non-punctuation, an
3029 is inserted into the token stream.
3030 This behaviour is for compatibility with
3035 .Dl \&.Xr mandoc 1 \&;
3036 .Dl \&.Xr mandoc 1 \&Ns s behaviour
3039 This macro should not be used; it is implemented for compatibility with
3044 in the event of natural paragraph breaks.
3046 Emits vertical space.
3047 This macro should not be used; it is implemented for compatibility with
3049 Its syntax is as follows:
3051 .D1 Pf \. Sx \&sp Op Ar height
3055 argument must be formatted as described in
3056 .Sx Scaling Widths .
3059 asserts a single vertical space.
3061 This section documents compatibility between mandoc and other other
3062 troff implementations, at this time limited to GNU troff
3066 refers to groff versions before 1.17,
3067 which featured a significant update of the
3071 Heirloom troff, the other significant troff implementation accepting
3072 \-mdoc, is similar to historic groff.
3074 The following problematic behaviour is found in groff:
3075 .ds hist (Historic groff only.)
3090 with unknown arguments produces no output at all.
3092 Newer groff and mandoc print
3097 does not recognize trailing punctuation characters when they immediately
3098 precede tabulator characters, but treats them as normal text and
3099 outputs a space before them.
3101 .Sx \&Bd Fl ragged compact
3102 does not start a new line.
3106 with non-standard arguments behaves very strangely.
3107 When there are three arguments, they are printed verbatim.
3108 Any other number of arguments is replaced by the current date,
3109 but without any arguments the string
3114 does not print a dash for an empty argument.
3118 does not start a new line unless invoked as the line macro in the
3126 children causes inconsistent spacing between arguments.
3127 In mandoc, a single space is always inserted between arguments.
3132 causes inconsistent vertical spacing, depending on whether a prior
3139 for the normalised behaviour in mandoc.
3142 ignores additional arguments and is not treated specially in the
3147 sometimes requires a
3151 In new groff and mandoc, any list may be nested by default and
3153 lists will restart the sequence only for the sub-list.
3156 followed by a delimiter is incorrectly used in some manuals
3157 instead of properly quoting that character, which sometimes works with
3161 only accepts a single link-name argument; the remainder is misformatted.
3164 does not format its arguments when used in the FILES section under
3168 can only be called by other macros, but not at the beginning of a line.
3173 Historic groff only allows up to eight or nine arguments per macro input
3174 line, depending on the exact situation.
3175 Providing more arguments causes garbled output.
3176 The number of arguments on one input line is not limited with mandoc.
3178 Historic groff has many un-callable macros.
3179 Most of these (excluding some block-level macros) are callable
3180 in new groff and mandoc.
3183 (vertical bar) is not fully supported as a delimiter.
3190 .Pq font family face
3192 escapes behave irregularly when specified within line-macro scopes.
3194 Negative scaling units return to prior lines.
3195 Instead, mandoc truncates them to zero.
3198 The following features are unimplemented in mandoc:
3206 .Fl offset Ar center
3208 .Fl offset Ar right .
3209 Groff does not implement centered and flush-right rendering either,
3210 but produces large indentations.
3214 .Pq horizontal position ,
3216 .Pq vertical position ,
3220 .Pq text filling colour ,
3222 .Pq zero-length character ,
3226 .Pq horizontal position marker ,
3228 .Pq text overstrike ,
3232 escape sequences are all discarded in mandoc.
3236 scaling unit is accepted by mandoc, but rendered as the default unit.
3238 In quoted literals, groff allows pairwise double-quotes to produce a
3239 standalone double-quote in formatted output.
3240 This is not supported by mandoc.
3253 language first appeared as a troff macro package in
3255 It was later significantly updated by Werner Lemberg and Ruslan Ermilov
3257 The standalone implementation that is part of the
3259 utility written by Kristaps Dzonsons appeared in
3264 reference was written by
3265 .An Kristaps Dzonsons ,
3266 .Mt kristaps@bsd.lv .
git.ckatri.com / mandoc.git / blob