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.
18 .Dd $Mdocdate: July 28 2018 $
23 .Nd semantic markup language for formatting manual pages
27 language supports authoring of manual pages for the
29 utility by allowing semantic annotations of words, phrases,
30 page sections and complete manual pages.
31 Such annotations are used by formatting tools to achieve a uniform
32 presentation across all manuals written in
34 and to support hyperlinking if supported by the output medium.
36 This reference document describes the structure of manual pages
37 and the syntax and usage of the
40 The reference implementation of a parsing and formatting tool is
44 section describes compatibility with other implementations.
48 document, lines beginning with the control character
52 The first word is the macro name.
53 It consists of two or three letters.
54 Most macro names begin with a capital letter.
55 For a list of available macros, see
57 The words following the macro name are arguments to the macro, optionally
58 including the names of other, callable macros; see
62 Lines not beginning with the control character are called
64 They provide free-form text to be printed; the formatting of the text
65 depends on the respective processing context:
66 .Bd -literal -offset indent
67 \&.Sh Macro lines change control state.
68 Text lines are interpreted within the current state.
71 Many aspects of the basic syntax of the
73 language are based on the
81 manual for details, in particular regarding
82 comments, escape sequences, whitespace, and quoting.
87 documents is discouraged;
89 supports some of them merely for backward compatibility.
93 document consists of a document prologue followed by one or more
96 The prologue, which consists of the
101 macros in that order, is required for every document.
103 The first section (sections are denoted by
105 must be the NAME section, consisting of at least one
110 Following that, convention dictates specifying at least the
114 sections, although this varies between manual sections.
116 The following is a well-formed skeleton
120 .Bd -literal -offset indent
122 \&.Dt PROGNAME section
126 \&.Nd one line about what it does
127 \&.\e\(dq .Sh LIBRARY
128 \&.\e\(dq For sections 2, 3, and 9 only.
129 \&.\e\(dq Not used in OpenBSD.
137 utility processes files ...
138 \&.\e\(dq .Sh CONTEXT
139 \&.\e\(dq For section 9 functions only.
140 \&.\e\(dq .Sh IMPLEMENTATION NOTES
141 \&.\e\(dq Not used in OpenBSD.
142 \&.\e\(dq .Sh RETURN VALUES
143 \&.\e\(dq For sections 2, 3, and 9 function return values only.
144 \&.\e\(dq .Sh ENVIRONMENT
145 \&.\e\(dq For sections 1, 6, 7, and 8 only.
147 \&.\e\(dq .Sh EXIT STATUS
148 \&.\e\(dq For sections 1, 6, and 8 only.
149 \&.\e\(dq .Sh EXAMPLES
150 \&.\e\(dq .Sh DIAGNOSTICS
151 \&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
153 \&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
154 \&.\e\(dq .Sh SEE ALSO
155 \&.\e\(dq .Xr foobar 1
156 \&.\e\(dq .Sh STANDARDS
157 \&.\e\(dq .Sh HISTORY
158 \&.\e\(dq .Sh AUTHORS
159 \&.\e\(dq .Sh CAVEATS
161 \&.\e\(dq .Sh SECURITY CONSIDERATIONS
162 \&.\e\(dq Not used in OpenBSD.
167 document are conventionally ordered as they appear above.
168 Sections should be composed as follows:
169 .Bl -ohang -offset Ds
171 The name(s) and a one line description of the documented material.
172 The syntax for this as follows:
173 .Bd -literal -offset indent
177 \&.Nd a one line description
182 names should be separated by commas.
186 macro(s) must precede the
195 The name of the library containing the documented material, which is
196 assumed to be a function in a section 2, 3, or 9 manual.
197 The syntax for this is as follows:
198 .Bd -literal -offset indent
205 Documents the utility invocation syntax, function call syntax, or device
208 For the first, utilities (sections 1, 6, and 8), this is
209 generally structured as follows:
210 .Bd -literal -offset indent
221 Commands should be ordered alphabetically.
223 For the second, function calls (sections 2, 3, 9):
224 .Bd -literal -offset indent
226 \&.Vt extern const char *global;
228 \&.Fn foo "const char *src"
230 \&.Fn bar "const char *src"
239 macros should follow C header-file conventions.
241 And for the third, configurations (section 4):
242 .Bd -literal -offset indent
243 \&.Cd \(dqit* at isa? port 0x2e\(dq
244 \&.Cd \(dqit* at isa? port 0x4e\(dq
247 Manuals not in these sections generally don't need a
250 Some macros are displayed differently in the
252 section, particularly
262 All of these macros are output on their own line.
263 If two such dissimilar macros are pairwise invoked (except for
269 they are separated by a vertical space, unless in the case of
274 which are always separated by vertical space.
276 When text and macros following an
278 macro starting an input line span multiple output lines,
279 all output lines but the first will be indented to align
280 with the text immediately following the
282 macro, up to the next
287 macro or the end of an enclosing block, whichever comes first.
289 This begins with an expansion of the brief, one line description in
291 .Bd -literal -offset indent
294 utility does this, that, and the other.
297 It usually follows with a breakdown of the options (if documenting a
299 .Bd -literal -offset indent
300 The arguments are as follows:
301 \&.Bl \-tag \-width Ds
303 Print verbose information.
307 List the options in alphabetical order,
308 uppercase before lowercase for each letter and
309 with no regard to whether an option takes an argument.
310 Put digits in ascending order before all letter options.
312 Manuals not documenting a command won't include the above fragment.
316 section usually contains most of the text of a manual, longer manuals
319 macro to form subsections.
320 In very long manuals, the
322 may be split into multiple sections, each started by an
324 macro followed by a non-standard section name, and each having
325 several subsections, like in the present
329 This section lists the contexts in which functions can be called in section 9.
330 The contexts are autoconf, process, or interrupt.
331 .It Em IMPLEMENTATION NOTES
332 Implementation-specific notes should be kept here.
333 This is useful when implementing standard functions that may have side
334 effects or notable algorithmic implications.
336 This section documents the
337 return values of functions in sections 2, 3, and 9.
342 Lists the environment variables used by the utility,
343 and explains the syntax and semantics of their values.
346 manual provides examples of typical content and formatting.
351 Documents files used.
352 It's helpful to document both the file name and a short description of how
353 the file is used (created, modified, etc.).
358 This section documents the
359 command exit status for section 1, 6, and 8 utilities.
360 Historically, this information was described in
362 a practise that is now discouraged.
368 This often contains snippets of well-formed, well-tested invocations.
369 Make sure that examples work properly!
371 Documents error messages.
372 In section 4 and 9 manuals, these are usually messages printed by the
373 kernel to the console and to the kernel log.
374 In section 1, 6, 7, and 8, these are usually messages printed by
375 userland programs to the standard error output.
377 Historically, this section was used in place of
379 for manuals in sections 1, 6, and 8; however, this practise is
388 settings in sections 2, 3, 4, and 9.
393 References other manuals with related topics.
394 This section should exist for most manuals.
395 Cross-references should conventionally be ordered first by section, then
396 alphabetically (ignoring case).
398 References to other documentation concerning the topic of the manual page,
399 for example authoritative books or journal articles, may also be
400 provided in this section.
407 References any standards implemented or used.
408 If not adhering to any standards, the
410 section should be used instead.
415 A brief history of the subject, including where it was first implemented,
416 and when it was ported to or reimplemented for the operating system at hand.
418 Credits to the person or persons who wrote the code and/or documentation.
419 Authors should generally be noted by both name and email address.
424 Common misuses and misunderstandings should be explained
427 Known bugs, limitations, and work-arounds should be described
429 .It Em SECURITY CONSIDERATIONS
430 Documents any security precautions that operators should consider.
433 This overview is sorted such that macros of similar purpose are listed
434 together, to help find the best macro for any given purpose.
435 Deprecated macros are not included in the overview, but can be found below
437 .Sx MACRO REFERENCE .
438 .Ss Document preamble and NAME section macros
439 .Bl -column "Brq, Bro, Brc" description
440 .It Sx \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year
441 .It Sx \&Dt Ta document title: Ar TITLE section Op Ar arch
442 .It Sx \&Os Ta operating system version: Op Ar system Op Ar version
443 .It Sx \&Nm Ta document name (one argument)
444 .It Sx \&Nd Ta document description (one line)
446 .Ss Sections and cross references
447 .Bl -column "Brq, Bro, Brc" description
448 .It Sx \&Sh Ta section header (one line)
449 .It Sx \&Ss Ta subsection header (one line)
450 .It Sx \&Sx Ta internal cross reference to a section or subsection
451 .It Sx \&Xr Ta cross reference to another manual page: Ar name section
452 .It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments)
454 .Ss Displays and lists
455 .Bl -column "Brq, Bro, Brc" description
456 .It Sx \&Bd , \&Ed Ta display block:
458 .Op Fl offset Ar width
460 .It Sx \&D1 Ta indented display (one line)
461 .It Sx \&Dl Ta indented literal display (one line)
462 .It Sx \&Ql Ta in-line literal display: Ql text
463 .It Sx \&Bl , \&El Ta list block:
468 .It Sx \&It Ta list item (syntax depends on Fl Ar type )
469 .It Sx \&Ta Ta table cell separator in Sx \&Bl Fl column No lists
470 .It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references)
473 .Bl -column "Brq, Bro, Brc" description
474 .It Sx \&Pf Ta prefix, no following horizontal space (one argument)
475 .It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
476 .It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
477 .It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off
478 .It Sx \&Bk , \&Ek Ta keep block: Fl words
480 .Ss Semantic markup for command line utilities
481 .Bl -column "Brq, Bro, Brc" description
482 .It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility
483 .It Sx \&Fl Ta command line options (flags) (>=0 arguments)
484 .It Sx \&Cm Ta command modifier (>0 arguments)
485 .It Sx \&Ar Ta command arguments (>=0 arguments)
486 .It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure)
487 .It Sx \&Ic Ta internal or interactive command (>0 arguments)
488 .It Sx \&Ev Ta environmental variable (>0 arguments)
489 .It Sx \&Pa Ta file system path (>=0 arguments)
491 .Ss Semantic markup for function libraries
492 .Bl -column "Brq, Bro, Brc" description
493 .It Sx \&Lb Ta function library (one argument)
494 .It Sx \&In Ta include file (one argument)
495 .It Sx \&Fd Ta other preprocessor directive (>0 arguments)
496 .It Sx \&Ft Ta function type (>0 arguments)
497 .It Sx \&Fo , \&Fc Ta function block: Ar funcname
498 .It Sx \&Fn Ta function name:
505 .It Sx \&Fa Ta function argument (>0 arguments)
506 .It Sx \&Vt Ta variable type (>0 arguments)
507 .It Sx \&Va Ta variable name (>0 arguments)
508 .It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments)
509 .It Sx \&Er Ta error constant (>0 arguments)
510 .It Sx \&Ev Ta environmental variable (>0 arguments)
512 .Ss Various semantic markup
513 .Bl -column "Brq, Bro, Brc" description
514 .It Sx \&An Ta author name (>0 arguments)
515 .It Sx \&Lk Ta hyperlink: Ar uri Op Ar name
516 .It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address
517 .It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
518 .It Sx \&Ad Ta memory address (>0 arguments)
519 .It Sx \&Ms Ta mathematical symbol (>0 arguments)
522 .Bl -column "Brq, Bro, Brc" description
523 .It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments)
524 .It Sx \&Sy Ta boldface font (symbolic) (>0 arguments)
525 .It Sx \&Li Ta typewriter font (literal) (>0 arguments)
526 .It Sx \&No Ta return to roman font (normal) (no arguments)
527 .It Sx \&Bf , \&Ef Ta font block:
528 .Op Fl Ar type | Cm \&Em | \&Li | \&Sy
530 .Ss Physical enclosures
531 .Bl -column "Brq, Bro, Brc" description
532 .It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text
533 .It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text
534 .It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text
535 .It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text
536 .It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text
537 .It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text
538 .It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text
539 .It Sx \&Eo , \&Ec Ta generic enclosure
542 .Bl -column "Brq, Bro, Brc" description
543 .It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
544 .It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
545 .It Sx \&St Ta reference to a standards document (one argument)
555 This section is a canonical reference of all macros, arranged
557 For the scoping of individual macros, see
563 Multiple authors should each be accorded their own
566 Author names should be ordered with full or abbreviated forename(s)
567 first, then full surname.
572 This macro may also be used in a non-bibliographic context when
573 referring to book titles.
575 Publication city or location of an
579 Publication date of an
582 Recommended formats of arguments are
587 Publisher or issuer name of an
595 Issue number (usually for journals) of an
599 Optional information of an
603 Book or journal page number of an
607 Institutional author (school, government, etc.) of an
610 Multiple institutional authors should each be accorded their own
614 Technical report name of an
621 This macro may also be used in a non-bibliographical context when
622 referring to article titles.
624 URI of reference document.
633 Does not have any tail arguments.
636 Do not use this for postal addresses.
643 Can be used both for the authors of the program, function, or driver
644 documented in the manual, or for the authors of the manual itself.
645 Requires either the name of an author or one of the following arguments:
647 .Bl -tag -width "-nosplitX" -offset indent -compact
649 Start a new output line before each subsequent invocation of
658 The effect of selecting either of the
660 modes ends at the beginning of the
665 section, the default is
667 for the first author listing and
669 for all other author listings.
673 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
675 Begin a block enclosed by angle brackets.
676 Does not have any head arguments.
677 This macro is almost never useful.
682 Inserts an apostrophe without any surrounding whitespace.
683 This is generally used as a grammatical device when referring to the verb
687 .Dl \&.Fn execve \&Ap d
689 Encloses its arguments in angle brackets.
690 The only important use case is for email addresses.
695 Occasionally, it is used for names of characters and keys, for example:
696 .Bd -literal -offset indent
716 usually renders with non-ASCII characters in non-ASCII output modes,
717 do not use it where the ASCII characters
721 are required as syntax elements.
722 Instead, use these characters directly in such cases, combining them
734 If an argument is not provided, the string
736 is used as a default.
741 .Dl ".Ar arg1 , arg2 ."
745 macro are names and placeholders for command arguments;
746 for fixed strings to be passed verbatim as arguments, use
754 Accepts one optional argument:
756 .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
767 Note that these arguments do not begin with a hyphen.
786 Does not have any tail arguments.
788 Begin a display block.
789 Its syntax is as follows:
790 .Bd -ragged -offset indent
793 .Op Fl offset Ar width
797 Display blocks are used to select a different indentation and
798 justification than the one used by the surrounding text.
799 They may contain both macro lines and text lines.
800 By default, a display block is preceded by a vertical space.
804 must be one of the following:
805 .Bl -tag -width 13n -offset indent
807 Produce one output line from each input line, and center-justify each line.
808 Using this display type is not recommended; many
810 implementations render it poorly.
812 Change the positions of line breaks to fill each line, and left- and
813 right-justify the resulting block.
815 Produce one output line from each input line,
816 and do not justify the block at all.
817 Preserve white space as it appears in the input.
818 Always use a constant-width font.
819 Use this for displaying source code.
821 Change the positions of line breaks to fill each line, and left-justify
826 but using the same font as for normal text, which is a variable width font
827 if supported by the output device.
832 must be provided first.
833 Additional arguments may follow:
834 .Bl -tag -width 13n -offset indent
835 .It Fl offset Ar width
836 Indent the display by the
838 which may be one of the following:
841 One of the pre-defined strings
843 the width of a standard indentation (six constant width characters);
850 which justifies to the right margin; or
852 which aligns around an imagined center axis.
854 A macro invocation, which selects a predefined width
855 associated with that macro.
856 The most popular is the imaginary macro
861 A scaling width as described in
864 An arbitrary string, which indents by the length of this string.
867 When the argument is missing,
871 Do not assert vertical space before the display.
875 .Bd -literal -offset indent
876 \&.Bd \-literal \-offset indent \-compact
886 Change the font mode for a scoped block of text.
887 Its syntax is as follows:
888 .Bd -ragged -offset indent
891 .Fl emphasis | literal | symbolic |
892 .Cm \&Em | \&Li | \&Sy
900 argument are equivalent, as are
908 Without an argument, this macro does nothing.
909 The font mode continues until broken by a new font mode in a nested
921 For each macro, keep its output together on the same output line,
922 until the end of the macro or the end of the input line is reached,
923 whichever comes first.
924 Line breaks in text lines are unaffected.
925 The syntax is as follows:
927 .D1 Pf \. Sx \&Bk Fl words
931 argument is required; additional arguments are ignored.
933 The following example will not break within each
936 .Bd -literal -offset indent
943 Be careful in using over-long lines within a keep block!
944 Doing so will clobber the right margin.
947 Lists consist of items specified using the
949 macro, containing a head or a body or both.
950 The list syntax is as follows:
951 .Bd -ragged -offset indent
962 is mandatory and must be specified first.
967 arguments accept macro names as described for
970 scaling widths as described in
972 or use the length of the given string.
975 is a global indentation for the whole list, affecting both item heads
977 For those list types supporting it, the
979 argument requests an additional indentation of item bodies,
984 argument is specified, list entries are separated by vertical space.
986 A list must specify one of the following list types:
987 .Bl -tag -width 12n -offset indent
989 No item heads can be specified, but a bullet will be printed at the head
991 Item bodies start on the same output line as the bullet
992 and are indented according to the
999 argument has no effect; instead, the string length of each argument
1000 specifies the width of one column.
1001 If the first line of the body of a
1007 contexts spanning one input line each are implied until an
1009 macro line is encountered, at which point items start being interpreted as
1016 except that dashes are used in place of bullets.
1020 except that item heads are not parsed for macro invocations.
1021 Most often used in the
1023 section with error constants in the item heads.
1026 No item heads can be specified.
1029 except that cardinal numbers are used in place of bullets,
1034 except that the first lines of item bodies are not indented, but follow
1035 the item heads like in
1042 Item bodies follow items heads on the same line, using normal inter-word
1044 Bodies are not indented, and the
1046 argument is ignored.
1048 No item heads can be specified, and none are printed.
1049 Bodies are not indented, and the
1051 argument is ignored.
1053 Item bodies start on the line following item heads and are not indented.
1056 argument is ignored.
1058 Item bodies are indented according to the
1061 When an item head fits inside the indentation, the item body follows
1062 this head on the same output line.
1063 Otherwise, the body starts on the output line following the head.
1066 Lists may be nested within lists and displays.
1071 lists may not be portable.
1078 Begin a block enclosed by square brackets.
1079 Does not have any head arguments.
1082 .Bd -literal -offset indent -compact
1090 Encloses its arguments in square brackets.
1093 .Dl \&.Bq 1 , \&Dv BUFSIZ
1096 this macro is sometimes abused to emulate optional arguments for
1097 commands; the correct macros to use for this purpose are
1109 Does not have any tail arguments.
1111 Begin a block enclosed by curly braces.
1112 Does not have any head arguments.
1115 .Bd -literal -offset indent -compact
1123 Encloses its arguments in curly braces.
1126 .Dl \&.Brq 1 , ... , \&Va n
1133 version provided as an argument, or a default value if
1134 no argument is provided.
1149 Supported only for compatibility, do not use this in new manuals.
1151 .Dq is currently in beta test.
1155 version provided as an argument, or a default value if no
1156 argument is provided.
1172 Kernel configuration declaration.
1173 This denotes strings accepted by
1175 It is most often used in section 4 manual pages.
1178 .Dl \&.Cd device le0 at scode?
1181 this macro is commonly abused by using quoted literals to retain
1182 whitespace and align consecutive
1185 This practise is discouraged.
1188 Typically used for fixed strings passed as arguments, unless
1190 is more appropriate.
1191 Also useful when specifying configuration options or keys.
1194 .Dl ".Nm mt Fl f Ar device Cm rewind"
1195 .Dl ".Nm ps Fl o Cm pid , Ns Cm command"
1196 .Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
1197 .Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa"
1198 .Dl ".Cm LogLevel Dv DEBUG"
1200 One-line indented display.
1201 This is formatted by the default rules and is useful for simple indented
1203 It is followed by a newline.
1206 .Dl \&.D1 \&Fl abcdefgh
1213 This macro is obsolete.
1214 No replacement is needed.
1217 and groff including its arguments.
1218 It was formerly used to toggle a debugging mode.
1223 Does not have any tail arguments.
1225 Document date for display in the page footer.
1226 This is the mandatory first macro of any
1229 Its syntax is as follows:
1231 .D1 Pf \. Sx \&Dd Ar month day , year
1235 is the full English month name, the
1237 is an integer number, and the
1239 is the full four-digit year.
1241 Other arguments are not portable; the
1243 utility handles them as follows:
1244 .Bl -dash -offset 3n -compact
1246 To have the date automatically filled in by the
1252 can be given as an argument.
1254 The traditional, purely numeric
1257 .Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day
1260 If a date string cannot be parsed, it is used verbatim.
1262 If no date string is given, the current date is used.
1266 .Dl \&.Dd $\&Mdocdate$
1267 .Dl \&.Dd $\&Mdocdate: July 2 2018$
1268 .Dl \&.Dd July 2, 2018
1275 One-line indented display.
1276 This is formatted as literal text and is useful for commands and
1278 It is followed by a newline.
1281 .Dl \&.Dl % mandoc mdoc.7 \e(ba less
1290 Begin a block enclosed by double quotes.
1291 Does not have any head arguments.
1294 .Bd -literal -offset indent -compact
1296 April is the cruellest month
1304 Encloses its arguments in
1309 .Bd -literal -offset indent -compact
1310 \&.Dq April is the cruellest month
1320 Document title for display in the page header.
1321 This is the mandatory second macro of any
1324 Its syntax is as follows:
1325 .Bd -ragged -offset indent
1332 Its arguments are as follows:
1333 .Bl -tag -width section -offset 2n
1335 The document's title (name), defaulting to
1338 To achieve a uniform appearance of page header lines,
1339 it should by convention be all caps.
1344 .Pq General Commands ,
1348 .Pq Library Functions ,
1352 .Pq Device Drivers ,
1358 .Pq Miscellaneous Information ,
1360 .Pq System Manager's Manual ,
1363 .Pq Kernel Developer's Manual .
1364 It should correspond to the manual's filename suffix and defaults to
1365 the empty string if unspecified.
1367 This specifies the machine architecture a manual page applies to,
1368 where relevant, for example
1374 The list of valid architectures varies by operating system.
1379 .Dl \&.Dt FOO 9 i386
1386 Defined variables such as preprocessor constants, constant symbols,
1387 enumeration values, and so on.
1392 .Dl \&.Dv STDOUT_FILENO
1398 for special-purpose constants,
1400 for variable symbols, and
1402 for listing preprocessor variable definitions in the
1407 version provided as an argument, or a default
1408 value if no argument is provided.
1423 Close a scope started by
1425 Its syntax is as follows:
1427 .D1 Pf \. Sx \&Ec Op Ar TERM
1431 argument is used as the enclosure tail, for example, specifying \e(rq
1435 End a display context started by
1438 End a font mode context started by
1441 End a keep context started by
1444 End a list context started by
1452 Request an italic font.
1453 If the output device does not provide that, underline.
1455 This is most often used for stress emphasis (not to be confused with
1458 In the rare cases where none of the semantic markup macros fit,
1459 it can also be used for technical terms and placeholders, except
1460 that for syntax elements,
1464 are preferred, respectively.
1467 .Bd -literal -compact -offset indent
1468 Selected lines are those
1470 matching any of the specified patterns.
1471 Some of the functions use a
1473 to save the pattern space for subsequent retrieval.
1483 This macro is obsolete.
1486 or any of the other enclosure macros.
1488 It encloses its argument in the delimiters specified by the last
1492 An arbitrary enclosure.
1493 Its syntax is as follows:
1495 .D1 Pf \. Sx \&Eo Op Ar TERM
1499 argument is used as the enclosure head, for example, specifying \e(lq
1503 Error constants for definitions of the
1505 libc global variable.
1506 This is most often used in section 2 and 3 manual pages.
1514 for general constants.
1516 This macro is obsolete.
1519 or any of the other enclosure macros.
1521 It takes two arguments, defining the delimiters to be used by subsequent
1525 Environmental variables such as those specified in
1534 for general constants.
1536 Insert a standard sentence regarding command exit values of 0 on success
1538 This is most often used in section 1, 6, and 8 manual pages.
1539 Its syntax is as follows:
1541 .D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
1545 is not specified, the document's name set by
1550 arguments are treated as separate utilities.
1555 Function argument or parameter.
1556 Its syntax is as follows:
1557 .Bd -ragged -offset indent
1565 Each argument may be a name and a type (recommended for the
1567 section), a name alone (for function invocations),
1568 or a type alone (for function prototypes).
1569 If both a type and a name are given or if the type consists of multiple
1570 words, all words belonging to the same function argument have to be
1571 given in a single argument to the
1575 This macro is also used to specify the field name of a structure.
1579 macro is used in the
1583 blocks when documenting multi-line function prototypes.
1584 If invoked with multiple arguments, the arguments are separated by a
1586 Furthermore, if the following macro is another
1588 the last argument will also have a trailing comma.
1591 .Dl \&.Fa \(dqconst char *p\(dq
1592 .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
1593 .Dl \&.Fa \(dqchar *\(dq size_t
1598 End a function context started by
1601 Preprocessor directive, in particular for listing it in the
1603 Historically, it was also used to document include files.
1604 The latter usage has been deprecated in favour of
1607 Its syntax is as follows:
1608 .Bd -ragged -offset indent
1610 .Li # Ns Ar directive
1615 .Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler
1616 .Dl \&.Fd #define SIO_MAXNFDS
1617 .Dl \&.Fd #ifdef FS_DEBUG
1619 .Dl \&.Fn dbg_open \(dqconst char *\(dq
1623 .Sx MANUAL STRUCTURE ,
1628 Command-line flag or option.
1629 Used when listing arguments to command-line utilities.
1630 Prints a fixed-width hyphen
1632 directly followed by each argument.
1633 If no arguments are provided, a hyphen is printed followed by a space.
1634 If the argument is a macro, a hyphen is prefixed to the subsequent macro
1638 .Dl ".Fl R Op Fl H | L | P"
1639 .Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
1640 .Dl ".Fl type Cm d Fl name Pa CVS"
1641 .Dl ".Fl Ar signal_number"
1648 Its syntax is as follows:
1649 .Bd -ragged -offset indent
1653 .Op Oo Ar argtype Oc Ar argname
1656 Function arguments are surrounded in parenthesis and
1657 are delimited by commas.
1658 If no arguments are specified, blank parenthesis are output.
1661 section, this macro starts a new output line,
1662 and a blank line is automatically inserted between function definitions.
1665 .Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
1666 .Dl \&.Fn funcname \(dqint arg0\(dq
1667 .Dl \&.Fn funcname arg0
1669 .Bd -literal -offset indent -compact
1674 When referring to a function documented in another manual page, use
1678 .Sx MANUAL STRUCTURE ,
1683 Begin a function block.
1684 This is a multi-line version of
1686 Its syntax is as follows:
1688 .D1 Pf \. Sx \&Fo Ar funcname
1690 Invocations usually occur in the following context:
1691 .Bd -ragged -offset indent
1692 .Pf \. Sx \&Ft Ar functype
1694 .Pf \. Sx \&Fo Ar funcname
1696 .Pf \. Sx \&Fa Qq Ar argtype Ar argname
1709 .Sx MANUAL STRUCTURE ,
1715 This macro is obsolete.
1716 No replacement markup is needed.
1718 It was used to show numerical function return values in an italic font.
1721 Its syntax is as follows:
1723 .D1 Pf \. Sx \&Ft Ar functype
1727 section, a new output line is started after this macro.
1731 .Bd -literal -offset indent -compact
1737 .Sx MANUAL STRUCTURE ,
1744 version provided as an argument, or a default value
1745 if no argument is provided.
1760 This macro is not implemented in
1763 It was used to include the contents of a (header) file literally.
1766 .Dl Pf . Sx \&Hf Ar filename
1768 Designate an internal or interactive command.
1771 but used for instructions rather than values.
1782 is preferred for displaying code; the
1784 macro is used when referring to specific instructions.
1786 The name of an include file.
1787 This macro is most often used in section 2, 3, and 9 manual pages.
1789 When invoked as the first macro on an input line in the
1791 section, the argument is displayed in angle brackets
1794 and a blank line is inserted in front if there is a preceding
1795 function declaration.
1796 In other sections, it only encloses its argument in angle brackets
1797 and causes no line break.
1800 .Dl \&.In sys/types.h
1803 .Sx MANUAL STRUCTURE .
1806 The syntax of this macro depends on the list type.
1815 have the following syntax:
1817 .D1 Pf \. Sx \&It Ar args
1826 have the following syntax:
1830 with subsequent lines interpreted within the scope of the
1832 until either a closing
1839 list has the following syntax:
1841 .D1 Pf \. Sx \&It Op Cm args
1843 Subsequent lines are interpreted as with
1846 The line arguments correspond to the list's left-hand side; body
1847 arguments correspond to the list's contents.
1851 list is the most complicated.
1852 Its syntax is as follows:
1854 .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
1855 .D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
1857 The arguments consist of one or more lines of text and macros
1858 representing a complete table line.
1859 Cells within the line are delimited by the special
1861 block macro or by literal tab characters.
1863 Using literal tabs is strongly discouraged because they are very
1864 hard to use correctly and
1866 code using them is very hard to read.
1867 In particular, a blank character is syntactically significant
1868 before and after the literal tab character.
1869 If a word precedes or follows the tab without an intervening blank,
1870 that word is never interpreted as a macro call, but always output
1873 The tab cell delimiter may only be used within the
1875 line itself; on following lines, only the
1877 macro can be used to delimit cells, and portability requires that
1879 is called by other macros: some parsers do not recognize it when
1880 it appears as the first macro on a line.
1882 Note that quoted strings may span tab-delimited cells on an
1887 .Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&;
1889 will preserve the whitespace before both commas,
1890 but not the whitespace before the semicolon.
1896 The syntax is as follows:
1898 .D1 Pf \. Sx \&Lb Ar library
1902 parameter may be a system library, such as
1906 in which case a small library description is printed next to the linker
1907 invocation; or a custom library, in which case the library name is
1909 This is most commonly used in the
1911 section as described in
1912 .Sx MANUAL STRUCTURE .
1918 Denotes text that should be in a
1921 Note that this is a presentation term and should not be used for
1922 stylistically decorating technical terms.
1924 On terminal output devices, this is often indistinguishable from
1935 Its syntax is as follows:
1937 .D1 Pf \. Sx \&Lk Ar uri Op Ar name
1940 .Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
1941 .Dl \&.Lk http://bsd.lv
1949 Display a mathematical symbol.
1950 Its syntax is as follows:
1952 .D1 Pf \. Sx \&Ms Ar symbol
1961 Its syntax is as follows:
1963 .D1 Pf \. Sx \&Mt Ar address
1966 .Dl \&.Mt discuss@manpages.bsd.lv
1967 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
1969 A one line description of the manual's content.
1970 This is the mandatory last macro of the
1972 section and not appropriate for other sections.
1975 .Dl Pf . Sx \&Nd mdoc language reference
1976 .Dl Pf . Sx \&Nd format and display UNIX manuals
1980 macro technically accepts child macros and terminates with a subsequent
1983 Do not assume this behaviour: some
1985 database generators are not smart enough to parse more than the line
1986 arguments and will display macros verbatim.
1991 The name of the manual page, or \(em in particular in section 1, 6,
1992 and 8 pages \(em of an additional command or feature documented in
1994 When first invoked, the
1996 macro expects a single argument, the name of the manual page.
1997 Usually, the first invocation happens in the
1999 section of the page.
2000 The specified name will be remembered and used whenever the macro is
2001 called again without arguments later in the page.
2005 .Sx Block full-implicit
2006 semantics when invoked as the first macro on an input line in the
2008 section; otherwise, it uses ordinary
2013 .Bd -literal -offset indent
2022 of section 2, 3 and 9 manual pages, use the
2026 to mark up the name of the manual page.
2029 Closes the scope of any preceding in-line macro.
2030 When used after physical formatting macros like
2034 switches back to the standard font face and weight.
2035 Can also be used to embed plain text strings in macro lines
2036 using semantic annotation macros.
2039 .Dl ".Em italic , Sy bold , No and roman"
2041 .Bd -literal -offset indent -compact
2043 \&.Cm :C No / Ar pattern No / Ar replacement No /
2053 Suppress a space between the output of the preceding macro
2054 and the following text or macro.
2055 Following invocation, input is interpreted as normal text
2060 This has no effect when invoked at the start of a macro line.
2063 .Dl ".Ar name Ns = Ns Ar value"
2064 .Dl ".Cm :M Ns Ar pattern"
2065 .Dl ".Fl o Ns Ar output"
2074 version provided as an argument, or a default value if
2075 no argument is provided.
2094 Multi-line version of
2098 .Bd -literal -offset indent -compact
2100 \&.Op Fl flag Ns Ar value
2104 Optional part of a command line.
2105 Prints the argument(s) in brackets.
2106 This is most often used in the
2108 section of section 1 and 8 manual pages.
2111 .Dl \&.Op \&Fl a \&Ar b
2112 .Dl \&.Op \&Ar a | b
2117 Operating system version for display in the page footer.
2118 This is the mandatory third macro of
2122 Its syntax is as follows:
2124 .D1 Pf \. Sx \&Os Op Ar system Op Ar version
2128 parameter specifies the relevant operating system or environment.
2129 It is suggested to leave it unspecified, in which case
2133 argument or, if that isn't specified either,
2142 .Dl \&.Os KTH/CSC/TCS
2150 This macro is obsolete.
2155 both have the same effect.
2159 packages described it as
2160 .Dq "old function type (FORTRAN)" .
2164 version provided as an argument, or a default value
2165 if no argument is provided.
2180 An absolute or relative file system path, or a file or directory name.
2181 If an argument is not provided, the character
2183 is used as a default.
2186 .Dl \&.Pa /usr/bin/mandoc
2187 .Dl \&.Pa /usr/share/man/man7/mdoc.7
2192 Close parenthesised context opened by
2195 Removes the space between its argument and the following macro.
2196 Its syntax is as follows:
2198 .D1 .Pf Ar prefix macro arguments ...
2200 This is equivalent to:
2202 .D1 .No \e& Ns Ar prefix No \&Ns Ar macro arguments ...
2206 argument is not parsed for macro names or delimiters,
2207 but used verbatim as if it were escaped.
2210 .Dl ".Pf $ Ar variable_name"
2211 .Dl ".Pf . Ar macro_name"
2212 .Dl ".Pf 0x Ar hex_digits"
2219 Multi-line version of
2223 This will assert vertical space between prior and subsequent macros
2226 Paragraph breaks are not needed before or after
2230 macros or before displays
2238 Parenthesised enclosure.
2243 Close quoted context opened by
2246 In-line literal display.
2247 This can for example be used for complete command invocations and
2248 for multi-word code fragments when more specific markup is not
2249 appropriate and an indented display is not desired.
2252 always encloses the arguments in single quotes, other formatters
2253 usually omit the quotes on non-terminal output devices when the
2254 arguments have three or more characters.
2262 Multi-line version of
2265 Encloses its arguments in
2280 Does not have any tail arguments.
2282 Begin a bibliographic
2285 Does not have any head arguments.
2286 The block macro may only contain
2302 child macros (at least one must be specified).
2305 .Bd -literal -offset indent -compact
2307 \&.%A J. E. Hopcroft
2309 \&.%B Introduction to Automata Theory, Languages, and Computation
2310 \&.%I Addison-Wesley
2311 \&.%C Reading, Massachusetts
2318 block is used within a SEE ALSO section, a vertical space is asserted
2319 before the rendered output, else the block continues on the current
2322 Insert a standard sentence regarding a function call's return value of 0
2323 on success and \-1 on error, with the
2325 libc global variable set on error.
2326 Its syntax is as follows:
2328 .D1 Pf \. Sx \&Rv Fl std Op Ar function ...
2332 is not specified, the document's name set by
2337 arguments are treated as separate functions.
2342 Close single-quoted context opened by
2345 Begin a new section.
2346 For a list of conventional manual sections, see
2347 .Sx MANUAL STRUCTURE .
2348 These sections should be used unless it's absolutely necessary that
2349 custom sections be used.
2351 Section names should be unique so that they may be keyed by
2353 Although this macro is parsed, it should not consist of child node or it
2354 may not be linked with
2363 Switches the spacing mode for output generated from macros.
2364 Its syntax is as follows:
2366 .D1 Pf \. Sx \&Sm Op Cm on | off
2368 By default, spacing is
2372 no white space is inserted between macro arguments and between the
2373 output generated from adjacent macros, but text lines
2374 still get normal spacing between words and sentences.
2376 When called without an argument, the
2378 macro toggles the spacing mode.
2379 Using this is not recommended because it makes the code harder to read.
2381 Multi-line version of
2384 Encloses its arguments in
2394 Begin a new subsection.
2397 there is no convention for the naming of subsections.
2400 the conventional sections described in
2401 .Sx MANUAL STRUCTURE
2402 rarely have subsections.
2404 Sub-section names should be unique so that they may be keyed by
2406 Although this macro is parsed, it should not consist of child node or it
2407 may not be linked with
2416 Replace an abbreviation for a standard with the full form.
2417 The following standards are recognised.
2418 Where multiple lines are given without a blank line in between,
2419 they all refer to the same standard, and using the first form
2422 .It C language standards
2424 .Bl -tag -width "-p1003.1g-2000" -compact
2434 The original C standard.
2448 The second major version of the C language standard.
2453 The third major version of the C language standard.
2455 .It POSIX.1 before the Single UNIX Specification
2457 .Bl -tag -width "-p1003.1g-2000" -compact
2463 The original POSIX standard, based on ANSI C.
2470 The first update of POSIX.1.
2477 Real-time extensions.
2482 POSIX thread interfaces.
2487 Technical Corrigendum.
2494 Includes POSIX.1-1990, 1b, 1c, and 1i.
2496 .It X/Open Portability Guide version 4 and related standards
2498 .Bl -tag -width "-p1003.1g-2000" -compact
2502 An XPG4 precursor, published in 1989.
2521 Based on POSIX.1 and POSIX.2, published in 1992.
2523 .It Single UNIX Specification version 1 and related standards
2525 .Bl -tag -width "-p1003.1g-2000" -compact
2531 This standard was published in 1994.
2532 It was used as the basis for UNIX 95 certification.
2533 The following three refer to parts of it.
2544 Networking APIs, including sockets.
2551 .It Single UNIX Specification version 2 and related standards
2553 .Bl -tag -width "-p1003.1g-2000" -compact
2556 This Standard was published in 1997
2557 and is also called X/Open Portability Guide version 5.
2558 It was used as the basis for UNIX 98 certification.
2559 The following refer to parts of it.
2575 .It Single UNIX Specification version 3
2577 .Bl -tag -width "-p1003.1-2001" -compact
2583 This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j.
2584 It is also called X/Open Portability Guide version 6.
2585 It is used as the basis for UNIX 03 certification.
2590 The second and last Technical Corrigendum.
2592 .It Single UNIX Specification version 4
2594 .Bl -tag -width "-p1003.1g-2000" -compact
2600 This standard is also called
2601 X/Open Portability Guide version 7.
2605 .Bl -tag -width "-p1003.1g-2000" -compact
2609 Floating-point arithmetic.
2614 Representation of dates and times, published in 1988.
2619 Ethernet local area networks.
2626 Reference a section or subsection in the same manual page.
2627 The referenced section or subsection name must be identical to the
2628 enclosed argument, including whitespace.
2631 .Dl \&.Sx MANUAL STRUCTURE
2638 Request a boldface font.
2640 This is most often used to indicate importance or seriousness (not to be
2641 confused with stress emphasis, see
2643 When none of the semantic macros fit, it is also adequate for syntax
2644 elements that have to be given or that appear verbatim.
2647 .Bd -literal -compact -offset indent
2651 appears in the owner permissions, set-user-ID mode is set.
2652 This utility replaces the former
2664 Table cell separator in
2666 lists; can only be used below
2669 Supported only for compatibility, do not use this in new manuals.
2670 Even though the macro name
2672 suggests a semantic function, historic usage is inconsistent, mostly
2673 using it as a presentation-level macro to request a small caps font.
2675 Supported only for compatibility, do not use this in new manuals.
2677 .Dq currently under development.
2679 Supported only for compatibility, do not use this in new manuals.
2687 .Dl \&.Va const char *bar ;
2689 For function arguments and parameters, use
2692 For declarations of global variables in the
2699 This is also used for indicating global variables in the
2701 section, in which case a variable name is also specified.
2702 Note that it accepts
2703 .Sx Block partial-implicit
2704 syntax when invoked as the first macro on an input line in the
2706 section, else it accepts ordinary
2709 In the former case, this macro starts a new output line,
2710 and a blank line is inserted in front if there is a preceding
2711 function definition or include directive.
2714 .Dl \&.Vt unsigned char
2715 .Dl \&.Vt extern const char * const sys_signame[] \&;
2717 For parameters in function prototypes, use
2719 instead, for function return types
2721 and for variable names outside the
2725 even when including a type with the name.
2727 .Sx MANUAL STRUCTURE .
2729 Close a scope opened by
2732 Extend the header of an
2734 macro or the body of a partial-implicit block macro
2735 beyond the end of the input line.
2736 This macro originally existed to work around the 9-argument limit
2740 Link to another manual
2741 .Pq Qq cross-reference .
2742 Its syntax is as follows:
2744 .D1 Pf \. Sx \&Xr Ar name section
2750 number of another man page.
2754 .Dl \&.Xr mandoc 1 \&;
2755 .Dl \&.Xr mandoc 1 \&Ns s behaviour
2757 The syntax of a macro depends on its classification.
2760 refers to macro arguments, which may be followed by zero or more
2764 opens the scope of a macro; and if specified,
2770 column indicates that the macro may also be called by passing its name
2771 as an argument to another macro.
2773 .Sq \&.Op \&Fl O \&Ar file
2775 .Sq Op Fl O Ar file .
2776 To prevent a macro call and render the macro name literally,
2777 escape it by prepending a zero-width space,
2783 If a macro is not callable but its name appears as an argument
2784 to another macro, it is interpreted as opaque text.
2792 column indicates whether the macro may call other macros by receiving
2793 their names as arguments.
2794 If a macro is not parsed but the name of another macro appears
2795 as an argument, it is interpreted as opaque text.
2799 column, if applicable, describes closure rules.
2800 .Ss Block full-explicit
2801 Multi-line scope closed by an explicit closing macro.
2802 All macros contains bodies; only
2808 .Bd -literal -offset indent
2809 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2813 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
2814 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2815 .It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
2816 .It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
2817 .It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
2818 .It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
2819 .It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
2820 .It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
2821 .It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
2822 .It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
2824 .Ss Block full-implicit
2825 Multi-line scope closed by end-of-file or implicitly by another macro.
2826 All macros have bodies; some
2828 .Sx \&It Fl bullet ,
2834 don't have heads; only one
2841 .Bd -literal -offset indent
2842 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
2845 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
2846 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2847 .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
2848 .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
2849 .It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
2850 .It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh
2851 .It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss
2857 .Sx Block full-implicit
2858 macro only when invoked as the first macro
2861 section line, else it is
2863 .Ss Block partial-explicit
2864 Like block full-explicit, but also with single-line scope.
2865 Each has at least a body and, in limited circumstances, a head
2872 .Bd -literal -offset indent
2873 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2875 \&.Yc \(lBtail...\(rB
2877 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
2878 \(lBbody...\(rB \&Yc \(lBtail...\(rB
2880 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
2881 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2882 .It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
2883 .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
2884 .It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
2885 .It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
2886 .It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
2887 .It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
2888 .It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
2889 .It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
2890 .It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
2891 .It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
2892 .It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
2893 .It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
2894 .It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
2895 .It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
2896 .It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
2897 .It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
2898 .It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
2899 .It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
2900 .It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
2901 .It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
2902 .It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
2903 .It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
2904 .It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
2905 .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
2907 .Ss Block partial-implicit
2908 Like block full-implicit, but with single-line scope closed by the
2910 .Bd -literal -offset indent
2911 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
2913 .Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
2914 .It Em Macro Ta Em Callable Ta Em Parsed
2915 .It Sx \&Aq Ta Yes Ta Yes
2916 .It Sx \&Bq Ta Yes Ta Yes
2917 .It Sx \&Brq Ta Yes Ta Yes
2918 .It Sx \&D1 Ta \&No Ta \&Yes
2919 .It Sx \&Dl Ta \&No Ta Yes
2920 .It Sx \&Dq Ta Yes Ta Yes
2921 .It Sx \&En Ta Yes Ta Yes
2922 .It Sx \&Op Ta Yes Ta Yes
2923 .It Sx \&Pq Ta Yes Ta Yes
2924 .It Sx \&Ql Ta Yes Ta Yes
2925 .It Sx \&Qq Ta Yes Ta Yes
2926 .It Sx \&Sq Ta Yes Ta Yes
2927 .It Sx \&Vt Ta Yes Ta Yes
2933 .Sx Block partial-implicit
2934 only when invoked as the first macro
2937 section line, else it is
2939 .Ss Special block macro
2942 macro can only be used below
2947 It delimits blocks representing table cells;
2948 these blocks have bodies, but no heads.
2949 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
2950 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2951 .It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It
2954 Closed by the end of the line, fixed argument lengths,
2955 and/or subsequent macros.
2956 In-line macros have only text children.
2957 If a number (or inequality) of arguments is
2959 then the macro accepts an arbitrary number of arguments.
2960 .Bd -literal -offset indent
2961 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
2963 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
2965 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
2967 .Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
2968 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
2969 .It Sx \&%A Ta \&No Ta \&No Ta >0
2970 .It Sx \&%B Ta \&No Ta \&No Ta >0
2971 .It Sx \&%C Ta \&No Ta \&No Ta >0
2972 .It Sx \&%D Ta \&No Ta \&No Ta >0
2973 .It Sx \&%I Ta \&No Ta \&No Ta >0
2974 .It Sx \&%J Ta \&No Ta \&No Ta >0
2975 .It Sx \&%N Ta \&No Ta \&No Ta >0
2976 .It Sx \&%O Ta \&No Ta \&No Ta >0
2977 .It Sx \&%P Ta \&No Ta \&No Ta >0
2978 .It Sx \&%Q Ta \&No Ta \&No Ta >0
2979 .It Sx \&%R Ta \&No Ta \&No Ta >0
2980 .It Sx \&%T Ta \&No Ta \&No Ta >0
2981 .It Sx \&%U Ta \&No Ta \&No Ta >0
2982 .It Sx \&%V Ta \&No Ta \&No Ta >0
2983 .It Sx \&Ad Ta Yes Ta Yes Ta >0
2984 .It Sx \&An Ta Yes Ta Yes Ta >0
2985 .It Sx \&Ap Ta Yes Ta Yes Ta 0
2986 .It Sx \&Ar Ta Yes Ta Yes Ta n
2987 .It Sx \&At Ta Yes Ta Yes Ta 1
2988 .It Sx \&Bsx Ta Yes Ta Yes Ta n
2989 .It Sx \&Bt Ta \&No Ta \&No Ta 0
2990 .It Sx \&Bx Ta Yes Ta Yes Ta n
2991 .It Sx \&Cd Ta Yes Ta Yes Ta >0
2992 .It Sx \&Cm Ta Yes Ta Yes Ta >0
2993 .It Sx \&Db Ta \&No Ta \&No Ta 1
2994 .It Sx \&Dd Ta \&No Ta \&No Ta n
2995 .It Sx \&Dt Ta \&No Ta \&No Ta n
2996 .It Sx \&Dv Ta Yes Ta Yes Ta >0
2997 .It Sx \&Dx Ta Yes Ta Yes Ta n
2998 .It Sx \&Em Ta Yes Ta Yes Ta >0
2999 .It Sx \&Er Ta Yes Ta Yes Ta >0
3000 .It Sx \&Es Ta Yes Ta Yes Ta 2
3001 .It Sx \&Ev Ta Yes Ta Yes Ta >0
3002 .It Sx \&Ex Ta \&No Ta \&No Ta n
3003 .It Sx \&Fa Ta Yes Ta Yes Ta >0
3004 .It Sx \&Fd Ta \&No Ta \&No Ta >0
3005 .It Sx \&Fl Ta Yes Ta Yes Ta n
3006 .It Sx \&Fn Ta Yes Ta Yes Ta >0
3007 .It Sx \&Fr Ta Yes Ta Yes Ta >0
3008 .It Sx \&Ft Ta Yes Ta Yes Ta >0
3009 .It Sx \&Fx Ta Yes Ta Yes Ta n
3010 .It Sx \&Hf Ta \&No Ta \&No Ta n
3011 .It Sx \&Ic Ta Yes Ta Yes Ta >0
3012 .It Sx \&In Ta \&No Ta \&No Ta 1
3013 .It Sx \&Lb Ta \&No Ta \&No Ta 1
3014 .It Sx \&Li Ta Yes Ta Yes Ta >0
3015 .It Sx \&Lk Ta Yes Ta Yes Ta >0
3016 .It Sx \&Lp Ta \&No Ta \&No Ta 0
3017 .It Sx \&Ms Ta Yes Ta Yes Ta >0
3018 .It Sx \&Mt Ta Yes Ta Yes Ta >0
3019 .It Sx \&Nm Ta Yes Ta Yes Ta n
3020 .It Sx \&No Ta Yes Ta Yes Ta 0
3021 .It Sx \&Ns Ta Yes Ta Yes Ta 0
3022 .It Sx \&Nx Ta Yes Ta Yes Ta n
3023 .It Sx \&Os Ta \&No Ta \&No Ta n
3024 .It Sx \&Ot Ta Yes Ta Yes Ta >0
3025 .It Sx \&Ox Ta Yes Ta Yes Ta n
3026 .It Sx \&Pa Ta Yes Ta Yes Ta n
3027 .It Sx \&Pf Ta Yes Ta Yes Ta 1
3028 .It Sx \&Pp Ta \&No Ta \&No Ta 0
3029 .It Sx \&Rv Ta \&No Ta \&No Ta n
3030 .It Sx \&Sm Ta \&No Ta \&No Ta <2
3031 .It Sx \&St Ta \&No Ta Yes Ta 1
3032 .It Sx \&Sx Ta Yes Ta Yes Ta >0
3033 .It Sx \&Sy Ta Yes Ta Yes Ta >0
3034 .It Sx \&Tn Ta Yes Ta Yes Ta >0
3035 .It Sx \&Ud Ta \&No Ta \&No Ta 0
3036 .It Sx \&Ux Ta Yes Ta Yes Ta n
3037 .It Sx \&Va Ta Yes Ta Yes Ta n
3038 .It Sx \&Vt Ta Yes Ta Yes Ta >0
3039 .It Sx \&Xr Ta Yes Ta Yes Ta 2
3042 When a macro argument consists of one single input character
3043 considered as a delimiter, the argument gets special handling.
3044 This does not apply when delimiters appear in arguments containing
3045 more than one character.
3046 Consequently, to prevent special handling and just handle it
3047 like any other argument, a delimiter can be escaped by prepending
3050 In text lines, delimiters never need escaping, but may be used
3051 as normal punctuation.
3053 For many macros, when the leading arguments are opening delimiters,
3054 these delimiters are put before the macro scope,
3055 and when the trailing arguments are closing delimiters,
3056 these delimiters are put after the macro scope.
3057 Spacing is suppressed after opening delimiters
3058 and before closing delimiters.
3061 .D1 Pf \. \&Aq "( [ word ] ) ."
3065 .D1 Aq ( [ word ] ) .
3067 Opening delimiters are:
3069 .Bl -tag -width Ds -offset indent -compact
3076 Closing delimiters are:
3078 .Bl -tag -width Ds -offset indent -compact
3097 Note that even a period preceded by a backslash
3099 gets this special handling; use
3103 Many in-line macros interrupt their scope when they encounter
3104 delimiters, and resume their scope when more arguments follow that
3108 .D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e"
3112 .D1 Fl a ( b | c \*(Ba d ) e
3114 This applies to both opening and closing delimiters,
3115 and also to the middle delimiter, which does not suppress spacing:
3117 .Bl -tag -width Ds -offset indent -compact
3122 As a special case, the predefined string \e*(Ba is handled and rendered
3123 in the same way as a plain
3126 Using this predefined string is not recommended in new manuals.
3130 documents, usage of semantic markup is recommended in order to have
3131 proper fonts automatically selected; only when no fitting semantic markup
3132 is available, consider falling back to
3139 font mode, it will automatically restore the previous font when exiting
3141 Manually switching the font using the
3144 font escape sequences is never required.
3146 This section provides an incomplete list of compatibility issues
3147 between mandoc and GNU troff
3150 The following problematic behaviour is found in groff:
3155 with non-standard arguments behaves very strangely.
3156 When there are three arguments, they are printed verbatim.
3157 Any other number of arguments is replaced by the current date,
3158 but without any arguments the string
3163 only accepts a single link-name argument; the remainder is misformatted.
3166 does not format its arguments when used in the FILES section under
3170 can only be called by other macros, but not at the beginning of a line.
3173 is not implemented (up to and including groff-1.22.2).
3179 .Pq font family face
3181 escapes behave irregularly when specified within line-macro scopes.
3183 Negative scaling units return to prior lines.
3184 Instead, mandoc truncates them to zero.
3187 The following features are unimplemented in mandoc:
3193 is unsupported for security reasons.
3197 does not adjust the right margin, but is an alias for
3203 does not use a literal font, but is an alias for
3208 .Fl offset Cm center
3212 Groff does not implement centered and flush-right rendering either,
3213 but produces large indentations.
3225 .Lk http://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language"
3226 provides a few tutorial-style pages for beginners, an extensive style
3227 guide for advanced authors, and an alphabetic index helping to choose
3228 the best macros for various kinds of content.
3232 language first appeared as a troff macro package in
3234 It was later significantly updated by Werner Lemberg and Ruslan Ermilov
3236 The standalone implementation that is part of the
3238 utility written by Kristaps Dzonsons appeared in
3243 reference was written by
3244 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .