1 .\" $Id: mdoc.7,v 1.271 2018/07/28 18:34:15 schwarze Exp $
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2010, 2011, 2013-2018 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.
19 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
20 .\" Copyright 2018 Nexenta Systems, Inc.
22 .Dd $Mdocdate: July 28 2018 $
27 .Nd semantic markup language for formatting manual pages
31 language supports authoring of manual pages for the
33 utility by allowing semantic annotations of words, phrases,
34 page sections and complete manual pages.
35 Such annotations are used by formatting tools to achieve a uniform
36 presentation across all manuals written in
38 and to support hyperlinking if supported by the output medium.
40 This reference document describes the structure of manual pages
41 and the syntax and usage of the
44 The reference implementation of a parsing and formatting tool is
48 section describes compatibility with other implementations.
52 document, lines beginning with the control character
56 The first word is the macro name.
57 It consists of two or three letters.
58 Most macro names begin with a capital letter.
59 For a list of available macros, see
61 The words following the macro name are arguments to the macro, optionally
62 including the names of other, callable macros; see
66 Lines not beginning with the control character are called
68 They provide free-form text to be printed; the formatting of the text
69 depends on the respective processing context:
70 .Bd -literal -offset indent
71 \&.Sh Macro lines change control state.
72 Text lines are interpreted within the current state.
75 Many aspects of the basic syntax of the
77 language are based on the
85 manual for details, in particular regarding
86 comments, escape sequences, whitespace, and quoting.
91 documents is discouraged;
93 supports some of them merely for backward compatibility.
97 document consists of a document prologue followed by one or more
100 The prologue, which consists of the
105 macros in that order, is required for every document.
107 The first section (sections are denoted by
109 must be the NAME section, consisting of at least one
114 Following that, convention dictates specifying at least the
118 sections, although this varies between manual sections.
120 The following is a well-formed skeleton
124 .Bd -literal -offset indent
126 \&.Dt PROGNAME section
130 \&.Nd one line about what it does
131 \&.\e\(dq .Sh LIBRARY
132 \&.\e\(dq For sections 2, 3, and 9 only.
140 utility processes files ...
141 \&.\e\(dq .Sh IMPLEMENTATION NOTES
142 \&.\e\(dq .Sh RETURN VALUES
143 \&.\e\(dq For sections 2, 3, and 9 only.
144 \&.\e\(dq .Sh CONTEXT
145 \&.\e\(dq For section 9 functions only.
146 \&.\e\(dq .Sh ENVIRONMENT
147 \&.\e\(dq For sections 1, 1M, and 5.
149 \&.\e\(dq .Sh EXIT STATUS
150 \&.\e\(dq For sections 1, 1M, and 5.
151 \&.\e\(dq .Sh EXAMPLES
152 \&.\e\(dq .Sh DIAGNOSTICS
154 \&.\e\(dq For sections 2, 3, and 9 only.
155 \&.\e\(dq .Sh ARCHITECTURE
156 \&.\e\(dq .Sh CODE SET INDEPENDENCE
157 \&.\e\(dq For sections 1, 1M, and 3 only.
158 \&.\e\(dq .Sh INTERFACE STABILITY
159 \&.\e\(dq .Sh MT-LEVEL
160 \&.\e\(dq For sections 2 and 3 only.
161 \&.\e\(dq .Sh SECURITY
162 \&.\e\(dq .Sh SEE ALSO
163 \&.\e\(dq .Xr foobar 1
164 \&.\e\(dq .Sh STANDARDS
165 \&.\e\(dq .Sh HISTORY
166 \&.\e\(dq .Sh AUTHORS
167 \&.\e\(dq .Sh CAVEATS
173 document are conventionally ordered as they appear above.
174 Sections should be composed as follows:
175 .Bl -ohang -offset Ds
177 The name(s) and a one line description of the documented material.
178 The syntax for this as follows:
179 .Bd -literal -offset indent
183 \&.Nd a one line description
188 names should be separated by commas.
192 macro(s) must precede the
201 The name of the library containing the documented material, which is
202 assumed to be a function in a section 2, 3, or 9 manual.
203 The syntax for this is as follows:
204 .Bd -literal -offset indent
211 Documents the utility invocation syntax, function call syntax, or device
214 For the first, utilities (sections 1 and 1M), this is
215 generally structured as follows:
216 .Bd -literal -offset indent
227 Commands should be ordered alphabetically.
229 For the second, function calls (sections 2, 3, 7I, 7P, 9):
230 .Bd -literal -offset indent
232 \&.Vt extern const char *global;
234 \&.Fn foo "const char *src"
236 \&.Fn bar "const char *src"
245 macros should follow C header-file conventions.
247 And for the third, configurations (section 7D):
248 .Bd -literal -offset indent
249 \&.Pa /dev/device_node
252 Manuals not in these sections generally don't need a
255 Some macros are displayed differently in the
257 section, particularly
267 All of these macros are output on their own line.
268 If two such dissimilar macros are pairwise invoked (except for
274 they are separated by a vertical space, unless in the case of
279 which are always separated by vertical space.
281 When text and macros following an
283 macro starting an input line span multiple output lines,
284 all output lines but the first will be indented to align
285 with the text immediately following the
287 macro, up to the next
292 macro or the end of an enclosing block, whichever comes first.
294 This begins with an expansion of the brief, one line description in
296 .Bd -literal -offset indent
299 utility does this, that, and the other.
302 It usually follows with a breakdown of the options (if documenting a
304 .Bd -literal -offset indent
305 The arguments are as follows:
306 \&.Bl \-tag \-width Ds
308 Print verbose information.
312 List the options in alphabetical order,
313 uppercase before lowercase for each letter and
314 with no regard to whether an option takes an argument.
315 Put digits in ascending order before all letter options.
317 Manuals not documenting a command won't include the above fragment.
321 section usually contains most of the text of a manual, longer manuals
324 macro to form subsections.
325 In very long manuals, the
327 may be split into multiple sections, each started by an
329 macro followed by a non-standard section name, and each having
330 several subsections, like in the present
333 .It Em IMPLEMENTATION NOTES
334 Implementation-specific notes should be kept here.
335 This is useful when implementing standard functions that may have side
336 effects or notable algorithmic implications.
338 This section documents the
339 return values of functions in sections 2, 3, and 9.
344 This section lists the contexts in which functions can be called in section 9.
345 The contexts are user, kernel, or interrupt.
347 Lists the environment variables used by the utility,
348 and explains the syntax and semantics of their values.
351 manual provides examples of typical content and formatting.
356 Documents files used.
357 It's helpful to document both the file name and a short description of how
358 the file is used (created, modified, etc.).
363 This section documents the
364 command exit status for sections 1 and 1M.
365 Historically, this information was described in
367 a practise that is now discouraged.
373 This often contains snippets of well-formed, well-tested invocations.
374 Make sure that examples work properly!
376 Documents error and diagnostic messages displayed to the user or
378 Note that exit status and return values should be documented in the
388 Documents error handling in sections 2, 3, and 9.
393 This section is usually absent, but will be present when the
394 interface is specific to one or more architectures.
395 .It Em CODE SET INDEPENDENCE
396 Indicates whether the interface operates correctly with various different
398 True independent code sets will support not only ASCII and Extended UNIX
399 Codesets (EUC), but also other multi-byte encodings such as UTF-8 and GB2312.
401 Generally there will be some limitations that are fairly standard.
404 for more information about some of these.
405 Most interfaces should support at least UTF-8 in addition to ASCII.
406 .It Em INTERFACE STABILITY
407 Indicates the level of commitment to the interface.
408 Interfaces can be described with in the following ways:
411 Indicates that the interface is defined by one or more standards bodies.
412 Generally, changes to the interface will be carefully managed to conform
413 to the relevant standards.
414 These interfaces are generally the most suitable for use in portable programs.
416 Indicates that the interface is intended to be preserved for the long-haul, and
417 will rarely, if ever change, and never without notification (barring
418 extraordinary and extenuating circumstances).
419 These interfaces are preferred over other interfaces with the exeception of
423 Indicates that the interface may change.
424 Generally, changes to these interfaces should be infrequent, and some effort
425 will be made to address compatibility considerations when changing or removing
427 However, there is no firm commitment to the preservation of the interface.
428 Most often this is applied to interfaces where operational experience with the
429 interface is still limited and some need to change may be anticipated.
431 Consumers should expect to revalidate any
433 interfaces when crossing release boundaries.
434 Products intended for use on many releases or intended to support compatibility
435 with future releases should avoid these interfaces.
437 The interface can change at any time for any reason.
438 Often this relates to interfaces that are part of external software components
439 that are still evolving rapidly.
440 Consumers should not expect that the interface (either binary or source level)
441 will be unchanged from one release to the next.
442 .It Nm Not-an-Interface
443 Describes something that is specifically not intended for programmatic
445 For example, specific human-readable output, or the layout of graphical items on
446 a user interface, may be described this way.
447 Generally programmatic alternatives to these will be available, and should be
448 used when programmatic consumption is needed.
450 This is an internal interface.
451 Generally these interfaces should only be used within the project, and should
452 not be used by other programs or modules.
453 The interface can and will change without notice as the project needs, at any
456 Most often, Private interfaces will lack any documentation whatsoever, and
457 generally any undocumented interface can be assumed to be Private.
459 The interface is not intended for use in new projects or programs, and may
460 be removed at a future date.
463 word is a modifier that can
464 be applied to other commitment levels.
466 .Nm Obsolete Committed
467 interface is unlikely to be removed or changed, but nonetheless new use
468 is discouraged (perhaps a better newer alternative is present).
471 This section describes considerations for the interface when used within
472 programs that use multiple threads.
473 More discussion of these considerations is made in the MT-Level section of
475 The interface can be described in the following ways.
478 Indicates the interface is safe for use within multiple threads.
479 There may be additional caveats that apply, in which case those will be
481 Note that some interfaces have semantics which may affect other threads, but
482 these should be an intrinsic part of the interface rather than an unexpected
484 For example, closing a file in one thread will cause that file to be closed in
487 Indicates the interface is unsuitable for concurrent use within multiple
489 A threaded application may still make use of the interface, but will be required
490 to provide external synchronization means to ensure that only a single thread
491 calls the interface at a time.
493 Indicates that the interface is not only safe for concurrent use, but is
494 designed for such use.
497 interface may make use of a global lock to provide safety, but at reduced
498 internal concurrency, whereas an
500 interface will be designed to be efficient even when used concurrently.
501 .It Nm Async-Signal-Safe
502 Indicates that the library is safe for use within a signal handler.
505 interface can be made
506 .Nm Async-Signal-Safe
507 by ensuring that it blocks signals when acquiring locks.
508 .It Nm Safe with Exceptions
511 but with specific exceptions noted.
512 .It Nm MT-Safe with Exceptions
515 but with specific exceptions noted.
518 Documents any security precautions that operators should consider.
520 References other manuals with related topics.
521 This section should exist for most manuals.
522 Cross-references should conventionally be ordered first by section, then
523 alphabetically (ignoring case).
525 References to other documentation concerning the topic of the manual page,
526 for example authoritative books or journal articles, may also be
527 provided in this section.
534 References any standards implemented or used.
535 If not adhering to any standards, the
537 section should be used instead.
542 A brief history of the subject, including where it was first implemented,
543 and when it was ported to or reimplemented for the operating system at hand.
545 Credits to the person or persons who wrote the code and/or documentation.
546 Authors should generally be noted by both name and email address.
551 Common misuses and misunderstandings should be explained
554 Known bugs, limitations, and work-arounds should be described
558 This overview is sorted such that macros of similar purpose are listed
559 together, to help find the best macro for any given purpose.
560 Deprecated macros are not included in the overview, but can be found below
562 .Sx MACRO REFERENCE .
563 .Ss Document preamble and NAME section macros
564 .Bl -column "Brq, Bro, Brc" description
565 .It Sx \&Dd Ta document date: Ar month day , year
566 .It Sx \&Dt Ta document title: Ar TITLE SECTION Op Ar arch
567 .It Sx \&Os Ta operating system version: Op Ar system Op Ar version
568 .It Sx \&Nm Ta document name (one argument)
569 .It Sx \&Nd Ta document description (one line)
571 .Ss Sections and cross references
572 .Bl -column "Brq, Bro, Brc" description
573 .It Sx \&Sh Ta section header (one line)
574 .It Sx \&Ss Ta subsection header (one line)
575 .It Sx \&Sx Ta internal cross reference to a section or subsection
576 .It Sx \&Xr Ta cross reference to another manual page: Ar name section
577 .It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments)
579 .Ss Displays and lists
580 .Bl -column "Brq, Bro, Brc" description
581 .It Sx \&Bd , \&Ed Ta display block:
583 .Op Fl offset Ar width
585 .It Sx \&D1 Ta indented display (one line)
586 .It Sx \&Dl Ta indented literal display (one line)
587 .It Sx \&Ql Ta in-line literal display: Ql text
588 .It Sx \&Bl , \&El Ta list block:
593 .It Sx \&It Ta list item (syntax depends on Fl Ar type )
594 .It Sx \&Ta Ta table cell separator in Sx \&Bl Fl column No lists
595 .It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references)
598 .Bl -column "Brq, Bro, Brc" description
599 .It Sx \&Pf Ta prefix, no following horizontal space (one argument)
600 .It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
601 .It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
602 .It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off
603 .It Sx \&Bk , \&Ek Ta keep block: Fl words
605 .Ss Semantic markup for command line utilities
606 .Bl -column "Brq, Bro, Brc" description
607 .It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility
608 .It Sx \&Fl Ta command line options (flags) (>=0 arguments)
609 .It Sx \&Cm Ta command modifier (>0 arguments)
610 .It Sx \&Ar Ta command arguments (>=0 arguments)
611 .It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure)
612 .It Sx \&Ic Ta internal or interactive command (>0 arguments)
613 .It Sx \&Ev Ta environmental variable (>0 arguments)
614 .It Sx \&Pa Ta file system path (>=0 arguments)
616 .Ss Semantic markup for function libraries
617 .Bl -column "Brq, Bro, Brc" description
618 .It Sx \&Lb Ta function library (one argument)
619 .It Sx \&In Ta include file (one argument)
620 .It Sx \&Fd Ta other preprocessor directive (>0 arguments)
621 .It Sx \&Ft Ta function type (>0 arguments)
622 .It Sx \&Fo , \&Fc Ta function block: Ar funcname
623 .It Sx \&Fn Ta function name:
630 .It Sx \&Fa Ta function argument (>0 arguments)
631 .It Sx \&Vt Ta variable type (>0 arguments)
632 .It Sx \&Va Ta variable name (>0 arguments)
633 .It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments)
634 .It Sx \&Er Ta error constant (>0 arguments)
635 .It Sx \&Ev Ta environmental variable (>0 arguments)
637 .Ss Various semantic markup
638 .Bl -column "Brq, Bro, Brc" description
639 .It Sx \&An Ta author name (>0 arguments)
640 .It Sx \&Lk Ta hyperlink: Ar uri Op Ar name
641 .It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address
642 .It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
643 .It Sx \&Ad Ta memory address (>0 arguments)
644 .It Sx \&Ms Ta mathematical symbol (>0 arguments)
647 .Bl -column "Brq, Bro, Brc" description
648 .It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments)
649 .It Sx \&Sy Ta boldface font (symbolic) (>0 arguments)
650 .It Sx \&Li Ta typewriter font (literal) (>0 arguments)
651 .It Sx \&No Ta return to roman font (normal) (no arguments)
652 .It Sx \&Bf , \&Ef Ta font block:
653 .Op Fl Ar type | Cm \&Em | \&Li | \&Sy
655 .Ss Physical enclosures
656 .Bl -column "Brq, Bro, Brc" description
657 .It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text
658 .It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text
659 .It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text
660 .It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text
661 .It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text
662 .It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text
663 .It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text
664 .It Sx \&Eo , \&Ec Ta generic enclosure
667 .Bl -column "Brq, Bro, Brc" description
668 .It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
669 .It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
670 .It Sx \&St Ta reference to a standards document (one argument)
680 This section is a canonical reference of all macros, arranged
682 For the scoping of individual macros, see
688 Multiple authors should each be accorded their own
691 Author names should be ordered with full or abbreviated forename(s)
692 first, then full surname.
697 This macro may also be used in a non-bibliographic context when
698 referring to book titles.
700 Publication city or location of an
704 Publication date of an
707 Recommended formats of arguments are
712 Publisher or issuer name of an
720 Issue number (usually for journals) of an
724 Optional information of an
728 Book or journal page number of an
732 Institutional author (school, government, etc.) of an
735 Multiple institutional authors should each be accorded their own
739 Technical report name of an
746 This macro may also be used in a non-bibliographical context when
747 referring to article titles.
749 URI of reference document.
758 Does not have any tail arguments.
761 Do not use this for postal addresses.
768 Can be used both for the authors of the program, function, or driver
769 documented in the manual, or for the authors of the manual itself.
770 Requires either the name of an author or one of the following arguments:
772 .Bl -tag -width "-nosplitX" -offset indent -compact
774 Start a new output line before each subsequent invocation of
783 The effect of selecting either of the
785 modes ends at the beginning of the
790 section, the default is
792 for the first author listing and
794 for all other author listings.
798 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
800 Begin a block enclosed by angle brackets.
801 Does not have any head arguments.
802 This macro is almost never useful.
807 Inserts an apostrophe without any surrounding whitespace.
808 This is generally used as a grammatical device when referring to the verb
812 .Dl \&.Fn execve \&Ap d
814 Encloses its arguments in angle brackets.
815 The only important use case is for email addresses.
820 Occasionally, it is used for names of characters and keys, for example:
821 .Bd -literal -offset indent
841 usually renders with non-ASCII characters in non-ASCII output modes,
842 do not use it where the ASCII characters
846 are required as syntax elements.
847 Instead, use these characters directly in such cases, combining them
859 If an argument is not provided, the string
861 is used as a default.
866 .Dl ".Ar arg1 , arg2 ."
870 macro are names and placeholders for command arguments;
871 for fixed strings to be passed verbatim as arguments, use
879 Accepts one optional argument:
881 .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
892 Note that these arguments do not begin with a hyphen.
911 Does not have any tail arguments.
913 Begin a display block.
914 Its syntax is as follows:
915 .Bd -ragged -offset indent
918 .Op Fl offset Ar width
922 Display blocks are used to select a different indentation and
923 justification than the one used by the surrounding text.
924 They may contain both macro lines and text lines.
925 By default, a display block is preceded by a vertical space.
929 must be one of the following:
930 .Bl -tag -width 13n -offset indent
932 Produce one output line from each input line, and center-justify each line.
933 Using this display type is not recommended; many
935 implementations render it poorly.
937 Change the positions of line breaks to fill each line, and left- and
938 right-justify the resulting block.
940 Produce one output line from each input line,
941 and do not justify the block at all.
942 Preserve white space as it appears in the input.
943 Always use a constant-width font.
944 Use this for displaying source code.
946 Change the positions of line breaks to fill each line, and left-justify
951 but using the same font as for normal text, which is a variable width font
952 if supported by the output device.
957 must be provided first.
958 Additional arguments may follow:
959 .Bl -tag -width 13n -offset indent
960 .It Fl offset Ar width
961 Indent the display by the
963 which may be one of the following:
966 One of the pre-defined strings
968 the width of a standard indentation (six constant width characters);
975 which justifies to the right margin; or
977 which aligns around an imagined center axis.
979 A macro invocation, which selects a predefined width
980 associated with that macro.
981 The most popular is the imaginary macro
986 A scaling width as described in
989 An arbitrary string, which indents by the length of this string.
992 When the argument is missing,
996 Do not assert vertical space before the display.
1000 .Bd -literal -offset indent
1001 \&.Bd \-literal \-offset indent \-compact
1011 Change the font mode for a scoped block of text.
1012 Its syntax is as follows:
1013 .Bd -ragged -offset indent
1016 .Fl emphasis | literal | symbolic |
1017 .Cm \&Em | \&Li | \&Sy
1025 argument are equivalent, as are
1033 Without an argument, this macro does nothing.
1034 The font mode continues until broken by a new font mode in a nested
1046 For each macro, keep its output together on the same output line,
1047 until the end of the macro or the end of the input line is reached,
1048 whichever comes first.
1049 Line breaks in text lines are unaffected.
1050 The syntax is as follows:
1052 .D1 Pf \. Sx \&Bk Fl words
1056 argument is required; additional arguments are ignored.
1058 The following example will not break within each
1061 .Bd -literal -offset indent
1064 \&.Op Fl o Ar output
1068 Be careful in using over-long lines within a keep block!
1069 Doing so will clobber the right margin.
1072 Lists consist of items specified using the
1074 macro, containing a head or a body or both.
1075 The list syntax is as follows:
1076 .Bd -ragged -offset indent
1080 .Op Fl offset Ar val
1087 is mandatory and must be specified first.
1092 arguments accept macro names as described for
1095 scaling widths as described in
1097 or use the length of the given string.
1100 is a global indentation for the whole list, affecting both item heads
1102 For those list types supporting it, the
1104 argument requests an additional indentation of item bodies,
1109 argument is specified, list entries are separated by vertical space.
1111 A list must specify one of the following list types:
1112 .Bl -tag -width 12n -offset indent
1114 No item heads can be specified, but a bullet will be printed at the head
1116 Item bodies start on the same output line as the bullet
1117 and are indented according to the
1124 argument has no effect; instead, the string length of each argument
1125 specifies the width of one column.
1126 If the first line of the body of a
1132 contexts spanning one input line each are implied until an
1134 macro line is encountered, at which point items start being interpreted as
1141 except that dashes are used in place of bullets.
1145 except that item heads are not parsed for macro invocations.
1146 Most often used in the
1148 section with error constants in the item heads.
1151 No item heads can be specified.
1154 except that cardinal numbers are used in place of bullets,
1159 except that the first lines of item bodies are not indented, but follow
1160 the item heads like in
1167 Item bodies follow items heads on the same line, using normal inter-word
1169 Bodies are not indented, and the
1171 argument is ignored.
1173 No item heads can be specified, and none are printed.
1174 Bodies are not indented, and the
1176 argument is ignored.
1178 Item bodies start on the line following item heads and are not indented.
1181 argument is ignored.
1183 Item bodies are indented according to the
1186 When an item head fits inside the indentation, the item body follows
1187 this head on the same output line.
1188 Otherwise, the body starts on the output line following the head.
1191 Lists may be nested within lists and displays.
1196 lists may not be portable.
1203 Begin a block enclosed by square brackets.
1204 Does not have any head arguments.
1207 .Bd -literal -offset indent -compact
1215 Encloses its arguments in square brackets.
1218 .Dl \&.Bq 1 , \&Dv BUFSIZ
1221 this macro is sometimes abused to emulate optional arguments for
1222 commands; the correct macros to use for this purpose are
1234 Does not have any tail arguments.
1236 Begin a block enclosed by curly braces.
1237 Does not have any head arguments.
1240 .Bd -literal -offset indent -compact
1248 Encloses its arguments in curly braces.
1251 .Dl \&.Brq 1 , ... , \&Va n
1258 version provided as an argument, or a default value if
1259 no argument is provided.
1274 Supported only for compatibility, do not use this in new manuals.
1276 .Dq is currently in beta test.
1280 version provided as an argument, or a default value if no
1281 argument is provided.
1297 Kernel configuration declaration.
1298 It is found in pages for
1303 .Dl \&.Cd device le0 at scode?
1306 this macro is commonly abused by using quoted literals to retain
1307 whitespace and align consecutive
1310 This practise is discouraged.
1313 Typically used for fixed strings passed as arguments, unless
1315 is more appropriate.
1316 Also useful when specifying configuration options or keys.
1319 .Dl ".Nm mt Fl f Ar device Cm rewind"
1320 .Dl ".Nm ps Fl o Cm pid , Ns Cm command"
1321 .Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
1322 .Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa"
1323 .Dl ".Cm LogLevel Dv DEBUG"
1325 One-line indented display.
1326 This is formatted by the default rules and is useful for simple indented
1328 It is followed by a newline.
1331 .Dl \&.D1 \&Fl abcdefgh
1338 This macro is obsolete.
1339 No replacement is needed.
1342 and groff including its arguments.
1343 It was formerly used to toggle a debugging mode.
1348 Does not have any tail arguments.
1350 Document date for display in the page footer.
1351 This is the mandatory first macro of any
1354 Its syntax is as follows:
1356 .D1 Pf \. Sx \&Dd Ar month day , year
1360 is the full English month name, the
1362 is an integer number, and the
1364 is the full four-digit year.
1366 Other arguments are not portable; the
1368 utility handles them as follows:
1369 .Bl -dash -offset 3n -compact
1371 To have the date automatically filled in by the
1377 can be given as an argument.
1379 The traditional, purely numeric
1382 .Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day
1385 If a date string cannot be parsed, it is used verbatim.
1387 If no date string is given, the current date is used.
1391 .Dl \&.Dd $\&Mdocdate$
1392 .Dl \&.Dd $\&Mdocdate: July 2 2018$
1393 .Dl \&.Dd July 2, 2018
1400 One-line indented display.
1401 This is formatted as literal text and is useful for commands and
1403 It is followed by a newline.
1406 .Dl \&.Dl % mandoc mdoc.5 \e(ba less
1415 Begin a block enclosed by double quotes.
1416 Does not have any head arguments.
1419 .Bd -literal -offset indent -compact
1421 April is the cruellest month
1429 Encloses its arguments in
1434 .Bd -literal -offset indent -compact
1435 \&.Dq April is the cruellest month
1445 Document title for display in the page header.
1446 This is the mandatory second macro of any
1449 Its syntax is as follows:
1450 .Bd -ragged -offset indent
1457 Its arguments are as follows:
1458 .Bl -tag -width section -offset 2n
1460 The document's title (name), defaulting to
1463 To achieve a uniform appearance of page header lines,
1464 it should by convention be all caps.
1467 It should correspond to the manual's filename suffix and defaults to
1468 the empty string if unspecified.
1469 This field is optional.
1470 To achieve a uniform appearance of page header lines,
1471 it should by convention be all caps.
1473 This specifies the machine architecture a manual page applies to,
1477 Defined variables such as preprocessor constants, constant symbols,
1478 enumeration values, and so on.
1483 .Dl \&.Dv STDOUT_FILENO
1489 for special-purpose constants,
1491 for variable symbols, and
1493 for listing preprocessor variable definitions in the
1498 version provided as an argument, or a default
1499 value if no argument is provided.
1514 Close a scope started by
1516 Its syntax is as follows:
1518 .D1 Pf \. Sx \&Ec Op Ar TERM
1522 argument is used as the enclosure tail, for example, specifying \e(rq
1526 End a display context started by
1529 End a font mode context started by
1532 End a keep context started by
1535 End a list context started by
1543 Request an italic font.
1544 If the output device does not provide that, underline.
1546 This is most often used for stress emphasis (not to be confused with
1549 In the rare cases where none of the semantic markup macros fit,
1550 it can also be used for technical terms and placeholders, except
1551 that for syntax elements,
1555 are preferred, respectively.
1558 .Bd -literal -compact -offset indent
1559 Selected lines are those
1561 matching any of the specified patterns.
1562 Some of the functions use a
1564 to save the pattern space for subsequent retrieval.
1574 This macro is obsolete.
1577 or any of the other enclosure macros.
1579 It encloses its argument in the delimiters specified by the last
1583 An arbitrary enclosure.
1584 Its syntax is as follows:
1586 .D1 Pf \. Sx \&Eo Op Ar TERM
1590 argument is used as the enclosure head, for example, specifying \e(lq
1594 Error constants for definitions of the
1596 libc global variable.
1597 This is most often used in section 2 and 3 manual pages.
1605 for general constants.
1607 This macro is obsolete.
1610 or any of the other enclosure macros.
1612 It takes two arguments, defining the delimiters to be used by subsequent
1616 Environmental variables such as those specified in
1625 for general constants.
1627 Insert a standard sentence regarding command exit values of 0 on success
1629 This is most often used in section 1 and 1M manual pages.
1630 Its syntax is as follows:
1632 .D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
1636 is not specified, the document's name set by
1641 arguments are treated as separate utilities.
1646 Function argument or parameter.
1647 Its syntax is as follows:
1648 .Bd -ragged -offset indent
1656 Each argument may be a name and a type (recommended for the
1658 section), a name alone (for function invocations),
1659 or a type alone (for function prototypes).
1660 If both a type and a name are given or if the type consists of multiple
1661 words, all words belonging to the same function argument have to be
1662 given in a single argument to the
1666 This macro is also used to specify the field name of a structure.
1670 macro is used in the
1674 blocks when documenting multi-line function prototypes.
1675 If invoked with multiple arguments, the arguments are separated by a
1677 Furthermore, if the following macro is another
1679 the last argument will also have a trailing comma.
1682 .Dl \&.Fa \(dqconst char *p\(dq
1683 .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
1684 .Dl \&.Fa \(dqchar *\(dq size_t
1689 End a function context started by
1692 Preprocessor directive, in particular for listing it in the
1694 Historically, it was also used to document include files.
1695 The latter usage has been deprecated in favour of
1698 Its syntax is as follows:
1699 .Bd -ragged -offset indent
1701 .Li # Ns Ar directive
1706 .Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler
1707 .Dl \&.Fd #define SIO_MAXNFDS
1708 .Dl \&.Fd #ifdef FS_DEBUG
1710 .Dl \&.Fn dbg_open \(dqconst char *\(dq
1714 .Sx MANUAL STRUCTURE ,
1719 Command-line flag or option.
1720 Used when listing arguments to command-line utilities.
1721 Prints a fixed-width hyphen
1723 directly followed by each argument.
1724 If no arguments are provided, a hyphen is printed followed by a space.
1725 If the argument is a macro, a hyphen is prefixed to the subsequent macro
1729 .Dl ".Fl R Op Fl H | L | P"
1730 .Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
1731 .Dl ".Fl type Cm d Fl name Pa CVS"
1732 .Dl ".Fl Ar signal_number"
1739 Its syntax is as follows:
1740 .Bd -ragged -offset indent
1744 .Op Oo Ar argtype Oc Ar argname
1747 Function arguments are surrounded in parenthesis and
1748 are delimited by commas.
1749 If no arguments are specified, blank parenthesis are output.
1752 section, this macro starts a new output line,
1753 and a blank line is automatically inserted between function definitions.
1756 .Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
1757 .Dl \&.Fn funcname \(dqint arg0\(dq
1758 .Dl \&.Fn funcname arg0
1760 .Bd -literal -offset indent -compact
1765 When referring to a function documented in another manual page, use
1769 .Sx MANUAL STRUCTURE ,
1774 Begin a function block.
1775 This is a multi-line version of
1777 Its syntax is as follows:
1779 .D1 Pf \. Sx \&Fo Ar funcname
1781 Invocations usually occur in the following context:
1782 .Bd -ragged -offset indent
1783 .Pf \. Sx \&Ft Ar functype
1785 .Pf \. Sx \&Fo Ar funcname
1787 .Pf \. Sx \&Fa Qq Ar argtype Ar argname
1800 .Sx MANUAL STRUCTURE ,
1806 This macro is obsolete.
1807 No replacement markup is needed.
1809 It was used to show numerical function return values in an italic font.
1812 Its syntax is as follows:
1814 .D1 Pf \. Sx \&Ft Ar functype
1818 section, a new output line is started after this macro.
1822 .Bd -literal -offset indent -compact
1828 .Sx MANUAL STRUCTURE ,
1835 version provided as an argument, or a default value
1836 if no argument is provided.
1851 This macro is not implemented in
1854 It was used to include the contents of a (header) file literally.
1857 .Dl Pf . Sx \&Hf Ar filename
1859 Designate an internal or interactive command.
1862 but used for instructions rather than values.
1873 is preferred for displaying code; the
1875 macro is used when referring to specific instructions.
1877 The name of an include file.
1878 This macro is most often used in section 2, 3, and 9 manual pages.
1880 When invoked as the first macro on an input line in the
1882 section, the argument is displayed in angle brackets
1885 and a blank line is inserted in front if there is a preceding
1886 function declaration.
1887 In other sections, it only encloses its argument in angle brackets
1888 and causes no line break.
1891 .Dl \&.In sys/types.h
1894 .Sx MANUAL STRUCTURE .
1897 The syntax of this macro depends on the list type.
1906 have the following syntax:
1908 .D1 Pf \. Sx \&It Ar args
1917 have the following syntax:
1921 with subsequent lines interpreted within the scope of the
1923 until either a closing
1930 list has the following syntax:
1932 .D1 Pf \. Sx \&It Op Cm args
1934 Subsequent lines are interpreted as with
1937 The line arguments correspond to the list's left-hand side; body
1938 arguments correspond to the list's contents.
1942 list is the most complicated.
1943 Its syntax is as follows:
1945 .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
1946 .D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
1948 The arguments consist of one or more lines of text and macros
1949 representing a complete table line.
1950 Cells within the line are delimited by the special
1952 block macro or by literal tab characters.
1954 Using literal tabs is strongly discouraged because they are very
1955 hard to use correctly and
1957 code using them is very hard to read.
1958 In particular, a blank character is syntactically significant
1959 before and after the literal tab character.
1960 If a word precedes or follows the tab without an intervening blank,
1961 that word is never interpreted as a macro call, but always output
1964 The tab cell delimiter may only be used within the
1966 line itself; on following lines, only the
1968 macro can be used to delimit cells, and portability requires that
1970 is called by other macros: some parsers do not recognize it when
1971 it appears as the first macro on a line.
1973 Note that quoted strings may span tab-delimited cells on an
1978 .Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&;
1980 will preserve the whitespace before both commas,
1981 but not the whitespace before the semicolon.
1987 The syntax is as follows:
1989 .D1 Pf \. Sx \&Lb Ar library
1993 parameter may be a system library, such as
1997 in which case a small library description is printed next to the linker
1998 invocation; or a custom library, in which case the library name is
2000 This is most commonly used in the
2002 section as described in
2003 .Sx MANUAL STRUCTURE .
2009 Denotes text that should be in a
2012 Note that this is a presentation term and should not be used for
2013 stylistically decorating technical terms.
2015 On terminal output devices, this is often indistinguishable from
2026 Its syntax is as follows:
2028 .D1 Pf \. Sx \&Lk Ar uri Op Ar name
2031 .Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
2032 .Dl \&.Lk http://bsd.lv
2040 Display a mathematical symbol.
2041 Its syntax is as follows:
2043 .D1 Pf \. Sx \&Ms Ar symbol
2052 Its syntax is as follows:
2054 .D1 Pf \. Sx \&Mt Ar address
2057 .Dl \&.Mt discuss@manpages.bsd.lv
2058 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
2060 A one line description of the manual's content.
2061 This is the mandatory last macro of the
2063 section and not appropriate for other sections.
2066 .Dl Pf . Sx \&Nd mdoc language reference
2067 .Dl Pf . Sx \&Nd format and display UNIX manuals
2071 macro technically accepts child macros and terminates with a subsequent
2074 Do not assume this behaviour: some
2076 database generators are not smart enough to parse more than the line
2077 arguments and will display macros verbatim.
2082 The name of the manual page, or \(em in particular in section 1
2083 pages \(em of an additional command or feature documented in
2085 When first invoked, the
2087 macro expects a single argument, the name of the manual page.
2088 Usually, the first invocation happens in the
2090 section of the page.
2091 The specified name will be remembered and used whenever the macro is
2092 called again without arguments later in the page.
2096 .Sx Block full-implicit
2097 semantics when invoked as the first macro on an input line in the
2099 section; otherwise, it uses ordinary
2104 .Bd -literal -offset indent
2113 of section 2, 3 and 9 manual pages, use the
2117 to mark up the name of the manual page.
2120 Closes the scope of any preceding in-line macro.
2121 When used after physical formatting macros like
2125 switches back to the standard font face and weight.
2126 Can also be used to embed plain text strings in macro lines
2127 using semantic annotation macros.
2130 .Dl ".Em italic , Sy bold , No and roman"
2132 .Bd -literal -offset indent -compact
2134 \&.Cm :C No / Ar pattern No / Ar replacement No /
2144 Suppress a space between the output of the preceding macro
2145 and the following text or macro.
2146 Following invocation, input is interpreted as normal text
2151 This has no effect when invoked at the start of a macro line.
2154 .Dl ".Ar name Ns = Ns Ar value"
2155 .Dl ".Cm :M Ns Ar pattern"
2156 .Dl ".Fl o Ns Ar output"
2165 version provided as an argument, or a default value if
2166 no argument is provided.
2185 Multi-line version of
2189 .Bd -literal -offset indent -compact
2191 \&.Op Fl flag Ns Ar value
2195 Optional part of a command line.
2196 Prints the argument(s) in brackets.
2197 This is most often used in the
2199 section of section 1 and 1M manual pages.
2202 .Dl \&.Op \&Fl a \&Ar b
2203 .Dl \&.Op \&Ar a | b
2208 Operating system version for display in the page footer.
2209 This is the mandatory third macro of
2213 Its syntax is as follows:
2215 .D1 Pf \. Sx \&Os Op Ar system Op Ar version
2219 parameter specifies the relevant operating system or environment.
2220 It is suggested to leave it unspecified, in which case
2224 argument or, if that isn't specified either,
2233 .Dl \&.Os KTH/CSC/TCS
2241 This macro is obsolete.
2246 both have the same effect.
2250 packages described it as
2251 .Dq "old function type (FORTRAN)" .
2255 version provided as an argument, or a default value
2256 if no argument is provided.
2271 An absolute or relative file system path, or a file or directory name.
2272 If an argument is not provided, the character
2274 is used as a default.
2277 .Dl \&.Pa /usr/bin/mandoc
2278 .Dl \&.Pa /usr/share/man/man5/mdoc.5
2283 Close parenthesised context opened by
2286 Removes the space between its argument and the following macro.
2287 Its syntax is as follows:
2289 .D1 .Pf Ar prefix macro arguments ...
2291 This is equivalent to:
2293 .D1 .No \e& Ns Ar prefix No \&Ns Ar macro arguments ...
2297 argument is not parsed for macro names or delimiters,
2298 but used verbatim as if it were escaped.
2301 .Dl ".Pf $ Ar variable_name"
2302 .Dl ".Pf . Ar macro_name"
2303 .Dl ".Pf 0x Ar hex_digits"
2310 Multi-line version of
2314 This will assert vertical space between prior and subsequent macros
2317 Paragraph breaks are not needed before or after
2321 macros or before displays
2329 Parenthesised enclosure.
2334 Close quoted context opened by
2337 In-line literal display.
2338 This can for example be used for complete command invocations and
2339 for multi-word code fragments when more specific markup is not
2340 appropriate and an indented display is not desired.
2343 always encloses the arguments in single quotes, other formatters
2344 usually omit the quotes on non-terminal output devices when the
2345 arguments have three or more characters.
2353 Multi-line version of
2356 Encloses its arguments in
2371 Does not have any tail arguments.
2373 Begin a bibliographic
2376 Does not have any head arguments.
2377 The block macro may only contain
2393 child macros (at least one must be specified).
2396 .Bd -literal -offset indent -compact
2398 \&.%A J. E. Hopcroft
2400 \&.%B Introduction to Automata Theory, Languages, and Computation
2401 \&.%I Addison-Wesley
2402 \&.%C Reading, Massachusetts
2409 block is used within a SEE ALSO section, a vertical space is asserted
2410 before the rendered output, else the block continues on the current
2413 Insert a standard sentence regarding a function call's return value of 0
2414 on success and \-1 on error, with the
2416 libc global variable set on error.
2417 Its syntax is as follows:
2419 .D1 Pf \. Sx \&Rv Fl std Op Ar function ...
2423 is not specified, the document's name set by
2428 arguments are treated as separate functions.
2433 Close single-quoted context opened by
2436 Begin a new section.
2437 For a list of conventional manual sections, see
2438 .Sx MANUAL STRUCTURE .
2439 These sections should be used unless it's absolutely necessary that
2440 custom sections be used.
2442 Section names should be unique so that they may be keyed by
2444 Although this macro is parsed, it should not consist of child node or it
2445 may not be linked with
2454 Switches the spacing mode for output generated from macros.
2455 Its syntax is as follows:
2457 .D1 Pf \. Sx \&Sm Op Cm on | off
2459 By default, spacing is
2463 no white space is inserted between macro arguments and between the
2464 output generated from adjacent macros, but text lines
2465 still get normal spacing between words and sentences.
2467 When called without an argument, the
2469 macro toggles the spacing mode.
2470 Using this is not recommended because it makes the code harder to read.
2472 Multi-line version of
2475 Encloses its arguments in
2485 Begin a new subsection.
2488 there is no convention for the naming of subsections.
2491 the conventional sections described in
2492 .Sx MANUAL STRUCTURE
2493 rarely have subsections.
2495 Sub-section names should be unique so that they may be keyed by
2497 Although this macro is parsed, it should not consist of child node or it
2498 may not be linked with
2507 Replace an abbreviation for a standard with the full form.
2508 The following standards are recognised.
2509 Where multiple lines are given without a blank line in between,
2510 they all refer to the same standard, and using the first form
2513 .It C language standards
2515 .Bl -tag -width "-p1003.1g-2000" -compact
2525 The original C standard.
2539 The second major version of the C language standard.
2544 The third major version of the C language standard.
2546 .It POSIX.1 before the Single UNIX Specification
2548 .Bl -tag -width "-p1003.1g-2000" -compact
2554 The original POSIX standard, based on ANSI C.
2561 The first update of POSIX.1.
2568 Real-time extensions.
2573 POSIX thread interfaces.
2578 Technical Corrigendum.
2585 Includes POSIX.1-1990, 1b, 1c, and 1i.
2587 .It X/Open Portability Guide version 4 and related standards
2589 .Bl -tag -width "-p1003.1g-2000" -compact
2593 An XPG4 precursor, published in 1989.
2612 Based on POSIX.1 and POSIX.2, published in 1992.
2614 .It Single UNIX Specification version 1 and related standards
2616 .Bl -tag -width "-p1003.1g-2000" -compact
2622 This standard was published in 1994.
2623 It was used as the basis for UNIX 95 certification.
2624 The following three refer to parts of it.
2635 Networking APIs, including sockets.
2642 .It Single UNIX Specification version 2 and related standards
2644 .Bl -tag -width "-p1003.1g-2000" -compact
2647 This Standard was published in 1997
2648 and is also called X/Open Portability Guide version 5.
2649 It was used as the basis for UNIX 98 certification.
2650 The following refer to parts of it.
2666 .It Single UNIX Specification version 3
2668 .Bl -tag -width "-p1003.1-2001" -compact
2674 This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j.
2675 It is also called X/Open Portability Guide version 6.
2676 It is used as the basis for UNIX 03 certification.
2681 The second and last Technical Corrigendum.
2683 .It Single UNIX Specification version 4
2685 .Bl -tag -width "-p1003.1g-2000" -compact
2691 This standard is also called
2692 X/Open Portability Guide version 7.
2696 .Bl -tag -width "-p1003.1g-2000" -compact
2700 Floating-point arithmetic.
2705 Representation of dates and times, published in 1988.
2710 Ethernet local area networks.
2717 Reference a section or subsection in the same manual page.
2718 The referenced section or subsection name must be identical to the
2719 enclosed argument, including whitespace.
2722 .Dl \&.Sx MANUAL STRUCTURE
2729 Request a boldface font.
2731 This is most often used to indicate importance or seriousness (not to be
2732 confused with stress emphasis, see
2734 When none of the semantic macros fit, it is also adequate for syntax
2735 elements that have to be given or that appear verbatim.
2738 .Bd -literal -compact -offset indent
2742 appears in the owner permissions, set-user-ID mode is set.
2743 This utility replaces the former
2755 Table cell separator in
2757 lists; can only be used below
2760 Supported only for compatibility, do not use this in new manuals.
2761 Even though the macro name
2763 suggests a semantic function, historic usage is inconsistent, mostly
2764 using it as a presentation-level macro to request a small caps font.
2766 Supported only for compatibility, do not use this in new manuals.
2768 .Dq currently under development.
2770 Supported only for compatibility, do not use this in new manuals.
2778 .Dl \&.Va const char *bar ;
2780 For function arguments and parameters, use
2783 For declarations of global variables in the
2790 This is also used for indicating global variables in the
2792 section, in which case a variable name is also specified.
2793 Note that it accepts
2794 .Sx Block partial-implicit
2795 syntax when invoked as the first macro on an input line in the
2797 section, else it accepts ordinary
2800 In the former case, this macro starts a new output line,
2801 and a blank line is inserted in front if there is a preceding
2802 function definition or include directive.
2805 .Dl \&.Vt unsigned char
2806 .Dl \&.Vt extern const char * const sys_signame[] \&;
2808 For parameters in function prototypes, use
2810 instead, for function return types
2812 and for variable names outside the
2816 even when including a type with the name.
2818 .Sx MANUAL STRUCTURE .
2820 Close a scope opened by
2823 Extend the header of an
2825 macro or the body of a partial-implicit block macro
2826 beyond the end of the input line.
2827 This macro originally existed to work around the 9-argument limit
2831 Link to another manual
2832 .Pq Qq cross-reference .
2833 Its syntax is as follows:
2835 .D1 Pf \. Sx \&Xr Ar name section
2841 number of another man page.
2845 .Dl \&.Xr mandoc 1 \&;
2846 .Dl \&.Xr mandoc 1 \&Ns s behaviour
2848 The syntax of a macro depends on its classification.
2851 refers to macro arguments, which may be followed by zero or more
2855 opens the scope of a macro; and if specified,
2861 column indicates that the macro may also be called by passing its name
2862 as an argument to another macro.
2864 .Sq \&.Op \&Fl O \&Ar file
2866 .Sq Op Fl O Ar file .
2867 To prevent a macro call and render the macro name literally,
2868 escape it by prepending a zero-width space,
2874 If a macro is not callable but its name appears as an argument
2875 to another macro, it is interpreted as opaque text.
2883 column indicates whether the macro may call other macros by receiving
2884 their names as arguments.
2885 If a macro is not parsed but the name of another macro appears
2886 as an argument, it is interpreted as opaque text.
2890 column, if applicable, describes closure rules.
2891 .Ss Block full-explicit
2892 Multi-line scope closed by an explicit closing macro.
2893 All macros contains bodies; only
2899 .Bd -literal -offset indent
2900 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2904 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
2905 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2906 .It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
2907 .It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
2908 .It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
2909 .It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
2910 .It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
2911 .It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
2912 .It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
2913 .It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
2915 .Ss Block full-implicit
2916 Multi-line scope closed by end-of-file or implicitly by another macro.
2917 All macros have bodies; some
2919 .Sx \&It Fl bullet ,
2925 don't have heads; only one
2932 .Bd -literal -offset indent
2933 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
2936 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
2937 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2938 .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
2939 .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
2940 .It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
2941 .It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh
2942 .It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss
2948 .Sx Block full-implicit
2949 macro only when invoked as the first macro
2952 section line, else it is
2954 .Ss Block partial-explicit
2955 Like block full-explicit, but also with single-line scope.
2956 Each has at least a body and, in limited circumstances, a head
2963 .Bd -literal -offset indent
2964 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2966 \&.Yc \(lBtail...\(rB
2968 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
2969 \(lBbody...\(rB \&Yc \(lBtail...\(rB
2971 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
2972 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2973 .It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
2974 .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
2975 .It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
2976 .It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
2977 .It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
2978 .It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
2979 .It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
2980 .It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
2981 .It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
2982 .It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
2983 .It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
2984 .It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
2985 .It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
2986 .It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
2987 .It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
2988 .It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
2989 .It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
2990 .It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
2991 .It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
2992 .It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
2993 .It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
2994 .It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
2995 .It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
2996 .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
2998 .Ss Block partial-implicit
2999 Like block full-implicit, but with single-line scope closed by the
3001 .Bd -literal -offset indent
3002 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
3004 .Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
3005 .It Em Macro Ta Em Callable Ta Em Parsed
3006 .It Sx \&Aq Ta Yes Ta Yes
3007 .It Sx \&Bq Ta Yes Ta Yes
3008 .It Sx \&Brq Ta Yes Ta Yes
3009 .It Sx \&D1 Ta \&No Ta \&Yes
3010 .It Sx \&Dl Ta \&No Ta Yes
3011 .It Sx \&Dq Ta Yes Ta Yes
3012 .It Sx \&En Ta Yes Ta Yes
3013 .It Sx \&Op Ta Yes Ta Yes
3014 .It Sx \&Pq Ta Yes Ta Yes
3015 .It Sx \&Ql Ta Yes Ta Yes
3016 .It Sx \&Qq Ta Yes Ta Yes
3017 .It Sx \&Sq Ta Yes Ta Yes
3018 .It Sx \&Vt Ta Yes Ta Yes
3024 .Sx Block partial-implicit
3025 only when invoked as the first macro
3028 section line, else it is
3030 .Ss Special block macro
3033 macro can only be used below
3038 It delimits blocks representing table cells;
3039 these blocks have bodies, but no heads.
3040 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
3041 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
3042 .It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It
3045 Closed by the end of the line, fixed argument lengths,
3046 and/or subsequent macros.
3047 In-line macros have only text children.
3048 If a number (or inequality) of arguments is
3050 then the macro accepts an arbitrary number of arguments.
3051 .Bd -literal -offset indent
3052 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
3054 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
3056 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
3058 .Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
3059 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
3060 .It Sx \&%A Ta \&No Ta \&No Ta >0
3061 .It Sx \&%B Ta \&No Ta \&No Ta >0
3062 .It Sx \&%C Ta \&No Ta \&No Ta >0
3063 .It Sx \&%D Ta \&No Ta \&No Ta >0
3064 .It Sx \&%I Ta \&No Ta \&No Ta >0
3065 .It Sx \&%J Ta \&No Ta \&No Ta >0
3066 .It Sx \&%N Ta \&No Ta \&No Ta >0
3067 .It Sx \&%O Ta \&No Ta \&No Ta >0
3068 .It Sx \&%P Ta \&No Ta \&No Ta >0
3069 .It Sx \&%Q Ta \&No Ta \&No Ta >0
3070 .It Sx \&%R Ta \&No Ta \&No Ta >0
3071 .It Sx \&%T Ta \&No Ta \&No Ta >0
3072 .It Sx \&%U Ta \&No Ta \&No Ta >0
3073 .It Sx \&%V Ta \&No Ta \&No Ta >0
3074 .It Sx \&Ad Ta Yes Ta Yes Ta >0
3075 .It Sx \&An Ta Yes Ta Yes Ta >0
3076 .It Sx \&Ap Ta Yes Ta Yes Ta 0
3077 .It Sx \&Ar Ta Yes Ta Yes Ta n
3078 .It Sx \&At Ta Yes Ta Yes Ta 1
3079 .It Sx \&Bsx Ta Yes Ta Yes Ta n
3080 .It Sx \&Bt Ta \&No Ta \&No Ta 0
3081 .It Sx \&Bx Ta Yes Ta Yes Ta n
3082 .It Sx \&Cd Ta Yes Ta Yes Ta >0
3083 .It Sx \&Cm Ta Yes Ta Yes Ta >0
3084 .It Sx \&Db Ta \&No Ta \&No Ta 1
3085 .It Sx \&Dd Ta \&No Ta \&No Ta n
3086 .It Sx \&Dt Ta \&No Ta \&No Ta n
3087 .It Sx \&Dv Ta Yes Ta Yes Ta >0
3088 .It Sx \&Dx Ta Yes Ta Yes Ta n
3089 .It Sx \&Em Ta Yes Ta Yes Ta >0
3090 .It Sx \&Er Ta Yes Ta Yes Ta >0
3091 .It Sx \&Es Ta Yes Ta Yes Ta 2
3092 .It Sx \&Ev Ta Yes Ta Yes Ta >0
3093 .It Sx \&Ex Ta \&No Ta \&No Ta n
3094 .It Sx \&Fa Ta Yes Ta Yes Ta >0
3095 .It Sx \&Fd Ta \&No Ta \&No Ta >0
3096 .It Sx \&Fl Ta Yes Ta Yes Ta n
3097 .It Sx \&Fn Ta Yes Ta Yes Ta >0
3098 .It Sx \&Fr Ta Yes Ta Yes Ta >0
3099 .It Sx \&Ft Ta Yes Ta Yes Ta >0
3100 .It Sx \&Fx Ta Yes Ta Yes Ta n
3101 .It Sx \&Hf Ta \&No Ta \&No Ta n
3102 .It Sx \&Ic Ta Yes Ta Yes Ta >0
3103 .It Sx \&In Ta \&No Ta \&No Ta 1
3104 .It Sx \&Lb Ta \&No Ta \&No Ta 1
3105 .It Sx \&Li Ta Yes Ta Yes Ta >0
3106 .It Sx \&Lk Ta Yes Ta Yes Ta >0
3107 .It Sx \&Lp Ta \&No Ta \&No Ta 0
3108 .It Sx \&Ms Ta Yes Ta Yes Ta >0
3109 .It Sx \&Mt Ta Yes Ta Yes Ta >0
3110 .It Sx \&Nm Ta Yes Ta Yes Ta n
3111 .It Sx \&No Ta Yes Ta Yes Ta 0
3112 .It Sx \&Ns Ta Yes Ta Yes Ta 0
3113 .It Sx \&Nx Ta Yes Ta Yes Ta n
3114 .It Sx \&Os Ta \&No Ta \&No Ta n
3115 .It Sx \&Ot Ta Yes Ta Yes Ta >0
3116 .It Sx \&Ox Ta Yes Ta Yes Ta n
3117 .It Sx \&Pa Ta Yes Ta Yes Ta n
3118 .It Sx \&Pf Ta Yes Ta Yes Ta 1
3119 .It Sx \&Pp Ta \&No Ta \&No Ta 0
3120 .It Sx \&Rv Ta \&No Ta \&No Ta n
3121 .It Sx \&Sm Ta \&No Ta \&No Ta <2
3122 .It Sx \&St Ta \&No Ta Yes Ta 1
3123 .It Sx \&Sx Ta Yes Ta Yes Ta >0
3124 .It Sx \&Sy Ta Yes Ta Yes Ta >0
3125 .It Sx \&Tn Ta Yes Ta Yes Ta >0
3126 .It Sx \&Ud Ta \&No Ta \&No Ta 0
3127 .It Sx \&Ux Ta Yes Ta Yes Ta n
3128 .It Sx \&Va Ta Yes Ta Yes Ta n
3129 .It Sx \&Vt Ta Yes Ta Yes Ta >0
3130 .It Sx \&Xr Ta Yes Ta Yes Ta 2
3133 When a macro argument consists of one single input character
3134 considered as a delimiter, the argument gets special handling.
3135 This does not apply when delimiters appear in arguments containing
3136 more than one character.
3137 Consequently, to prevent special handling and just handle it
3138 like any other argument, a delimiter can be escaped by prepending
3141 In text lines, delimiters never need escaping, but may be used
3142 as normal punctuation.
3144 For many macros, when the leading arguments are opening delimiters,
3145 these delimiters are put before the macro scope,
3146 and when the trailing arguments are closing delimiters,
3147 these delimiters are put after the macro scope.
3148 Spacing is suppressed after opening delimiters
3149 and before closing delimiters.
3152 .D1 Pf \. \&Aq "( [ word ] ) ."
3156 .D1 Aq ( [ word ] ) .
3158 Opening delimiters are:
3160 .Bl -tag -width Ds -offset indent -compact
3167 Closing delimiters are:
3169 .Bl -tag -width Ds -offset indent -compact
3188 Note that even a period preceded by a backslash
3190 gets this special handling; use
3194 Many in-line macros interrupt their scope when they encounter
3195 delimiters, and resume their scope when more arguments follow that
3199 .D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e"
3203 .D1 Fl a ( b | c \*(Ba d ) e
3205 This applies to both opening and closing delimiters,
3206 and also to the middle delimiter, which does not suppress spacing:
3208 .Bl -tag -width Ds -offset indent -compact
3213 As a special case, the predefined string \e*(Ba is handled and rendered
3214 in the same way as a plain
3217 Using this predefined string is not recommended in new manuals.
3221 documents, usage of semantic markup is recommended in order to have
3222 proper fonts automatically selected; only when no fitting semantic markup
3223 is available, consider falling back to
3230 font mode, it will automatically restore the previous font when exiting
3232 Manually switching the font using the
3235 font escape sequences is never required.
3237 This section provides an incomplete list of compatibility issues
3238 between mandoc and GNU troff
3241 The following problematic behaviour is found in groff:
3246 with non-standard arguments behaves very strangely.
3247 When there are three arguments, they are printed verbatim.
3248 Any other number of arguments is replaced by the current date,
3249 but without any arguments the string
3254 only accepts a single link-name argument; the remainder is misformatted.
3257 does not format its arguments when used in the FILES section under
3261 can only be called by other macros, but not at the beginning of a line.
3264 is not implemented (up to and including groff-1.22.2).
3270 .Pq font family face
3272 escapes behave irregularly when specified within line-macro scopes.
3274 Negative scaling units return to prior lines.
3275 Instead, mandoc truncates them to zero.
3278 The following features are unimplemented in mandoc:
3284 is unsupported for security reasons.
3288 does not adjust the right margin, but is an alias for
3294 does not use a literal font, but is an alias for
3299 .Fl offset Cm center
3303 Groff does not implement centered and flush-right rendering either,
3304 but produces large indentations.
3316 .Lk http://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language"
3317 provides a few tutorial-style pages for beginners, an extensive style
3318 guide for advanced authors, and an alphabetic index helping to choose
3319 the best macros for various kinds of content.
3323 language first appeared as a troff macro package in
3325 It was later significantly updated by Werner Lemberg and Ruslan Ermilov
3327 The standalone implementation that is part of the
3329 utility written by Kristaps Dzonsons appeared in
3334 reference was written by
3335 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .