1 .\" $Id: mdoc.7,v 1.229 2014/06/22 17:07:06 schwarze Exp $
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2010, 2011, 2013 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: June 22 2014 $
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 Manuals not documenting a command won't include the above fragment.
311 section usually contains most of the text of a manual, longer manuals
314 macro to form subsections.
315 In very long manuals, the
317 may be split into multiple sections, each started by an
319 macro followed by a non-standard section name, and each having
320 several subsections, like in the present
324 This section lists the contexts in which functions can be called in section 9.
325 The contexts are autoconf, process, or interrupt.
326 .It Em IMPLEMENTATION NOTES
327 Implementation-specific notes should be kept here.
328 This is useful when implementing standard functions that may have side
329 effects or notable algorithmic implications.
331 This section documents the
332 return values of functions in sections 2, 3, and 9.
337 Lists the environment variables used by the utility,
338 and explains the syntax and semantics of their values.
341 manual provides examples of typical content and formatting.
346 Documents files used.
347 It's helpful to document both the file name and a short description of how
348 the file is used (created, modified, etc.).
353 This section documents the
354 command exit status for section 1, 6, and 8 utilities.
355 Historically, this information was described in
357 a practise that is now discouraged.
363 This often contains snippets of well-formed, well-tested invocations.
364 Make sure that examples work properly!
366 Documents error messages.
367 In section 4 and 9 manuals, these are usually messages printed by the
368 kernel to the console and to the kernel log.
369 In section 1, 6, 7, and 8, these are usually messages printed by
370 userland programs to the standard error output.
372 Historically, this section was used in place of
374 for manuals in sections 1, 6, and 8; however, this practise is
383 settings in sections 2, 3, 4, and 9.
388 References other manuals with related topics.
389 This section should exist for most manuals.
390 Cross-references should conventionally be ordered first by section, then
393 References to other documentation concerning the topic of the manual page,
394 for example authoritative books or journal articles, may also be
395 provided in this section.
402 References any standards implemented or used.
403 If not adhering to any standards, the
405 section should be used instead.
410 A brief history of the subject, including where it was first implemented,
411 and when it was ported to or reimplemented for the operating system at hand.
413 Credits to the person or persons who wrote the code and/or documentation.
414 Authors should generally be noted by both name and email address.
419 Common misuses and misunderstandings should be explained
422 Known bugs, limitations, and work-arounds should be described
424 .It Em SECURITY CONSIDERATIONS
425 Documents any security precautions that operators should consider.
428 This overview is sorted such that macros of similar purpose are listed
429 together, to help find the best macro for any given purpose.
430 Deprecated macros are not included in the overview, but can be found below
432 .Sx MACRO REFERENCE .
433 .Ss Document preamble and NAME section macros
434 .Bl -column "Brq, Bro, Brc" description
435 .It Sx \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year
436 .It Sx \&Dt Ta document title: Ar TITLE section Op Ar volume | arch
437 .It Sx \&Os Ta operating system version: Op Ar system Op Ar version
438 .It Sx \&Nm Ta document name (one argument)
439 .It Sx \&Nd Ta document description (one line)
441 .Ss Sections and cross references
442 .Bl -column "Brq, Bro, Brc" description
443 .It Sx \&Sh Ta section header (one line)
444 .It Sx \&Ss Ta subsection header (one line)
445 .It Sx \&Sx Ta internal cross reference to a section or subsection
446 .It Sx \&Xr Ta cross reference to another manual page: Ar name section
447 .It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments)
449 .Ss Displays and lists
450 .Bl -column "Brq, Bro, Brc" description
451 .It Sx \&Bd , \&Ed Ta display block:
453 .Op Fl offset Ar width
455 .It Sx \&D1 Ta indented display (one line)
456 .It Sx \&Dl Ta indented literal display (one line)
457 .It Sx \&Bl , \&El Ta list block:
462 .It Sx \&It Ta list item (syntax depends on Fl Ar type )
463 .It Sx \&Ta Ta table cell separator in Sx \&Bl Fl column No lists
464 .It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references)
467 .Bl -column "Brq, Bro, Brc" description
468 .It Sx \&Pf Ta prefix, no following horizontal space (one argument)
469 .It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
470 .It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
471 .It Sx \&Sm Ta switch horizontal spacing mode: Cm on | off
472 .It Sx \&Bk , \&Ek Ta keep block: Fl words
473 .It Sx \&br Ta force output line break in text mode (no arguments)
474 .It Sx \&sp Ta force vertical space: Op Ar height
476 .Ss Semantic markup for command line utilities:
477 .Bl -column "Brq, Bro, Brc" description
478 .It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility
479 .It Sx \&Fl Ta command line options (flags) (>=0 arguments)
480 .It Sx \&Cm Ta command modifier (>0 arguments)
481 .It Sx \&Ar Ta command arguments (>=0 arguments)
482 .It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure)
483 .It Sx \&Ic Ta internal or interactive command (>0 arguments)
484 .It Sx \&Ev Ta environmental variable (>0 arguments)
485 .It Sx \&Pa Ta file system path (>=0 arguments)
487 .Ss Semantic markup for function libraries:
488 .Bl -column "Brq, Bro, Brc" description
489 .It Sx \&Lb Ta function library (one argument)
490 .It Sx \&In Ta include file (one argument)
491 .It Sx \&Fd Ta other preprocessor directive (>0 arguments)
492 .It Sx \&Ft Ta function type (>0 arguments)
493 .It Sx \&Fo , \&Fc Ta function block: Ar funcname
494 .It Sx \&Fn Ta function name:
501 .It Sx \&Fa Ta function argument (>0 arguments)
502 .It Sx \&Vt Ta variable type (>0 arguments)
503 .It Sx \&Va Ta variable name (>0 arguments)
504 .It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments)
505 .It Sx \&Er Ta error constant (>0 arguments)
506 .It Sx \&Ev Ta environmental variable (>0 arguments)
508 .Ss Various semantic markup:
509 .Bl -column "Brq, Bro, Brc" description
510 .It Sx \&An Ta author name (>0 arguments)
511 .It Sx \&Lk Ta hyperlink: Ar uri Op Ar name
512 .It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address
513 .It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
514 .It Sx \&Ad Ta memory address (>0 arguments)
515 .It Sx \&Ms Ta mathematical symbol (>0 arguments)
516 .It Sx \&Tn Ta tradename (>0 arguments)
519 .Bl -column "Brq, Bro, Brc" description
520 .It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments)
521 .It Sx \&Sy Ta boldface font (symbolic) (>0 arguments)
522 .It Sx \&Li Ta typewriter font (literal) (>0 arguments)
523 .It Sx \&No Ta return to roman font (normal) (no arguments)
524 .It Sx \&Bf , \&Ef Ta font block:
525 .Op Fl Ar type | Cm \&Em | \&Li | \&Sy
527 .Ss Physical enclosures
528 .Bl -column "Brq, Bro, Brc" description
529 .It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text
530 .It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text
531 .It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text
532 .It Sx \&Ql Ta single-quoted literal text: Ql text
533 .It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text
534 .It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text
535 .It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text
536 .It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text
537 .It Sx \&Eo , \&Ec Ta generic enclosure
540 .Bl -column "Brq, Bro, Brc" description
541 .It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
542 .It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
543 .It Sx \&St Ta reference to a standards document (one argument)
554 This section is a canonical reference of all macros, arranged
556 For the scoping of individual macros, see
562 Multiple authors should each be accorded their own
565 Author names should be ordered with full or abbreviated forename(s)
566 first, then full surname.
571 This macro may also be used in a non-bibliographic context when
572 referring to book titles.
574 Publication city or location of an
578 Publication date of an
581 Recommended formats of arguments are
586 Publisher or issuer name of an
594 Issue number (usually for journals) of an
598 Optional information of an
602 Book or journal page number of an
606 Institutional author (school, government, etc.) of an
609 Multiple institutional authors should each be accorded their own
613 Technical report name of an
620 This macro may also be used in a non-bibliographical context when
621 referring to article titles.
623 URI of reference document.
632 Does not have any tail arguments.
635 Do not use this for postal addresses.
642 Can be used both for the authors of the program, function, or driver
643 documented in the manual, or for the authors of the manual itself.
644 Requires either the name of an author or one of the following arguments:
646 .Bl -tag -width "-nosplitX" -offset indent -compact
648 Start a new output line before each subsequent invocation of
657 The effect of selecting either of the
659 modes ends at the beginning of the
664 section, the default is
666 for the first author listing and
668 for all other author listings.
672 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
674 Begin a block enclosed by angle brackets.
675 Does not have any head arguments.
678 .Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
683 Inserts an apostrophe without any surrounding whitespace.
684 This is generally used as a grammatical device when referring to the verb
688 .Dl \&.Fn execve \&Ap d
690 Encloses its arguments in angle brackets.
693 .Dl \&.Fl -key= \&Ns \&Aq \&Ar val
696 this macro is often abused for rendering URIs, which should instead use
700 or to note pre-processor
702 statements, which should use
709 If an argument is not provided, the string
711 is used as a default.
716 .Dl ".Ar arg1 , arg2 ."
720 macro are names and placeholders for command arguments;
721 for fixed strings to be passed verbatim as arguments, use
729 Accepts one optional argument:
731 .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
742 Note that these arguments do not begin with a hyphen.
762 Does not have any tail arguments.
764 Begin a display block.
765 Its syntax is as follows:
766 .Bd -ragged -offset indent
769 .Op Fl offset Ar width
773 Display blocks are used to select a different indentation and
774 justification than the one used by the surrounding text.
775 They may contain both macro lines and text lines.
776 By default, a display block is preceded by a vertical space.
780 must be one of the following:
781 .Bl -tag -width 13n -offset indent
783 Produce one output line from each input line, and centre-justify each line.
784 Using this display type is not recommended; many
786 implementations render it poorly.
788 Change the positions of line breaks to fill each line, and left- and
789 right-justify the resulting block.
791 Produce one output line from each input line,
792 and do not justify the block at all.
793 Preserve white space as it appears in the input.
794 Always use a constant-width font.
795 Use this for displaying source code.
797 Change the positions of line breaks to fill each line, and left-justify
802 but using the same font as for normal text, which is a variable width font
803 if supported by the output device.
808 must be provided first.
809 Additional arguments may follow:
810 .Bl -tag -width 13n -offset indent
811 .It Fl offset Ar width
812 Indent the display by the
814 which may be one of the following:
817 One of the pre-defined strings
819 the width of a standard indentation (six constant width characters);
826 which justifies to the right margin; or
828 which aligns around an imagined centre axis.
830 A macro invocation, which selects a predefined width
831 associated with that macro.
832 The most popular is the imaginary macro
837 A scaling width as described in
840 An arbitrary string, which indents by the length of this string.
843 When the argument is missing,
847 Do not assert vertical space before the display.
851 .Bd -literal -offset indent
852 \&.Bd \-literal \-offset indent \-compact
862 Change the font mode for a scoped block of text.
863 Its syntax is as follows:
864 .Bd -ragged -offset indent
867 .Fl emphasis | literal | symbolic |
868 .Cm \&Em | \&Li | \&Sy
876 argument are equivalent, as are
884 Without an argument, this macro does nothing.
885 The font mode continues until broken by a new font mode in a nested
897 For each macro, keep its output together on the same output line,
898 until the end of the macro or the end of the input line is reached,
899 whichever comes first.
900 Line breaks in text lines are unaffected.
901 The syntax is as follows:
903 .D1 Pf \. Sx \&Bk Fl words
907 argument is required; additional arguments are ignored.
909 The following example will not break within each
912 .Bd -literal -offset indent
919 Be careful in using over-long lines within a keep block!
920 Doing so will clobber the right margin.
923 Lists consist of items specified using the
925 macro, containing a head or a body or both.
926 The list syntax is as follows:
927 .Bd -ragged -offset indent
938 is mandatory and must be specified first.
943 arguments accept scaling widths as described in
945 or use the length of the given string.
948 is a global indentation for the whole list, affecting both item heads
950 For those list types supporting it, the
952 argument requests an additional indentation of item bodies,
957 argument is specified, list entries are separated by vertical space.
959 A list must specify one of the following list types:
960 .Bl -tag -width 12n -offset indent
962 No item heads can be specified, but a bullet will be printed at the head
964 Item bodies start on the same output line as the bullet
965 and are indented according to the
972 argument has no effect; instead, each argument specifies the width
973 of one column, using either the scaling width syntax described in
975 or the string length of the argument.
976 If the first line of the body of a
982 contexts spanning one input line each are implied until an
984 macro line is encountered, at which point items start being interpreted as
991 except that dashes are used in place of bullets.
995 except that item heads are not parsed for macro invocations.
996 Most often used in the
998 section with error constants in the item heads.
1001 No item heads can be specified.
1004 except that cardinal numbers are used in place of bullets,
1009 except that the first lines of item bodies are not indented, but follow
1010 the item heads like in
1017 Item bodies follow items heads on the same line, using normal inter-word
1019 Bodies are not indented, and the
1021 argument is ignored.
1023 No item heads can be specified, and none are printed.
1024 Bodies are not indented, and the
1026 argument is ignored.
1028 Item bodies start on the line following item heads and are not indented.
1031 argument is ignored.
1033 Item bodies are indented according to the
1036 When an item head fits inside the indentation, the item body follows
1037 this head on the same output line.
1038 Otherwise, the body starts on the output line following the head.
1041 Lists may be nested within lists and displays.
1046 lists may not be portable.
1053 Begin a block enclosed by square brackets.
1054 Does not have any head arguments.
1057 .Bd -literal -offset indent -compact
1065 Encloses its arguments in square brackets.
1068 .Dl \&.Bq 1 , \&Dv BUFSIZ
1071 this macro is sometimes abused to emulate optional arguments for
1072 commands; the correct macros to use for this purpose are
1084 Does not have any tail arguments.
1086 Begin a block enclosed by curly braces.
1087 Does not have any head arguments.
1090 .Bd -literal -offset indent -compact
1098 Encloses its arguments in curly braces.
1101 .Dl \&.Brq 1 , ... , \&Va n
1108 version provided as an argument, or a default value if
1109 no argument is provided.
1126 .Dq is currently in beta test.
1130 version provided as an argument, or a default value if no
1131 argument is provided.
1148 Kernel configuration declaration.
1149 This denotes strings accepted by
1151 It is most often used in section 4 manual pages.
1154 .Dl \&.Cd device le0 at scode?
1157 this macro is commonly abused by using quoted literals to retain
1158 whitespace and align consecutive
1161 This practise is discouraged.
1164 Typically used for fixed strings passed as arguments, unless
1166 is more appropriate.
1167 Also useful when specifying configuration options or keys.
1170 .Dl ".Nm mt Fl f Ar device Cm rewind"
1171 .Dl ".Nm ps Fl o Cm pid , Ns Cm command"
1172 .Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
1173 .Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa"
1174 .Dl ".Cm LogLevel Dv DEBUG"
1176 One-line indented display.
1177 This is formatted by the default rules and is useful for simple indented
1179 It is followed by a newline.
1182 .Dl \&.D1 \&Fl abcdefgh
1189 Switch debugging mode.
1190 Its syntax is as follows:
1192 .D1 Pf \. Sx \&Db Cm on | off
1194 This macro is ignored by
1200 Does not have any tail arguments.
1203 This is the mandatory first macro of any
1206 Its syntax is as follows:
1208 .D1 Pf \. Sx \&Dd Ar month day , year
1212 is the full English month name, the
1214 is an optionally zero-padded numeral, and the
1216 is the full four-digit year.
1218 Other arguments are not portable; the
1220 utility handles them as follows:
1221 .Bl -dash -offset 3n -compact
1223 To have the date automatically filled in by the
1229 can be given as an argument.
1231 A few alternative date formats are accepted as well
1232 and converted to the standard form.
1234 If a date string cannot be parsed, it is used verbatim.
1236 If no date string is given, the current date is used.
1240 .Dl \&.Dd $\&Mdocdate$
1241 .Dl \&.Dd $\&Mdocdate: July 21 2007$
1242 .Dl \&.Dd July 21, 2007
1249 One-line intended display.
1250 This is formatted as literal text and is useful for commands and
1252 It is followed by a newline.
1255 .Dl \&.Dl % mandoc mdoc.7 \e(ba less
1262 Begin a block enclosed by double quotes.
1263 Does not have any head arguments.
1266 .Bd -literal -offset indent -compact
1268 April is the cruellest month
1276 Encloses its arguments in
1281 .Bd -literal -offset indent -compact
1282 \&.Dq April is the cruellest month
1293 This is the mandatory second macro of any
1296 Its syntax is as follows:
1297 .Bd -ragged -offset indent
1309 Its arguments are as follows:
1310 .Bl -tag -width Ds -offset Ds
1312 The document's title (name), defaulting to
1315 It should be capitalised.
1326 .Pq Perl libraries ,
1336 .Pq system utilities ,
1338 .Pq kernel functions ,
1340 .Pq X Window System ,
1342 .Pq X Window System ,
1352 It should correspond to the manual's filename suffix and defaults to
1356 This overrides the volume inferred from
1358 This field is optional, and if specified, must be one of
1360 .Pq users' supplementary documents ,
1362 .Pq programmers' supplementary documents ,
1364 .Pq administrators' supplementary documents ,
1366 .Pq system managers' manuals ,
1368 .Pq users' reference manuals ,
1370 .Pq programmers' reference manuals ,
1372 .Pq kernel manuals ,
1383 .Pq contributed manuals .
1385 This specifies the machine architecture a manual page applies to,
1386 where relevant, for example
1392 The list of supported architectures varies by operating system.
1393 For the full list of all architectures recognized by
1397 in the source distribution.
1403 .Dl \&.Dt FOO 9 i386
1410 Defined variables such as preprocessor constants, constant symbols,
1411 enumeration values, and so on.
1416 .Dl \&.Dv STDOUT_FILENO
1422 for special-purpose constants,
1424 for variable symbols, and
1426 for listing preprocessor variable definitions in the
1431 version provided as an argument, or a default
1432 value if no argument is provided.
1448 Close a scope started by
1450 Its syntax is as follows:
1452 .D1 Pf \. Sx \&Ec Op Ar TERM
1456 argument is used as the enclosure tail, for example, specifying \e(rq
1460 End a display context started by
1463 End a font mode context started by
1466 End a keep context started by
1469 End a list context started by
1477 Denotes text that should be
1479 Note that this is a presentation term and should not be used for
1480 stylistically decorating technical terms.
1481 Depending on the output device, this is usually represented
1482 using an italic font or underlined characters.
1495 This macro is obsolete and not implemented in
1498 An arbitrary enclosure.
1499 Its syntax is as follows:
1501 .D1 Pf \. Sx \&Eo Op Ar TERM
1505 argument is used as the enclosure head, for example, specifying \e(lq
1509 Error constants for definitions of the
1511 libc global variable.
1512 This is most often used in section 2 and 3 manual pages.
1520 for general constants.
1522 This macro is obsolete and not implemented.
1524 Environmental variables such as those specified in
1533 for general constants.
1535 Insert a standard sentence regarding command exit values of 0 on success
1537 This is most often used in section 1, 6, and 8 manual pages.
1538 Its syntax is as follows:
1540 .D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
1544 is not specified, the document's name set by
1549 arguments are treated as separate utilities.
1555 Its syntax is as follows:
1556 .Bd -ragged -offset indent
1562 This may be invoked for names with or without the corresponding type.
1563 It is also used to specify the field name of a structure.
1566 macro is used in the
1570 section when documenting multi-line function prototypes.
1571 If invoked with multiple arguments, the arguments are separated by a
1573 Furthermore, if the following macro is another
1575 the last argument will also have a trailing comma.
1578 .Dl \&.Fa \(dqconst char *p\(dq
1579 .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
1585 End a function context started by
1588 Preprocessor directive, in particular for listing it in the
1590 Historically, it was also used to document include files.
1591 The latter usage has been deprecated in favour of
1594 Its syntax is as follows:
1595 .Bd -ragged -offset indent
1597 .Li # Ns Ar directive
1602 .Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler
1603 .Dl \&.Fd #define SIO_MAXNFDS
1604 .Dl \&.Fd #ifdef FS_DEBUG
1606 .Dl \&.Fn dbg_open \(dqconst char *\(dq
1610 .Sx MANUAL STRUCTURE ,
1615 Command-line flag or option.
1616 Used when listing arguments to command-line utilities.
1617 Prints a fixed-width hyphen
1619 directly followed by each argument.
1620 If no arguments are provided, a hyphen is printed followed by a space.
1621 If the argument is a macro, a hyphen is prefixed to the subsequent macro
1625 .Dl ".Fl R Op Fl H | L | P"
1626 .Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
1627 .Dl ".Fl type Cm d Fl name Pa CVS"
1628 .Dl ".Fl Ar signal_number"
1635 Its syntax is as follows:
1636 .Bd -ragged -offset indent
1640 .Op Oo Ar argtype Oc Ar argname
1643 Function arguments are surrounded in parenthesis and
1644 are delimited by commas.
1645 If no arguments are specified, blank parenthesis are output.
1648 section, this macro starts a new output line,
1649 and a blank line is automatically inserted between function definitions.
1652 .Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
1653 .Dl \&.Fn funcname \(dqint arg0\(dq
1654 .Dl \&.Fn funcname arg0
1656 .Bd -literal -offset indent -compact
1661 When referring to a function documented in another manual page, use
1665 .Sx MANUAL STRUCTURE ,
1670 Begin a function block.
1671 This is a multi-line version of
1673 Its syntax is as follows:
1675 .D1 Pf \. Sx \&Fo Ar funcname
1677 Invocations usually occur in the following context:
1678 .Bd -ragged -offset indent
1679 .Pf \. Sx \&Ft Ar functype
1681 .Pf \. Sx \&Fo Ar funcname
1683 .Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname
1696 .Sx MANUAL STRUCTURE ,
1702 This macro is obsolete and not implemented in
1705 It was used to show function return values.
1708 .Dl Pf . Sx \&Fr Ar value
1711 Its syntax is as follows:
1713 .D1 Pf \. Sx \&Ft Ar functype
1717 section, a new output line is started after this macro.
1721 .Bd -literal -offset indent -compact
1727 .Sx MANUAL STRUCTURE ,
1734 version provided as an argument, or a default value
1735 if no argument is provided.
1751 This macro is not implemented in
1754 It was used to include the contents of a (header) file literally.
1757 .Dl Pf . Sx \&Hf Ar filename
1759 Designate an internal or interactive command.
1762 but used for instructions rather than values.
1773 is preferred for displaying code; the
1775 macro is used when referring to specific instructions.
1780 When invoked as the first macro on an input line in the
1782 section, the argument is displayed in angle brackets
1785 and a blank line is inserted in front if there is a preceding
1786 function declaration.
1787 This is most often used in section 2, 3, and 9 manual pages.
1790 .Dl \&.In sys/types.h
1793 .Sx MANUAL STRUCTURE .
1796 The syntax of this macro depends on the list type.
1805 have the following syntax:
1807 .D1 Pf \. Sx \&It Ar args
1816 have the following syntax:
1820 with subsequent lines interpreted within the scope of the
1822 until either a closing
1829 list has the following syntax:
1831 .D1 Pf \. Sx \&It Op Cm args
1833 Subsequent lines are interpreted as with
1836 The line arguments correspond to the list's left-hand side; body
1837 arguments correspond to the list's contents.
1841 list is the most complicated.
1842 Its syntax is as follows:
1844 .D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
1845 .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
1847 The arguments consist of one or more lines of text and macros
1848 representing a complete table line.
1849 Cells within the line are delimited by tabs or by the special
1852 The tab cell delimiter may only be used within the
1854 line itself; on following lines, only the
1856 macro can be used to delimit cells, and
1858 is only recognised as a macro when called by other macros,
1859 not as the first macro on a line.
1861 Note that quoted strings may span tab-delimited cells on an
1866 .Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
1868 will preserve the semicolon whitespace except for the last.
1874 The syntax is as follows:
1876 .D1 Pf \. Sx \&Lb Ar library
1880 parameter may be a system library, such as
1884 in which case a small library description is printed next to the linker
1885 invocation; or a custom library, in which case the library name is
1887 This is most commonly used in the
1889 section as described in
1890 .Sx MANUAL STRUCTURE .
1896 Denotes text that should be in a
1899 Note that this is a presentation term and should not be used for
1900 stylistically decorating technical terms.
1902 On terminal output devices, this is often indistinguishable from
1913 Its syntax is as follows:
1915 .D1 Pf \. Sx \&Lk Ar uri Op Ar name
1918 .Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
1919 .Dl \&.Lk http://bsd.lv
1927 Display a mathematical symbol.
1928 Its syntax is as follows:
1930 .D1 Pf \. Sx \&Ms Ar symbol
1939 Its syntax is as follows:
1941 .D1 Pf \. Sx \&Mt Ar address
1944 .Dl \&.Mt discuss@manpages.bsd.lv
1945 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
1947 A one line description of the manual's content.
1948 This may only be invoked in the
1950 section subsequent the
1955 .Dl Pf . Sx \&Nd mdoc language reference
1956 .Dl Pf . Sx \&Nd format and display UNIX manuals
1960 macro technically accepts child macros and terminates with a subsequent
1963 Do not assume this behaviour: some
1965 database generators are not smart enough to parse more than the line
1966 arguments and will display macros verbatim.
1971 The name of the manual page, or \(em in particular in section 1, 6,
1972 and 8 pages \(em of an additional command or feature documented in
1974 When first invoked, the
1976 macro expects a single argument, the name of the manual page.
1977 Usually, the first invocation happens in the
1979 section of the page.
1980 The specified name will be remembered and used whenever the macro is
1981 called again without arguments later in the page.
1985 .Sx Block full-implicit
1986 semantics when invoked as the first macro on an input line in the
1988 section; otherwise, it uses ordinary
1993 .Bd -literal -offset indent
2002 of section 2, 3 and 9 manual pages, use the
2006 to mark up the name of the manual page.
2009 Closes the scope of any preceding in-line macro.
2010 When used after physical formatting macros like
2014 switches back to the standard font face and weight.
2015 Can also be used to embed plain text strings in macro lines
2016 using semantic annotation macros.
2019 .Dl ".Em italic , Sy bold , No and roman"
2021 .Bd -literal -offset indent -compact
2023 \&.Cm :C No / Ar pattern No / Ar replacement No /
2033 Suppress a space between the output of the preceding macro
2034 and the following text or macro.
2035 Following invocation, input is interpreted as normal text
2040 This has no effect when invoked at the start of a macro line.
2043 .Dl ".Ar name Ns = Ns Ar value"
2044 .Dl ".Cm :M Ns Ar pattern"
2045 .Dl ".Fl o Ns Ar output"
2054 version provided as an argument, or a default value if
2055 no argument is provided.
2075 Multi-line version of
2079 .Bd -literal -offset indent -compact
2081 \&.Op Fl flag Ns Ar value
2085 Optional part of a command line.
2086 Prints the argument(s) in brackets.
2087 This is most often used in the
2089 section of section 1 and 8 manual pages.
2092 .Dl \&.Op \&Fl a \&Ar b
2093 .Dl \&.Op \&Ar a | b
2098 Document operating system version.
2099 This is the mandatory third macro of
2103 Its syntax is as follows:
2105 .D1 Pf \. Sx \&Os Op Ar system Op Ar version
2109 parameter specifies the relevant operating system or environment.
2110 Left unspecified, it defaults to the local operating system version.
2111 This is the suggested form.
2115 .Dl \&.Os KTH/CSC/TCS
2123 This macro is obsolete and not implemented in
2128 packages described it as
2129 .Dq "old function type (FORTRAN)" .
2133 version provided as an argument, or a default value
2134 if no argument is provided.
2150 An absolute or relative file system path, or a file or directory name.
2151 If an argument is not provided, the character
2153 is used as a default.
2156 .Dl \&.Pa /usr/bin/mandoc
2157 .Dl \&.Pa /usr/share/man/man7/mdoc.7
2162 Close parenthesised context opened by
2165 Removes the space between its argument
2167 and the following macro.
2168 Its syntax is as follows:
2170 .D1 .Pf Ar prefix macro arguments ...
2172 This is equivalent to:
2174 .D1 .No Ar prefix No \&Ns Ar macro arguments ...
2177 .Dl ".Pf $ Ar variable_name"
2178 .Dl ".Pf 0x Ar hex_digits"
2185 Multi-line version of
2189 This will assert vertical space between prior and subsequent macros
2192 Paragraph breaks are not needed before or after
2196 macros or before displays
2204 Parenthesised enclosure.
2209 Close quoted context opened by
2212 Format a single-quoted literal.
2218 Multi-line version of
2221 Encloses its arguments in
2236 Does not have any tail arguments.
2238 Begin a bibliographic
2241 Does not have any head arguments.
2242 The block macro may only contain
2258 child macros (at least one must be specified).
2261 .Bd -literal -offset indent -compact
2263 \&.%A J. E. Hopcroft
2265 \&.%B Introduction to Automata Theory, Languages, and Computation
2266 \&.%I Addison-Wesley
2267 \&.%C Reading, Massachusettes
2274 block is used within a SEE ALSO section, a vertical space is asserted
2275 before the rendered output, else the block continues on the current
2278 Insert a standard sentence regarding a function call's return value of 0
2279 on success and \-1 on error, with the
2281 libc global variable set on error.
2282 Its syntax is as follows:
2284 .D1 Pf \. Sx \&Rv Fl std Op Ar function ...
2288 is not specified, the document's name set by
2293 arguments are treated as separate functions.
2298 Close single-quoted context opened by
2301 Begin a new section.
2302 For a list of conventional manual sections, see
2303 .Sx MANUAL STRUCTURE .
2304 These sections should be used unless it's absolutely necessary that
2305 custom sections be used.
2307 Section names should be unique so that they may be keyed by
2309 Although this macro is parsed, it should not consist of child node or it
2310 may not be linked with
2319 Switches the spacing mode for output generated from macros.
2320 Its syntax is as follows:
2322 .D1 Pf \. Sx \&Sm Cm on | off
2324 By default, spacing is
2328 no white space is inserted between macro arguments and between the
2329 output generated from adjacent macros, but text lines
2330 still get normal spacing between words and sentences.
2332 Multi-line version of
2335 Encloses its arguments in
2345 Begin a new subsection.
2348 there is no convention for the naming of subsections.
2351 the conventional sections described in
2352 .Sx MANUAL STRUCTURE
2353 rarely have subsections.
2355 Sub-section names should be unique so that they may be keyed by
2357 Although this macro is parsed, it should not consist of child node or it
2358 may not be linked with
2367 Replace an abbreviation for a standard with the full form.
2368 The following standards are recognised.
2369 Where multiple lines are given without a blank line in between,
2370 they all refer to the same standard, and using the first form
2373 .It C language standards
2375 .Bl -tag -width "-p1003.1g-2000" -compact
2385 The original C standard.
2401 The second major version of the C language standard.
2406 The third major version of the C language standard.
2408 .It POSIX.1 before the Single UNIX Specification
2410 .Bl -tag -width "-p1003.1g-2000" -compact
2416 The original POSIX standard, based on ANSI C.
2423 The first update of POSIX.1.
2430 Real-time extensions.
2435 POSIX thread interfaces.
2440 Technical Corrigendum.
2447 Includes POSIX.1-1990, 1b, 1c, and 1i.
2449 .It X/Open Portability Guide version 4 and related standards
2451 .Bl -tag -width "-p1003.1g-2000" -compact
2455 An XPG4 precursor, published in 1989.
2474 Based on POSIX.1 and POSIX.2, published in 1992.
2476 .It Single UNIX Specification version 1 and related standards
2478 .Bl -tag -width "-p1003.1g-2000" -compact
2482 This standard was published in 1994 and is also called SUSv1.
2483 It was used as the basis for UNIX 95 certification.
2484 The following three refer to parts of it.
2495 Networking APIs, including sockets.
2505 .It Single UNIX Specification version 2 and related standards
2507 .Bl -tag -width "-p1003.1g-2000" -compact
2510 This Standard was published in 1997
2511 and is also called X/Open Portability Guide version 5.
2512 It was used as the basis for UNIX 98 certification.
2513 The following refer to parts of it.
2536 POSIX software administration.
2538 .It Single UNIX Specification version 3 and related standards
2540 .Bl -tag -width "-p1003.1g-2000X" -compact
2544 Additional real-time extensions.
2549 Advanced real-time extensions.
2554 Amendment 7: Tracing [C Language].
2561 This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j.
2562 It is also called X/Open Portability Guide version 6.
2563 It is used as the basis for UNIX 03 certification.
2568 The second and last Technical Corrigendum.
2570 .It Single UNIX Specification version 4
2572 .Bl -tag -width "-p1003.1g-2000" -compact
2576 This standard is also called SUSv4 and
2577 X/Open Portability Guide version 7.
2582 This is the first Technical Corrigendum.
2586 .Bl -tag -width "-p1003.1g-2000" -compact
2590 Floating-point arithmetic.
2595 Representation of dates and times, published in 1988.
2600 Ethernet local area networks.
2607 Reference a section or subsection in the same manual page.
2608 The referenced section or subsection name must be identical to the
2609 enclosed argument, including whitespace.
2612 .Dl \&.Sx MANUAL STRUCTURE
2619 Format enclosed arguments in symbolic
2621 Note that this is a presentation term and should not be used for
2622 stylistically decorating technical terms.
2631 Table cell separator in
2633 lists; can only be used below
2638 Since this macro is often implemented to use a small caps font,
2639 it has historically been used for acronyms (like ASCII) as well.
2640 Such usage is not recommended because it would use the same macro
2641 sometimes for semantical annotation, sometimes for physical formatting.
2647 .Dq currently under development.
2652 Accepts no argument.
2671 .Dl \&.Va const char *bar ;
2674 This is also used for indicating global variables in the
2676 section, in which case a variable name is also specified.
2677 Note that it accepts
2678 .Sx Block partial-implicit
2679 syntax when invoked as the first macro on an input line in the
2681 section, else it accepts ordinary
2684 In the former case, this macro starts a new output line,
2685 and a blank line is inserted in front if there is a preceding
2686 function definition or include directive.
2688 Note that this should not be confused with
2690 which is used for function return types.
2693 .Dl \&.Vt unsigned char
2694 .Dl \&.Vt extern const char * const sys_signame[] \&;
2697 .Sx MANUAL STRUCTURE
2701 Close a scope opened by
2704 Extend the header of an
2706 macro or the body of a partial-implicit block macro
2707 beyond the end of the input line.
2708 This macro originally existed to work around the 9-argument limit
2712 Link to another manual
2713 .Pq Qq cross-reference .
2714 Its syntax is as follows:
2716 .D1 Pf \. Sx \&Xr Ar name Op section
2722 number of another man page;
2723 omitting the section number is rarely useful.
2727 .Dl \&.Xr mandoc 1 \&;
2728 .Dl \&.Xr mandoc 1 \&Ns s behaviour
2731 This macro should not be used; it is implemented for compatibility with
2736 in the event of natural paragraph breaks.
2738 Emits vertical space.
2739 This macro should not be used; it is implemented for compatibility with
2741 Its syntax is as follows:
2743 .D1 Pf \. Sx \&sp Op Ar height
2747 argument is a scaling width as described in
2751 asserts a single vertical space.
2753 The syntax of a macro depends on its classification.
2756 refers to macro arguments, which may be followed by zero or more
2760 opens the scope of a macro; and if specified,
2766 column indicates that the macro may also be called by passing its name
2767 as an argument to another macro.
2769 .Sq \&.Op \&Fl O \&Ar file
2771 .Sq Op Fl O Ar file .
2772 To prevent a macro call and render the macro name literally,
2773 escape it by prepending a zero-width space,
2779 If a macro is not callable but its name appears as an argument
2780 to another macro, it is interpreted as opaque text.
2788 column indicates whether the macro may call other macros by receiving
2789 their names as arguments.
2790 If a macro is not parsed but the name of another macro appears
2791 as an argument, it is interpreted as opaque text.
2795 column, if applicable, describes closure rules.
2796 .Ss Block full-explicit
2797 Multi-line scope closed by an explicit closing macro.
2798 All macros contains bodies; only
2804 .Bd -literal -offset indent
2805 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2809 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
2810 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2811 .It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
2812 .It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
2813 .It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
2814 .It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
2815 .It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
2816 .It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
2817 .It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
2818 .It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
2820 .Ss Block full-implicit
2821 Multi-line scope closed by end-of-file or implicitly by another macro.
2822 All macros have bodies; some
2824 .Sx \&It Fl bullet ,
2830 don't have heads; only one
2837 .Bd -literal -offset indent
2838 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
2841 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
2842 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2843 .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
2844 .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
2845 .It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
2846 .It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh
2847 .It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss
2853 .Sx Block full-implicit
2854 macro only when invoked as the first macro
2857 section line, else it is
2859 .Ss Block partial-explicit
2860 Like block full-explicit, but also with single-line scope.
2861 Each has at least a body and, in limited circumstances, a head
2868 .Bd -literal -offset indent
2869 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2871 \&.Yc \(lBtail...\(rB
2873 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
2874 \(lBbody...\(rB \&Yc \(lBtail...\(rB
2876 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
2877 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2878 .It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
2879 .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
2880 .It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
2881 .It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
2882 .It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
2883 .It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
2884 .It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
2885 .It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
2886 .It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
2887 .It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
2888 .It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
2889 .It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
2890 .It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
2891 .It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
2892 .It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
2893 .It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
2894 .It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
2895 .It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
2896 .It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
2897 .It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
2898 .It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
2899 .It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
2900 .It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
2901 .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
2903 .Ss Block partial-implicit
2904 Like block full-implicit, but with single-line scope closed by the
2906 .Bd -literal -offset indent
2907 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
2909 .Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
2910 .It Em Macro Ta Em Callable Ta Em Parsed
2911 .It Sx \&Aq Ta Yes Ta Yes
2912 .It Sx \&Bq Ta Yes Ta Yes
2913 .It Sx \&Brq Ta Yes Ta Yes
2914 .It Sx \&D1 Ta \&No Ta \&Yes
2915 .It Sx \&Dl Ta \&No Ta Yes
2916 .It Sx \&Dq Ta Yes Ta Yes
2917 .It Sx \&Op Ta Yes Ta Yes
2918 .It Sx \&Pq Ta Yes Ta Yes
2919 .It Sx \&Ql Ta Yes Ta Yes
2920 .It Sx \&Qq Ta Yes Ta Yes
2921 .It Sx \&Sq Ta Yes Ta Yes
2922 .It Sx \&Vt Ta Yes Ta Yes
2928 .Sx Block partial-implicit
2929 only when invoked as the first macro
2932 section line, else it is
2934 .Ss Special block macro
2937 macro can only be used below
2942 It delimits blocks representing table cells;
2943 these blocks have bodies, but no heads.
2944 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
2945 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2946 .It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It
2949 Closed by the end of the line, fixed argument lengths,
2950 and/or subsequent macros.
2951 In-line macros have only text children.
2952 If a number (or inequality) of arguments is
2954 then the macro accepts an arbitrary number of arguments.
2955 .Bd -literal -offset indent
2956 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
2958 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
2960 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
2962 .Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
2963 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
2964 .It Sx \&%A Ta \&No Ta \&No Ta >0
2965 .It Sx \&%B Ta \&No Ta \&No Ta >0
2966 .It Sx \&%C Ta \&No Ta \&No Ta >0
2967 .It Sx \&%D Ta \&No Ta \&No Ta >0
2968 .It Sx \&%I Ta \&No Ta \&No Ta >0
2969 .It Sx \&%J Ta \&No Ta \&No Ta >0
2970 .It Sx \&%N Ta \&No Ta \&No Ta >0
2971 .It Sx \&%O Ta \&No Ta \&No Ta >0
2972 .It Sx \&%P Ta \&No Ta \&No Ta >0
2973 .It Sx \&%Q Ta \&No Ta \&No Ta >0
2974 .It Sx \&%R Ta \&No Ta \&No Ta >0
2975 .It Sx \&%T Ta \&No Ta \&No Ta >0
2976 .It Sx \&%U Ta \&No Ta \&No Ta >0
2977 .It Sx \&%V Ta \&No Ta \&No Ta >0
2978 .It Sx \&Ad Ta Yes Ta Yes Ta >0
2979 .It Sx \&An Ta Yes Ta Yes Ta >0
2980 .It Sx \&Ap Ta Yes Ta Yes Ta 0
2981 .It Sx \&Ar Ta Yes Ta Yes Ta n
2982 .It Sx \&At Ta Yes Ta Yes Ta 1
2983 .It Sx \&Bsx Ta Yes Ta Yes Ta n
2984 .It Sx \&Bt Ta \&No Ta \&No Ta 0
2985 .It Sx \&Bx Ta Yes Ta Yes Ta n
2986 .It Sx \&Cd Ta Yes Ta Yes Ta >0
2987 .It Sx \&Cm Ta Yes Ta Yes Ta >0
2988 .It Sx \&Db Ta \&No Ta \&No Ta 1
2989 .It Sx \&Dd Ta \&No Ta \&No Ta n
2990 .It Sx \&Dt Ta \&No Ta \&No Ta n
2991 .It Sx \&Dv Ta Yes Ta Yes Ta >0
2992 .It Sx \&Dx Ta Yes Ta Yes Ta n
2993 .It Sx \&Em Ta Yes Ta Yes Ta >0
2994 .It Sx \&En Ta \&No Ta \&No Ta 0
2995 .It Sx \&Er Ta Yes Ta Yes Ta >0
2996 .It Sx \&Es Ta \&No Ta \&No Ta 0
2997 .It Sx \&Ev Ta Yes Ta Yes Ta >0
2998 .It Sx \&Ex Ta \&No Ta \&No Ta n
2999 .It Sx \&Fa Ta Yes Ta Yes Ta >0
3000 .It Sx \&Fd Ta \&No Ta \&No Ta >0
3001 .It Sx \&Fl Ta Yes Ta Yes Ta n
3002 .It Sx \&Fn Ta Yes Ta Yes Ta >0
3003 .It Sx \&Fr Ta \&No Ta \&No Ta n
3004 .It Sx \&Ft Ta Yes Ta Yes Ta >0
3005 .It Sx \&Fx Ta Yes Ta Yes Ta n
3006 .It Sx \&Hf Ta \&No Ta \&No Ta n
3007 .It Sx \&Ic Ta Yes Ta Yes Ta >0
3008 .It Sx \&In Ta \&No Ta \&No Ta 1
3009 .It Sx \&Lb Ta \&No Ta \&No Ta 1
3010 .It Sx \&Li Ta Yes Ta Yes Ta >0
3011 .It Sx \&Lk Ta Yes Ta Yes Ta >0
3012 .It Sx \&Lp Ta \&No Ta \&No Ta 0
3013 .It Sx \&Ms Ta Yes Ta Yes Ta >0
3014 .It Sx \&Mt Ta Yes Ta Yes Ta >0
3015 .It Sx \&Nm Ta Yes Ta Yes Ta n
3016 .It Sx \&No Ta Yes Ta Yes Ta 0
3017 .It Sx \&Ns Ta Yes Ta Yes Ta 0
3018 .It Sx \&Nx Ta Yes Ta Yes Ta n
3019 .It Sx \&Os Ta \&No Ta \&No Ta n
3020 .It Sx \&Ot Ta \&No Ta \&No Ta n
3021 .It Sx \&Ox Ta Yes Ta Yes Ta n
3022 .It Sx \&Pa Ta Yes Ta Yes Ta n
3023 .It Sx \&Pf Ta Yes Ta Yes Ta 1
3024 .It Sx \&Pp Ta \&No Ta \&No Ta 0
3025 .It Sx \&Rv Ta \&No Ta \&No Ta n
3026 .It Sx \&Sm Ta \&No Ta \&No Ta 1
3027 .It Sx \&St Ta \&No Ta Yes Ta 1
3028 .It Sx \&Sx Ta Yes Ta Yes Ta >0
3029 .It Sx \&Sy Ta Yes Ta Yes Ta >0
3030 .It Sx \&Tn Ta Yes Ta Yes Ta >0
3031 .It Sx \&Ud Ta \&No Ta \&No Ta 0
3032 .It Sx \&Ux Ta Yes Ta Yes Ta n
3033 .It Sx \&Va Ta Yes Ta Yes Ta n
3034 .It Sx \&Vt Ta Yes Ta Yes Ta >0
3035 .It Sx \&Xr Ta Yes Ta Yes Ta >0
3036 .It Sx \&br Ta \&No Ta \&No Ta 0
3037 .It Sx \&sp Ta \&No Ta \&No Ta 1
3040 When a macro argument consists of one single input character
3041 considered as a delimiter, the argument gets special handling.
3042 This does not apply when delimiters appear in arguments containing
3043 more than one character.
3044 Consequently, to prevent special handling and just handle it
3045 like any other argument, a delimiter can be escaped by prepending
3048 In text lines, delimiters never need escaping, but may be used
3049 as normal punctuation.
3051 For many macros, when the leading arguments are opening delimiters,
3052 these delimiters are put before the macro scope,
3053 and when the trailing arguments are closing delimiters,
3054 these delimiters are put after the macro scope.
3057 .D1 Pf \. \&Aq "( [ word ] ) ."
3061 .D1 Aq ( [ word ] ) .
3063 Opening delimiters are:
3065 .Bl -tag -width Ds -offset indent -compact
3072 Closing delimiters are:
3074 .Bl -tag -width Ds -offset indent -compact
3093 Note that even a period preceded by a backslash
3095 gets this special handling; use
3099 Many in-line macros interrupt their scope when they encounter
3100 delimiters, and resume their scope when more arguments follow that
3104 .D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e"
3108 .D1 Fl a ( b | c \*(Ba d ) e
3110 This applies to both opening and closing delimiters,
3111 and also to the middle delimiter:
3113 .Bl -tag -width Ds -offset indent -compact
3118 As a special case, the predefined string \e*(Ba is handled and rendered
3119 in the same way as a plain
3122 Using this predefined string is not recommended in new manuals.
3126 documents, usage of semantic markup is recommended in order to have
3127 proper fonts automatically selected; only when no fitting semantic markup
3128 is available, consider falling back to
3135 font mode, it will automatically restore the previous font when exiting
3137 Manually switching the font using the
3140 font escape sequences is never required.
3142 This section provides an incomplete list of compatibility issues
3143 between mandoc and other troff implementations, at this time limited
3148 refers to groff versions before 1.17,
3149 which featured a significant update of the
3153 Heirloom troff, the other significant troff implementation accepting
3154 \-mdoc, is similar to historic groff.
3156 The following problematic behaviour is found in groff:
3157 .ds hist (Historic groff only.)
3172 with unknown arguments produces no output at all.
3174 Newer groff and mandoc print
3179 does not recognise trailing punctuation characters when they immediately
3180 precede tabulator characters, but treats them as normal text and
3181 outputs a space before them.
3183 .Sx \&Bd Fl ragged compact
3184 does not start a new line.
3188 with non-standard arguments behaves very strangely.
3189 When there are three arguments, they are printed verbatim.
3190 Any other number of arguments is replaced by the current date,
3191 but without any arguments the string
3196 does not print a dash for an empty argument.
3200 does not start a new line unless invoked as the line macro in the
3208 children causes inconsistent spacing between arguments.
3209 In mandoc, a single space is always inserted between arguments.
3214 causes inconsistent vertical spacing, depending on whether a prior
3221 for the normalised behaviour in mandoc.
3224 ignores additional arguments and is not treated specially in the
3229 sometimes requires a
3233 In new groff and mandoc, any list may be nested by default and
3235 lists will restart the sequence only for the sub-list.
3238 followed by a delimiter is incorrectly used in some manuals
3239 instead of properly quoting that character, which sometimes works with
3243 only accepts a single link-name argument; the remainder is misformatted.
3246 does not format its arguments when used in the FILES section under
3250 can only be called by other macros, but not at the beginning of a line.
3253 is not implemented (up to and including groff-1.22.2).
3255 Historic groff only allows up to eight or nine arguments per macro input
3256 line, depending on the exact situation.
3257 Providing more arguments causes garbled output.
3258 The number of arguments on one input line is not limited with mandoc.
3260 Historic groff has many un-callable macros.
3261 Most of these (excluding some block-level macros) are callable
3262 in new groff and mandoc.
3265 (vertical bar) is not fully supported as a delimiter.
3272 .Pq font family face
3274 escapes behave irregularly when specified within line-macro scopes.
3276 Negative scaling units return to prior lines.
3277 Instead, mandoc truncates them to zero.
3280 The following features are unimplemented in mandoc:
3288 .Fl offset Cm center
3290 .Fl offset Cm right .
3291 Groff does not implement centred and flush-right rendering either,
3292 but produces large indentations.
3305 language first appeared as a troff macro package in
3307 It was later significantly updated by Werner Lemberg and Ruslan Ermilov
3309 The standalone implementation that is part of the
3311 utility written by Kristaps Dzonsons appeared in
3316 reference was written by
3317 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .