1 .\" $Id: mdoc.7,v 1.257 2015/11/05 12:06:45 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.
19 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
20 .\" Copyright 2015 Nexenta Systems, Inc. All rights reserved.
22 .Dd $Mdocdate: November 5 2015 $
27 .Nd semantic markup language for formatting manual pages
31 language supports authoring of manual pages for the
33 utility by allowing semantic annotations of words, phrases,
34 page sections and complete manual pages.
35 Such annotations are used by formatting tools to achieve a uniform
36 presentation across all manuals written in
38 and to support hyperlinking if supported by the output medium.
40 This reference document describes the structure of manual pages
41 and the syntax and usage of the
44 The reference implementation of a parsing and formatting tool is
48 section describes compatibility with other implementations.
52 document, lines beginning with the control character
56 The first word is the macro name.
57 It consists of two or three letters.
58 Most macro names begin with a capital letter.
59 For a list of available macros, see
61 The words following the macro name are arguments to the macro, optionally
62 including the names of other, callable macros; see
66 Lines not beginning with the control character are called
68 They provide free-form text to be printed; the formatting of the text
69 depends on the respective processing context:
70 .Bd -literal -offset indent
71 \&.Sh Macro lines change control state.
72 Text lines are interpreted within the current state.
75 Many aspects of the basic syntax of the
77 language are based on the
85 manual for details, in particular regarding
86 comments, escape sequences, whitespace, and quoting.
91 documents is discouraged;
93 supports some of them merely for backward compatibility.
97 document consists of a document prologue followed by one or more
100 The prologue, which consists of the
105 macros in that order, is required for every document.
107 The first section (sections are denoted by
109 must be the NAME section, consisting of at least one
114 Following that, convention dictates specifying at least the
118 sections, although this varies between manual sections.
120 The following is a well-formed skeleton
124 .Bd -literal -offset indent
126 \&.Dt PROGNAME section
130 \&.Nd one line about what it does
131 \&.\e\(dq .Sh LIBRARY
132 \&.\e\(dq For sections 2, 3, and 9 only.
140 utility processes files ...
141 \&.\e\(dq .Sh IMPLEMENTATION NOTES
142 \&.\e\(dq .Sh RETURN VALUES
143 \&.\e\(dq For sections 2, 3, and 9 only.
144 \&.\e\(dq .Sh CONTEXT
145 \&.\e\(dq For section 9 functions only.
146 \&.\e\(dq .Sh ENVIRONMENT
147 \&.\e\(dq For sections 1, 1M, and 5.
149 \&.\e\(dq .Sh EXIT STATUS
150 \&.\e\(dq For sections 1, 1M, and 5.
151 \&.\e\(dq .Sh EXAMPLES
152 \&.\e\(dq .Sh DIAGNOSTICS
154 \&.\e\(dq For sections 2, 3, and 9 only.
155 \&.\e\(dq .Sh ARCHITECTURE
156 \&.\e\(dq .Sh CODE SET INDEPENDENCE
157 \&.\e\(dq For sections 1, 1M, and 3 only.
158 \&.\e\(dq .Sh INTERFACE STABILITY
159 \&.\e\(dq .Sh MT-LEVEL
160 \&.\e\(dq For sections 2 and 3 only.
161 \&.\e\(dq .Sh SECURITY
162 \&.\e\(dq .Sh SEE ALSO
163 \&.\e\(dq .Xr foobar 1
164 \&.\e\(dq .Sh STANDARDS
165 \&.\e\(dq .Sh HISTORY
166 \&.\e\(dq .Sh AUTHORS
167 \&.\e\(dq .Sh CAVEATS
173 document are conventionally ordered as they appear above.
174 Sections should be composed as follows:
175 .Bl -ohang -offset Ds
177 The name(s) and a one line description of the documented material.
178 The syntax for this as follows:
179 .Bd -literal -offset indent
183 \&.Nd a one line description
188 names should be separated by commas.
192 macro(s) must precede the
201 The name of the library containing the documented material, which is
202 assumed to be a function in a section 2, 3, or 9 manual.
203 The syntax for this is as follows:
204 .Bd -literal -offset indent
211 Documents the utility invocation syntax, function call syntax, or device
214 For the first, utilities (sections 1 and 1M), this is
215 generally structured as follows:
216 .Bd -literal -offset indent
227 Commands should be ordered alphabetically.
229 For the second, function calls (sections 2, 3, 7I, 7P, 9):
230 .Bd -literal -offset indent
232 \&.Vt extern const char *global;
234 \&.Fn foo "const char *src"
236 \&.Fn bar "const char *src"
245 macros should follow C header-file conventions.
247 And for the third, configurations (section 7D):
248 .Bd -literal -offset indent
249 \&.Pa /dev/device_node
252 Manuals not in these sections generally don't need a
255 Some macros are displayed differently in the
257 section, particularly
267 All of these macros are output on their own line.
268 If two such dissimilar macros are pairwise invoked (except for
274 they are separated by a vertical space, unless in the case of
279 which are always separated by vertical space.
281 When text and macros following an
283 macro starting an input line span multiple output lines,
284 all output lines but the first will be indented to align
285 with the text immediately following the
287 macro, up to the next
292 macro or the end of an enclosing block, whichever comes first.
294 This begins with an expansion of the brief, one line description in
296 .Bd -literal -offset indent
299 utility does this, that, and the other.
302 It usually follows with a breakdown of the options (if documenting a
304 .Bd -literal -offset indent
305 The arguments are as follows:
306 \&.Bl \-tag \-width Ds
308 Print verbose information.
312 List the options in alphabetical order,
313 uppercase before lowercase for each letter and
314 with no regard to whether an option takes an argument.
315 Put digits in ascending order before all letter options.
317 Manuals not documenting a command won't include the above fragment.
321 section usually contains most of the text of a manual, longer manuals
324 macro to form subsections.
325 In very long manuals, the
327 may be split into multiple sections, each started by an
329 macro followed by a non-standard section name, and each having
330 several subsections, like in the present
333 .It Em IMPLEMENTATION NOTES
334 Implementation-specific notes should be kept here.
335 This is useful when implementing standard functions that may have side
336 effects or notable algorithmic implications.
338 This section documents the
339 return values of functions in sections 2, 3, and 9.
344 This section lists the contexts in which functions can be called in section 9.
345 The contexts are user, kernel, or interrupt.
347 Lists the environment variables used by the utility,
348 and explains the syntax and semantics of their values.
351 manual provides examples of typical content and formatting.
356 Documents files used.
357 It's helpful to document both the file name and a short description of how
358 the file is used (created, modified, etc.).
363 This section documents the
364 command exit status for sections 1 and 1M.
365 Historically, this information was described in
367 a practise that is now discouraged.
373 This often contains snippets of well-formed, well-tested invocations.
374 Make sure that examples work properly!
376 Documents error and diagnostic messages displayed to the user or
377 sent to logs. Note that exit
378 status and return values should be documented in the
388 Documents error handling in sections 2, 3, and 9.
393 This section is usually absent, but will be present when the
394 interface is specific to one or more architectures.
395 .It Em CODE SET INDEPENDENCE
396 Indicates whether the interface operates correctly with various different
397 code sets. True independent code sets will support not only ASCII and
398 Extended UNIX Codesets (EUC), but also other multi-byte encodings such as
401 Generally there will be some limitations that are fairly standard. See
402 .Xr standards 5 for more information about some of these. Most interfaces
403 should support at least UTF-8 in addition to ASCII.
404 .It Em INTERFACE STABILITY
405 Indicates the level of commitment to the interface. Interfaces can be described
406 with in the following ways:
409 Indicates that the interface is defined by one or more standards bodies.
410 Generally, changes to the interface will be carefully managed to conform
411 to the relevant standards. These interfaces are generally the most suitable
412 for use in portable programs.
414 Indicates that the interface is intended to be preserved for the long-haul, and
415 will rarely, if ever change, and never without notification (barring
416 extraordinary and extenuating circumstances). These interfaces are
417 preferred over other interfaces with the exeception of
421 Indicates that the interface may change. Generally, changes to these interfaces
422 should be infrequent, and some effort will be made to address compatibility
423 considerations when changing or removing such interfaces. However, there is
424 no firm commitment to the preservation of the interface. Most often this
425 is applied to interfaces where operational experience with the interface
426 is still limited and some need to change may be anticipated.
428 Consumers should expect to revalidate any
430 interfaces when crossing release boundaries. Products intended for
431 use on many releases or intended to support compatibility with future
432 releases should avoid these interfaces.
434 The interface can change at any time for any reason. Often this relates to
435 interfaces that are part of external software components that are still evolving
436 rapidly. Consumers should not expect that the interface (either binary or
437 source level) will be unchanged from one release to the next.
438 .It Nm Not-an-Interface
439 Describes something that is specifically not intended for programmatic
440 consumption. For example, specific human-readable output, or the layout
441 of graphical items on a user interface, may be described this way. Generally
442 programmatic alternatives to these will be available, and should be used
443 when programmatic consumption is needed.
445 This is an internal interface. Generally these interfaces should only be
446 used within the project, and should not be used by other programs or modules.
447 The interface can and will change without notice as the project needs, at
450 Most often, Private interfaces will lack any documentation whatsoever, and
451 generally any undocumented interface can be assumed to be Private.
453 The interface is not intended for use in new projects or programs, and may
454 be removed at a future date. The
456 word is a modifier that can
457 be applied to other commitment levels. For example an
458 .Nm Obsolete Committed
459 interface is unlikely to be removed or changed, but nonetheless new use
460 is discouraged (perhaps a better newer alternative is present).
463 This section describes considerations for the interface when used within
464 programs that use multiple threads. More discussion of these considerations
465 is made in the MT-Level section of
467 The interface can be described in the following ways.
470 Indicates the interface is safe for use within multiple threads. There
471 may be additional caveats that apply, in which case those will be
472 described. Note that some interfaces have semantics which may affect
473 other threads, but these should be an intrinsic part of the interface
474 rather than an unexpected side effect. For example, closing a file in
475 one thread will cause that file to be closed in all threads.
477 Indicates the interface is unsuitable for concurrent use within multiple
478 threads. A threaded application may still make use of the interface, but
479 will be required to provide external synchronization means to ensure that
480 only a single thread calls the interface at a time.
482 Indicates that the interface is not only safe for concurrent use, but is
483 designed for such use. For example, a
485 interface may make use of a global lock to provide safety, but at reduced
486 internal concurrency, whereas an
488 interface will be designed to be efficient even when used concurrently.
489 .It Nm Async-Signal-Safe
490 Indicates that the library is safe for use within a signal handler. An
492 interface can be made
493 .Nm Async-Signal-Safe
494 by ensuring that it blocks signals when acquiring locks.
495 .It Nm Safe with Exceptions
498 but with specific exceptions noted.
499 .It Nm MT-Safe with Exceptions
502 but with specific exceptions noted.
505 Documents any security precautions that operators should consider.
507 References other manuals with related topics.
508 This section should exist for most manuals.
509 Cross-references should conventionally be ordered first by section, then
510 alphabetically (ignoring case).
512 References to other documentation concerning the topic of the manual page,
513 for example authoritative books or journal articles, may also be
514 provided in this section.
521 References any standards implemented or used.
522 If not adhering to any standards, the
524 section should be used instead.
529 A brief history of the subject, including where it was first implemented,
530 and when it was ported to or reimplemented for the operating system at hand.
532 Credits to the person or persons who wrote the code and/or documentation.
533 Authors should generally be noted by both name and email address.
538 Common misuses and misunderstandings should be explained
541 Known bugs, limitations, and work-arounds should be described
545 This overview is sorted such that macros of similar purpose are listed
546 together, to help find the best macro for any given purpose.
547 Deprecated macros are not included in the overview, but can be found below
549 .Sx MACRO REFERENCE .
550 .Ss Document preamble and NAME section macros
551 .Bl -column "Brq, Bro, Brc" description
552 .It Sx \&Dd Ta document date: Ar month day , year
553 .It Sx \&Dt Ta document title: Ar TITLE SECTION Op Ar arch
554 .It Sx \&Os Ta operating system version: Op Ar system Op Ar version
555 .It Sx \&Nm Ta document name (one argument)
556 .It Sx \&Nd Ta document description (one line)
558 .Ss Sections and cross references
559 .Bl -column "Brq, Bro, Brc" description
560 .It Sx \&Sh Ta section header (one line)
561 .It Sx \&Ss Ta subsection header (one line)
562 .It Sx \&Sx Ta internal cross reference to a section or subsection
563 .It Sx \&Xr Ta cross reference to another manual page: Ar name section
564 .It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments)
566 .Ss Displays and lists
567 .Bl -column "Brq, Bro, Brc" description
568 .It Sx \&Bd , \&Ed Ta display block:
570 .Op Fl offset Ar width
572 .It Sx \&D1 Ta indented display (one line)
573 .It Sx \&Dl Ta indented literal display (one line)
574 .It Sx \&Ql Ta in-line literal display: Ql text
575 .It Sx \&Bl , \&El Ta list block:
580 .It Sx \&It Ta list item (syntax depends on Fl Ar type )
581 .It Sx \&Ta Ta table cell separator in Sx \&Bl Fl column No lists
582 .It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references)
585 .Bl -column "Brq, Bro, Brc" description
586 .It Sx \&Pf Ta prefix, no following horizontal space (one argument)
587 .It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
588 .It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
589 .It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off
590 .It Sx \&Bk , \&Ek Ta keep block: Fl words
591 .It Sx \&br Ta force output line break in text mode (no arguments)
592 .It Sx \&sp Ta force vertical space: Op Ar height
594 .Ss Semantic markup for command line utilities:
595 .Bl -column "Brq, Bro, Brc" description
596 .It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility
597 .It Sx \&Fl Ta command line options (flags) (>=0 arguments)
598 .It Sx \&Cm Ta command modifier (>0 arguments)
599 .It Sx \&Ar Ta command arguments (>=0 arguments)
600 .It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure)
601 .It Sx \&Ic Ta internal or interactive command (>0 arguments)
602 .It Sx \&Ev Ta environmental variable (>0 arguments)
603 .It Sx \&Pa Ta file system path (>=0 arguments)
605 .Ss Semantic markup for function libraries:
606 .Bl -column "Brq, Bro, Brc" description
607 .It Sx \&Lb Ta function library (one argument)
608 .It Sx \&In Ta include file (one argument)
609 .It Sx \&Fd Ta other preprocessor directive (>0 arguments)
610 .It Sx \&Ft Ta function type (>0 arguments)
611 .It Sx \&Fo , \&Fc Ta function block: Ar funcname
612 .It Sx \&Fn Ta function name:
619 .It Sx \&Fa Ta function argument (>0 arguments)
620 .It Sx \&Vt Ta variable type (>0 arguments)
621 .It Sx \&Va Ta variable name (>0 arguments)
622 .It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments)
623 .It Sx \&Er Ta error constant (>0 arguments)
624 .It Sx \&Ev Ta environmental variable (>0 arguments)
626 .Ss Various semantic markup:
627 .Bl -column "Brq, Bro, Brc" description
628 .It Sx \&An Ta author name (>0 arguments)
629 .It Sx \&Lk Ta hyperlink: Ar uri Op Ar name
630 .It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address
631 .It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
632 .It Sx \&Ad Ta memory address (>0 arguments)
633 .It Sx \&Ms Ta mathematical symbol (>0 arguments)
636 .Bl -column "Brq, Bro, Brc" description
637 .It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments)
638 .It Sx \&Sy Ta boldface font (symbolic) (>0 arguments)
639 .It Sx \&Li Ta typewriter font (literal) (>0 arguments)
640 .It Sx \&No Ta return to roman font (normal) (no arguments)
641 .It Sx \&Bf , \&Ef Ta font block:
642 .Op Fl Ar type | Cm \&Em | \&Li | \&Sy
644 .Ss Physical enclosures
645 .Bl -column "Brq, Bro, Brc" description
646 .It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text
647 .It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text
648 .It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text
649 .It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text
650 .It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text
651 .It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text
652 .It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text
653 .It Sx \&Eo , \&Ec Ta generic enclosure
656 .Bl -column "Brq, Bro, Brc" description
657 .It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
658 .It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
659 .It Sx \&St Ta reference to a standards document (one argument)
669 This section is a canonical reference of all macros, arranged
671 For the scoping of individual macros, see
677 Multiple authors should each be accorded their own
680 Author names should be ordered with full or abbreviated forename(s)
681 first, then full surname.
686 This macro may also be used in a non-bibliographic context when
687 referring to book titles.
689 Publication city or location of an
693 Publication date of an
696 Recommended formats of arguments are
701 Publisher or issuer name of an
709 Issue number (usually for journals) of an
713 Optional information of an
717 Book or journal page number of an
721 Institutional author (school, government, etc.) of an
724 Multiple institutional authors should each be accorded their own
728 Technical report name of an
735 This macro may also be used in a non-bibliographical context when
736 referring to article titles.
738 URI of reference document.
747 Does not have any tail arguments.
750 Do not use this for postal addresses.
757 Can be used both for the authors of the program, function, or driver
758 documented in the manual, or for the authors of the manual itself.
759 Requires either the name of an author or one of the following arguments:
761 .Bl -tag -width "-nosplitX" -offset indent -compact
763 Start a new output line before each subsequent invocation of
772 The effect of selecting either of the
774 modes ends at the beginning of the
779 section, the default is
781 for the first author listing and
783 for all other author listings.
787 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
789 Begin a block enclosed by angle brackets.
790 Does not have any head arguments.
793 .Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
798 Inserts an apostrophe without any surrounding whitespace.
799 This is generally used as a grammatical device when referring to the verb
803 .Dl \&.Fn execve \&Ap d
805 Encloses its arguments in angle brackets.
808 .Dl \&.Fl -key= \&Ns \&Aq \&Ar val
811 this macro is often abused for rendering URIs, which should instead use
815 or to note pre-processor
817 statements, which should use
824 If an argument is not provided, the string
826 is used as a default.
831 .Dl ".Ar arg1 , arg2 ."
835 macro are names and placeholders for command arguments;
836 for fixed strings to be passed verbatim as arguments, use
844 Accepts one optional argument:
846 .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
857 Note that these arguments do not begin with a hyphen.
876 Does not have any tail arguments.
878 Begin a display block.
879 Its syntax is as follows:
880 .Bd -ragged -offset indent
883 .Op Fl offset Ar width
887 Display blocks are used to select a different indentation and
888 justification than the one used by the surrounding text.
889 They may contain both macro lines and text lines.
890 By default, a display block is preceded by a vertical space.
894 must be one of the following:
895 .Bl -tag -width 13n -offset indent
897 Produce one output line from each input line, and center-justify each line.
898 Using this display type is not recommended; many
900 implementations render it poorly.
902 Change the positions of line breaks to fill each line, and left- and
903 right-justify the resulting block.
905 Produce one output line from each input line,
906 and do not justify the block at all.
907 Preserve white space as it appears in the input.
908 Always use a constant-width font.
909 Use this for displaying source code.
911 Change the positions of line breaks to fill each line, and left-justify
916 but using the same font as for normal text, which is a variable width font
917 if supported by the output device.
922 must be provided first.
923 Additional arguments may follow:
924 .Bl -tag -width 13n -offset indent
925 .It Fl offset Ar width
926 Indent the display by the
928 which may be one of the following:
931 One of the pre-defined strings
933 the width of a standard indentation (six constant width characters);
940 which justifies to the right margin; or
942 which aligns around an imagined center axis.
944 A macro invocation, which selects a predefined width
945 associated with that macro.
946 The most popular is the imaginary macro
951 A scaling width as described in
954 An arbitrary string, which indents by the length of this string.
957 When the argument is missing,
961 Do not assert vertical space before the display.
965 .Bd -literal -offset indent
966 \&.Bd \-literal \-offset indent \-compact
976 Change the font mode for a scoped block of text.
977 Its syntax is as follows:
978 .Bd -ragged -offset indent
981 .Fl emphasis | literal | symbolic |
982 .Cm \&Em | \&Li | \&Sy
990 argument are equivalent, as are
998 Without an argument, this macro does nothing.
999 The font mode continues until broken by a new font mode in a nested
1011 For each macro, keep its output together on the same output line,
1012 until the end of the macro or the end of the input line is reached,
1013 whichever comes first.
1014 Line breaks in text lines are unaffected.
1015 The syntax is as follows:
1017 .D1 Pf \. Sx \&Bk Fl words
1021 argument is required; additional arguments are ignored.
1023 The following example will not break within each
1026 .Bd -literal -offset indent
1029 \&.Op Fl o Ar output
1033 Be careful in using over-long lines within a keep block!
1034 Doing so will clobber the right margin.
1037 Lists consist of items specified using the
1039 macro, containing a head or a body or both.
1040 The list syntax is as follows:
1041 .Bd -ragged -offset indent
1045 .Op Fl offset Ar val
1052 is mandatory and must be specified first.
1057 arguments accept macro names as described for
1060 scaling widths as described in
1062 or use the length of the given string.
1065 is a global indentation for the whole list, affecting both item heads
1067 For those list types supporting it, the
1069 argument requests an additional indentation of item bodies,
1074 argument is specified, list entries are separated by vertical space.
1076 A list must specify one of the following list types:
1077 .Bl -tag -width 12n -offset indent
1079 No item heads can be specified, but a bullet will be printed at the head
1081 Item bodies start on the same output line as the bullet
1082 and are indented according to the
1089 argument has no effect; instead, each argument specifies the width
1090 of one column, using either the scaling width syntax described in
1092 or the string length of the argument.
1093 If the first line of the body of a
1099 contexts spanning one input line each are implied until an
1101 macro line is encountered, at which point items start being interpreted as
1108 except that dashes are used in place of bullets.
1112 except that item heads are not parsed for macro invocations.
1113 Most often used in the
1115 section with error constants in the item heads.
1118 No item heads can be specified.
1121 except that cardinal numbers are used in place of bullets,
1126 except that the first lines of item bodies are not indented, but follow
1127 the item heads like in
1134 Item bodies follow items heads on the same line, using normal inter-word
1136 Bodies are not indented, and the
1138 argument is ignored.
1140 No item heads can be specified, and none are printed.
1141 Bodies are not indented, and the
1143 argument is ignored.
1145 Item bodies start on the line following item heads and are not indented.
1148 argument is ignored.
1150 Item bodies are indented according to the
1153 When an item head fits inside the indentation, the item body follows
1154 this head on the same output line.
1155 Otherwise, the body starts on the output line following the head.
1158 Lists may be nested within lists and displays.
1163 lists may not be portable.
1170 Begin a block enclosed by square brackets.
1171 Does not have any head arguments.
1174 .Bd -literal -offset indent -compact
1182 Encloses its arguments in square brackets.
1185 .Dl \&.Bq 1 , \&Dv BUFSIZ
1188 this macro is sometimes abused to emulate optional arguments for
1189 commands; the correct macros to use for this purpose are
1201 Does not have any tail arguments.
1203 Begin a block enclosed by curly braces.
1204 Does not have any head arguments.
1207 .Bd -literal -offset indent -compact
1215 Encloses its arguments in curly braces.
1218 .Dl \&.Brq 1 , ... , \&Va n
1225 version provided as an argument, or a default value if
1226 no argument is provided.
1241 Supported only for compatibility, do not use this in new manuals.
1243 .Dq is currently in beta test.
1247 version provided as an argument, or a default value if no
1248 argument is provided.
1264 Kernel configuration declaration. It is found in pages for
1269 .Dl \&.Cd device le0 at scode?
1272 this macro is commonly abused by using quoted literals to retain
1273 whitespace and align consecutive
1276 This practise is discouraged.
1279 Typically used for fixed strings passed as arguments, unless
1281 is more appropriate.
1282 Also useful when specifying configuration options or keys.
1285 .Dl ".Nm mt Fl f Ar device Cm rewind"
1286 .Dl ".Nm ps Fl o Cm pid , Ns Cm command"
1287 .Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
1288 .Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa"
1289 .Dl ".Cm LogLevel Dv DEBUG"
1291 One-line indented display.
1292 This is formatted by the default rules and is useful for simple indented
1294 It is followed by a newline.
1297 .Dl \&.D1 \&Fl abcdefgh
1304 This macro is obsolete.
1305 No replacement is needed.
1308 and groff including its arguments.
1309 It was formerly used to toggle a debugging mode.
1314 Does not have any tail arguments.
1316 Document date for display in the page footer.
1317 This is the mandatory first macro of any
1320 Its syntax is as follows:
1322 .D1 Pf \. Sx \&Dd Ar month day , year
1326 is the full English month name, the
1328 is an optionally zero-padded numeral, and the
1330 is the full four-digit year.
1332 Other arguments are not portable; the
1334 utility handles them as follows:
1335 .Bl -dash -offset 3n -compact
1337 To have the date automatically filled in by the
1343 can be given as an argument.
1345 The traditional, purely numeric
1348 .Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day
1351 If a date string cannot be parsed, it is used verbatim.
1353 If no date string is given, the current date is used.
1357 .Dl \&.Dd $\&Mdocdate$
1358 .Dl \&.Dd $\&Mdocdate: July 21 2007$
1359 .Dl \&.Dd July 21, 2007
1366 One-line indented display.
1367 This is formatted as literal text and is useful for commands and
1369 It is followed by a newline.
1372 .Dl \&.Dl % mandoc mdoc.5 \e(ba less
1381 Begin a block enclosed by double quotes.
1382 Does not have any head arguments.
1385 .Bd -literal -offset indent -compact
1387 April is the cruellest month
1395 Encloses its arguments in
1400 .Bd -literal -offset indent -compact
1401 \&.Dq April is the cruellest month
1411 Document title for display in the page header.
1412 This is the mandatory second macro of any
1415 Its syntax is as follows:
1416 .Bd -ragged -offset indent
1423 Its arguments are as follows:
1424 .Bl -tag -width section -offset 2n
1426 The document's title (name), defaulting to
1429 To achieve a uniform appearance of page header lines,
1430 it should by convention be all caps.
1433 It should correspond to the manual's filename suffix and defaults to
1434 the empty string if unspecified.
1435 This field is optional.
1436 To achieve a uniform appearance of page header lines,
1437 it should by convention be all caps.
1439 This specifies the machine architecture a manual page applies to,
1443 Defined variables such as preprocessor constants, constant symbols,
1444 enumeration values, and so on.
1449 .Dl \&.Dv STDOUT_FILENO
1455 for special-purpose constants,
1457 for variable symbols, and
1459 for listing preprocessor variable definitions in the
1464 version provided as an argument, or a default
1465 value if no argument is provided.
1480 Close a scope started by
1482 Its syntax is as follows:
1484 .D1 Pf \. Sx \&Ec Op Ar TERM
1488 argument is used as the enclosure tail, for example, specifying \e(rq
1492 End a display context started by
1495 End a font mode context started by
1498 End a keep context started by
1501 End a list context started by
1509 Request an italic font.
1510 If the output device does not provide that, underline.
1512 This is most often used for stress emphasis (not to be confused with
1515 In the rare cases where none of the semantic markup macros fit,
1516 it can also be used for technical terms and placeholders, except
1517 that for syntax elements,
1521 are preferred, respectively.
1524 .Bd -literal -compact -offset indent
1525 Selected lines are those
1527 matching any of the specified patterns.
1528 Some of the functions use a
1530 to save the pattern space for subsequent retrieval.
1540 This macro is obsolete.
1543 or any of the other enclosure macros.
1545 It encloses its argument in the delimiters specified by the last
1549 An arbitrary enclosure.
1550 Its syntax is as follows:
1552 .D1 Pf \. Sx \&Eo Op Ar TERM
1556 argument is used as the enclosure head, for example, specifying \e(lq
1560 Error constants for definitions of the
1562 libc global variable.
1563 This is most often used in section 2 and 3 manual pages.
1571 for general constants.
1573 This macro is obsolete.
1576 or any of the other enclosure macros.
1578 It takes two arguments, defining the delimiters to be used by subsequent
1582 Environmental variables such as those specified in
1591 for general constants.
1593 Insert a standard sentence regarding command exit values of 0 on success
1595 This is most often used in section 1 and 1M manual pages.
1596 Its syntax is as follows:
1598 .D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
1602 is not specified, the document's name set by
1607 arguments are treated as separate utilities.
1612 Function argument or parameter.
1613 Its syntax is as follows:
1614 .Bd -ragged -offset indent
1622 Each argument may be a name and a type (recommended for the
1624 section), a name alone (for function invocations),
1625 or a type alone (for function prototypes).
1626 If both a type and a name are given or if the type consists of multiple
1627 words, all words belonging to the same function argument have to be
1628 given in a single argument to the
1632 This macro is also used to specify the field name of a structure.
1636 macro is used in the
1640 blocks when documenting multi-line function prototypes.
1641 If invoked with multiple arguments, the arguments are separated by a
1643 Furthermore, if the following macro is another
1645 the last argument will also have a trailing comma.
1648 .Dl \&.Fa \(dqconst char *p\(dq
1649 .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
1650 .Dl \&.Fa \(dqchar *\(dq size_t
1655 End a function context started by
1658 Preprocessor directive, in particular for listing it in the
1660 Historically, it was also used to document include files.
1661 The latter usage has been deprecated in favour of
1664 Its syntax is as follows:
1665 .Bd -ragged -offset indent
1667 .Li # Ns Ar directive
1672 .Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler
1673 .Dl \&.Fd #define SIO_MAXNFDS
1674 .Dl \&.Fd #ifdef FS_DEBUG
1676 .Dl \&.Fn dbg_open \(dqconst char *\(dq
1680 .Sx MANUAL STRUCTURE ,
1685 Command-line flag or option.
1686 Used when listing arguments to command-line utilities.
1687 Prints a fixed-width hyphen
1689 directly followed by each argument.
1690 If no arguments are provided, a hyphen is printed followed by a space.
1691 If the argument is a macro, a hyphen is prefixed to the subsequent macro
1695 .Dl ".Fl R Op Fl H | L | P"
1696 .Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
1697 .Dl ".Fl type Cm d Fl name Pa CVS"
1698 .Dl ".Fl Ar signal_number"
1705 Its syntax is as follows:
1706 .Bd -ragged -offset indent
1710 .Op Oo Ar argtype Oc Ar argname
1713 Function arguments are surrounded in parenthesis and
1714 are delimited by commas.
1715 If no arguments are specified, blank parenthesis are output.
1718 section, this macro starts a new output line,
1719 and a blank line is automatically inserted between function definitions.
1722 .Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
1723 .Dl \&.Fn funcname \(dqint arg0\(dq
1724 .Dl \&.Fn funcname arg0
1726 .Bd -literal -offset indent -compact
1731 When referring to a function documented in another manual page, use
1735 .Sx MANUAL STRUCTURE ,
1740 Begin a function block.
1741 This is a multi-line version of
1743 Its syntax is as follows:
1745 .D1 Pf \. Sx \&Fo Ar funcname
1747 Invocations usually occur in the following context:
1748 .Bd -ragged -offset indent
1749 .Pf \. Sx \&Ft Ar functype
1751 .Pf \. Sx \&Fo Ar funcname
1753 .Pf \. Sx \&Fa Qq Ar argtype Ar argname
1766 .Sx MANUAL STRUCTURE ,
1772 This macro is obsolete.
1773 No replacement markup is needed.
1775 It was used to show numerical function return values in an italic font.
1778 Its syntax is as follows:
1780 .D1 Pf \. Sx \&Ft Ar functype
1784 section, a new output line is started after this macro.
1788 .Bd -literal -offset indent -compact
1794 .Sx MANUAL STRUCTURE ,
1801 version provided as an argument, or a default value
1802 if no argument is provided.
1817 This macro is not implemented in
1820 It was used to include the contents of a (header) file literally.
1823 .Dl Pf . Sx \&Hf Ar filename
1825 Designate an internal or interactive command.
1828 but used for instructions rather than values.
1839 is preferred for displaying code; the
1841 macro is used when referring to specific instructions.
1843 The name of an include file.
1844 This macro is most often used in section 2, 3, and 9 manual pages.
1846 When invoked as the first macro on an input line in the
1848 section, the argument is displayed in angle brackets
1851 and a blank line is inserted in front if there is a preceding
1852 function declaration.
1853 In other sections, it only encloses its argument in angle brackets
1854 and causes no line break.
1857 .Dl \&.In sys/types.h
1860 .Sx MANUAL STRUCTURE .
1863 The syntax of this macro depends on the list type.
1872 have the following syntax:
1874 .D1 Pf \. Sx \&It Ar args
1883 have the following syntax:
1887 with subsequent lines interpreted within the scope of the
1889 until either a closing
1896 list has the following syntax:
1898 .D1 Pf \. Sx \&It Op Cm args
1900 Subsequent lines are interpreted as with
1903 The line arguments correspond to the list's left-hand side; body
1904 arguments correspond to the list's contents.
1908 list is the most complicated.
1909 Its syntax is as follows:
1911 .D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
1912 .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
1914 The arguments consist of one or more lines of text and macros
1915 representing a complete table line.
1916 Cells within the line are delimited by tabs or by the special
1919 The tab cell delimiter may only be used within the
1921 line itself; on following lines, only the
1923 macro can be used to delimit cells, and
1925 is only recognised as a macro when called by other macros,
1926 not as the first macro on a line.
1928 Note that quoted strings may span tab-delimited cells on an
1933 .Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
1935 will preserve the semicolon whitespace except for the last.
1941 The syntax is as follows:
1943 .D1 Pf \. Sx \&Lb Ar library
1947 parameter may be a system library, such as
1951 in which case a small library description is printed next to the linker
1952 invocation; or a custom library, in which case the library name is
1954 This is most commonly used in the
1956 section as described in
1957 .Sx MANUAL STRUCTURE .
1963 Denotes text that should be in a
1966 Note that this is a presentation term and should not be used for
1967 stylistically decorating technical terms.
1969 On terminal output devices, this is often indistinguishable from
1980 Its syntax is as follows:
1982 .D1 Pf \. Sx \&Lk Ar uri Op Ar name
1985 .Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
1986 .Dl \&.Lk http://bsd.lv
1994 Display a mathematical symbol.
1995 Its syntax is as follows:
1997 .D1 Pf \. Sx \&Ms Ar symbol
2006 Its syntax is as follows:
2008 .D1 Pf \. Sx \&Mt Ar address
2011 .Dl \&.Mt discuss@manpages.bsd.lv
2012 .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
2014 A one line description of the manual's content.
2015 This is the mandatory last macro of the
2017 section and not appropriate for other sections.
2020 .Dl Pf . Sx \&Nd mdoc language reference
2021 .Dl Pf . Sx \&Nd format and display UNIX manuals
2025 macro technically accepts child macros and terminates with a subsequent
2028 Do not assume this behaviour: some
2030 database generators are not smart enough to parse more than the line
2031 arguments and will display macros verbatim.
2036 The name of the manual page, or \(em in particular in section 1
2037 pages \(em of an additional command or feature documented in
2039 When first invoked, the
2041 macro expects a single argument, the name of the manual page.
2042 Usually, the first invocation happens in the
2044 section of the page.
2045 The specified name will be remembered and used whenever the macro is
2046 called again without arguments later in the page.
2050 .Sx Block full-implicit
2051 semantics when invoked as the first macro on an input line in the
2053 section; otherwise, it uses ordinary
2058 .Bd -literal -offset indent
2067 of section 2, 3 and 9 manual pages, use the
2071 to mark up the name of the manual page.
2074 Closes the scope of any preceding in-line macro.
2075 When used after physical formatting macros like
2079 switches back to the standard font face and weight.
2080 Can also be used to embed plain text strings in macro lines
2081 using semantic annotation macros.
2084 .Dl ".Em italic , Sy bold , No and roman"
2086 .Bd -literal -offset indent -compact
2088 \&.Cm :C No / Ar pattern No / Ar replacement No /
2098 Suppress a space between the output of the preceding macro
2099 and the following text or macro.
2100 Following invocation, input is interpreted as normal text
2105 This has no effect when invoked at the start of a macro line.
2108 .Dl ".Ar name Ns = Ns Ar value"
2109 .Dl ".Cm :M Ns Ar pattern"
2110 .Dl ".Fl o Ns Ar output"
2119 version provided as an argument, or a default value if
2120 no argument is provided.
2139 Multi-line version of
2143 .Bd -literal -offset indent -compact
2145 \&.Op Fl flag Ns Ar value
2149 Optional part of a command line.
2150 Prints the argument(s) in brackets.
2151 This is most often used in the
2153 section of section 1 and 1M manual pages.
2156 .Dl \&.Op \&Fl a \&Ar b
2157 .Dl \&.Op \&Ar a | b
2162 Operating system version for display in the page footer.
2163 This is the mandatory third macro of
2167 Its syntax is as follows:
2169 .D1 Pf \. Sx \&Os Op Ar system Op Ar version
2173 parameter specifies the relevant operating system or environment.
2174 It is suggested to leave it unspecified, in which case
2178 argument or, if that isn't specified either,
2187 .Dl \&.Os KTH/CSC/TCS
2195 This macro is obsolete.
2200 both have the same effect.
2204 packages described it as
2205 .Dq "old function type (FORTRAN)" .
2209 version provided as an argument, or a default value
2210 if no argument is provided.
2225 An absolute or relative file system path, or a file or directory name.
2226 If an argument is not provided, the character
2228 is used as a default.
2231 .Dl \&.Pa /usr/bin/mandoc
2232 .Dl \&.Pa /usr/share/man/man5/mdoc.5
2237 Close parenthesised context opened by
2240 Removes the space between its argument and the following macro.
2241 Its syntax is as follows:
2243 .D1 .Pf Ar prefix macro arguments ...
2245 This is equivalent to:
2247 .D1 .No \e& Ns Ar prefix No \&Ns Ar macro arguments ...
2251 argument is not parsed for macro names or delimiters,
2252 but used verbatim as if it were escaped.
2255 .Dl ".Pf $ Ar variable_name"
2256 .Dl ".Pf . Ar macro_name"
2257 .Dl ".Pf 0x Ar hex_digits"
2264 Multi-line version of
2268 This will assert vertical space between prior and subsequent macros
2271 Paragraph breaks are not needed before or after
2275 macros or before displays
2283 Parenthesised enclosure.
2288 Close quoted context opened by
2291 In-line literal display.
2292 This can for example be used for complete command invocations and
2293 for multi-word code fragments when more specific markup is not
2294 appropriate and an indented display is not desired.
2297 always encloses the arguments in single quotes, other formatters
2298 usually omit the quotes on non-terminal output devices when the
2299 arguments have three or more characters.
2307 Multi-line version of
2310 Encloses its arguments in
2325 Does not have any tail arguments.
2327 Begin a bibliographic
2330 Does not have any head arguments.
2331 The block macro may only contain
2347 child macros (at least one must be specified).
2350 .Bd -literal -offset indent -compact
2352 \&.%A J. E. Hopcroft
2354 \&.%B Introduction to Automata Theory, Languages, and Computation
2355 \&.%I Addison-Wesley
2356 \&.%C Reading, Massachusetts
2363 block is used within a SEE ALSO section, a vertical space is asserted
2364 before the rendered output, else the block continues on the current
2367 Insert a standard sentence regarding a function call's return value of 0
2368 on success and \-1 on error, with the
2370 libc global variable set on error.
2371 Its syntax is as follows:
2373 .D1 Pf \. Sx \&Rv Fl std Op Ar function ...
2377 is not specified, the document's name set by
2382 arguments are treated as separate functions.
2387 Close single-quoted context opened by
2390 Begin a new section.
2391 For a list of conventional manual sections, see
2392 .Sx MANUAL STRUCTURE .
2393 These sections should be used unless it's absolutely necessary that
2394 custom sections be used.
2396 Section names should be unique so that they may be keyed by
2398 Although this macro is parsed, it should not consist of child node or it
2399 may not be linked with
2408 Switches the spacing mode for output generated from macros.
2409 Its syntax is as follows:
2411 .D1 Pf \. Sx \&Sm Op Cm on | off
2413 By default, spacing is
2417 no white space is inserted between macro arguments and between the
2418 output generated from adjacent macros, but text lines
2419 still get normal spacing between words and sentences.
2421 When called without an argument, the
2423 macro toggles the spacing mode.
2424 Using this is not recommended because it makes the code harder to read.
2426 Multi-line version of
2429 Encloses its arguments in
2439 Begin a new subsection.
2442 there is no convention for the naming of subsections.
2445 the conventional sections described in
2446 .Sx MANUAL STRUCTURE
2447 rarely have subsections.
2449 Sub-section names should be unique so that they may be keyed by
2451 Although this macro is parsed, it should not consist of child node or it
2452 may not be linked with
2461 Replace an abbreviation for a standard with the full form.
2462 The following standards are recognised.
2463 Where multiple lines are given without a blank line in between,
2464 they all refer to the same standard, and using the first form
2467 .It C language standards
2469 .Bl -tag -width "-p1003.1g-2000" -compact
2479 The original C standard.
2493 The second major version of the C language standard.
2498 The third major version of the C language standard.
2500 .It POSIX.1 before the Single UNIX Specification
2502 .Bl -tag -width "-p1003.1g-2000" -compact
2508 The original POSIX standard, based on ANSI C.
2515 The first update of POSIX.1.
2522 Real-time extensions.
2527 POSIX thread interfaces.
2532 Technical Corrigendum.
2539 Includes POSIX.1-1990, 1b, 1c, and 1i.
2541 .It X/Open Portability Guide version 4 and related standards
2543 .Bl -tag -width "-p1003.1g-2000" -compact
2547 An XPG4 precursor, published in 1989.
2566 Based on POSIX.1 and POSIX.2, published in 1992.
2568 .It Single UNIX Specification version 1 and related standards
2570 .Bl -tag -width "-p1003.1g-2000" -compact
2576 This standard was published in 1994.
2577 It was used as the basis for UNIX 95 certification.
2578 The following three refer to parts of it.
2589 Networking APIs, including sockets.
2596 .It Single UNIX Specification version 2 and related standards
2598 .Bl -tag -width "-p1003.1g-2000" -compact
2601 This Standard was published in 1997
2602 and is also called X/Open Portability Guide version 5.
2603 It was used as the basis for UNIX 98 certification.
2604 The following refer to parts of it.
2620 .It Single UNIX Specification version 3
2622 .Bl -tag -width "-p1003.1-2001" -compact
2628 This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j.
2629 It is also called X/Open Portability Guide version 6.
2630 It is used as the basis for UNIX 03 certification.
2635 The second and last Technical Corrigendum.
2637 .It Single UNIX Specification version 4
2639 .Bl -tag -width "-p1003.1g-2000" -compact
2645 This standard is also called
2646 X/Open Portability Guide version 7.
2651 This is the first Technical Corrigendum.
2655 .Bl -tag -width "-p1003.1g-2000" -compact
2659 Floating-point arithmetic.
2664 Representation of dates and times, published in 1988.
2669 Ethernet local area networks.
2676 Reference a section or subsection in the same manual page.
2677 The referenced section or subsection name must be identical to the
2678 enclosed argument, including whitespace.
2681 .Dl \&.Sx MANUAL STRUCTURE
2688 Request a boldface font.
2690 This is most often used to indicate importance or seriousness (not to be
2691 confused with stress emphasis, see
2693 When none of the semantic macros fit, it is also adequate for syntax
2694 elements that have to be given or that appear verbatim.
2697 .Bd -literal -compact -offset indent
2701 appears in the owner permissions, set-user-ID mode is set.
2702 This utility replaces the former
2714 Table cell separator in
2716 lists; can only be used below
2719 Supported only for compatibility, do not use this in new manuals.
2720 Even though the macro name
2722 suggests a semantic function, historic usage is inconsistent, mostly
2723 using it as a presentation-level macro to request a small caps font.
2725 Supported only for compatibility, do not use this in new manuals.
2727 .Dq currently under development.
2729 Supported only for compatibility, do not use this in new manuals.
2737 .Dl \&.Va const char *bar ;
2739 For function arguments and parameters, use
2742 For declarations of global variables in the
2749 This is also used for indicating global variables in the
2751 section, in which case a variable name is also specified.
2752 Note that it accepts
2753 .Sx Block partial-implicit
2754 syntax when invoked as the first macro on an input line in the
2756 section, else it accepts ordinary
2759 In the former case, this macro starts a new output line,
2760 and a blank line is inserted in front if there is a preceding
2761 function definition or include directive.
2764 .Dl \&.Vt unsigned char
2765 .Dl \&.Vt extern const char * const sys_signame[] \&;
2767 For parameters in function prototypes, use
2769 instead, for function return types
2771 and for variable names outside the
2775 even when including a type with the name.
2777 .Sx MANUAL STRUCTURE .
2779 Close a scope opened by
2782 Extend the header of an
2784 macro or the body of a partial-implicit block macro
2785 beyond the end of the input line.
2786 This macro originally existed to work around the 9-argument limit
2790 Link to another manual
2791 .Pq Qq cross-reference .
2792 Its syntax is as follows:
2794 .D1 Pf \. Sx \&Xr Ar name Op section
2800 number of another man page;
2801 omitting the section number is rarely useful.
2805 .Dl \&.Xr mandoc 1 \&;
2806 .Dl \&.Xr mandoc 1 \&Ns s behaviour
2809 This macro should not be used; it is implemented for compatibility with
2814 in the event of natural paragraph breaks.
2816 Emits vertical space.
2817 This macro should not be used; it is implemented for compatibility with
2819 Its syntax is as follows:
2821 .D1 Pf \. Sx \&sp Op Ar height
2825 argument is a scaling width as described in
2829 asserts a single vertical space.
2831 The syntax of a macro depends on its classification.
2834 refers to macro arguments, which may be followed by zero or more
2838 opens the scope of a macro; and if specified,
2844 column indicates that the macro may also be called by passing its name
2845 as an argument to another macro.
2847 .Sq \&.Op \&Fl O \&Ar file
2849 .Sq Op Fl O Ar file .
2850 To prevent a macro call and render the macro name literally,
2851 escape it by prepending a zero-width space,
2857 If a macro is not callable but its name appears as an argument
2858 to another macro, it is interpreted as opaque text.
2866 column indicates whether the macro may call other macros by receiving
2867 their names as arguments.
2868 If a macro is not parsed but the name of another macro appears
2869 as an argument, it is interpreted as opaque text.
2873 column, if applicable, describes closure rules.
2874 .Ss Block full-explicit
2875 Multi-line scope closed by an explicit closing macro.
2876 All macros contains bodies; only
2882 .Bd -literal -offset indent
2883 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2887 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
2888 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2889 .It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
2890 .It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
2891 .It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
2892 .It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
2893 .It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
2894 .It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
2895 .It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
2896 .It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
2898 .Ss Block full-implicit
2899 Multi-line scope closed by end-of-file or implicitly by another macro.
2900 All macros have bodies; some
2902 .Sx \&It Fl bullet ,
2908 don't have heads; only one
2915 .Bd -literal -offset indent
2916 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
2919 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
2920 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2921 .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
2922 .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
2923 .It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
2924 .It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh
2925 .It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss
2931 .Sx Block full-implicit
2932 macro only when invoked as the first macro
2935 section line, else it is
2937 .Ss Block partial-explicit
2938 Like block full-explicit, but also with single-line scope.
2939 Each has at least a body and, in limited circumstances, a head
2946 .Bd -literal -offset indent
2947 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2949 \&.Yc \(lBtail...\(rB
2951 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
2952 \(lBbody...\(rB \&Yc \(lBtail...\(rB
2954 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
2955 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2956 .It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
2957 .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
2958 .It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
2959 .It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
2960 .It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
2961 .It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
2962 .It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
2963 .It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
2964 .It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
2965 .It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
2966 .It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
2967 .It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
2968 .It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
2969 .It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
2970 .It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
2971 .It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
2972 .It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
2973 .It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
2974 .It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
2975 .It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
2976 .It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
2977 .It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
2978 .It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
2979 .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
2981 .Ss Block partial-implicit
2982 Like block full-implicit, but with single-line scope closed by the
2984 .Bd -literal -offset indent
2985 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
2987 .Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
2988 .It Em Macro Ta Em Callable Ta Em Parsed
2989 .It Sx \&Aq Ta Yes Ta Yes
2990 .It Sx \&Bq Ta Yes Ta Yes
2991 .It Sx \&Brq Ta Yes Ta Yes
2992 .It Sx \&D1 Ta \&No Ta \&Yes
2993 .It Sx \&Dl Ta \&No Ta Yes
2994 .It Sx \&Dq Ta Yes Ta Yes
2995 .It Sx \&En Ta Yes Ta Yes
2996 .It Sx \&Op Ta Yes Ta Yes
2997 .It Sx \&Pq Ta Yes Ta Yes
2998 .It Sx \&Ql Ta Yes Ta Yes
2999 .It Sx \&Qq Ta Yes Ta Yes
3000 .It Sx \&Sq Ta Yes Ta Yes
3001 .It Sx \&Vt Ta Yes Ta Yes
3007 .Sx Block partial-implicit
3008 only when invoked as the first macro
3011 section line, else it is
3013 .Ss Special block macro
3016 macro can only be used below
3021 It delimits blocks representing table cells;
3022 these blocks have bodies, but no heads.
3023 .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
3024 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
3025 .It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It
3028 Closed by the end of the line, fixed argument lengths,
3029 and/or subsequent macros.
3030 In-line macros have only text children.
3031 If a number (or inequality) of arguments is
3033 then the macro accepts an arbitrary number of arguments.
3034 .Bd -literal -offset indent
3035 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
3037 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
3039 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
3041 .Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
3042 .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
3043 .It Sx \&%A Ta \&No Ta \&No Ta >0
3044 .It Sx \&%B Ta \&No Ta \&No Ta >0
3045 .It Sx \&%C Ta \&No Ta \&No Ta >0
3046 .It Sx \&%D Ta \&No Ta \&No Ta >0
3047 .It Sx \&%I Ta \&No Ta \&No Ta >0
3048 .It Sx \&%J Ta \&No Ta \&No Ta >0
3049 .It Sx \&%N Ta \&No Ta \&No Ta >0
3050 .It Sx \&%O Ta \&No Ta \&No Ta >0
3051 .It Sx \&%P Ta \&No Ta \&No Ta >0
3052 .It Sx \&%Q Ta \&No Ta \&No Ta >0
3053 .It Sx \&%R Ta \&No Ta \&No Ta >0
3054 .It Sx \&%T Ta \&No Ta \&No Ta >0
3055 .It Sx \&%U Ta \&No Ta \&No Ta >0
3056 .It Sx \&%V Ta \&No Ta \&No Ta >0
3057 .It Sx \&Ad Ta Yes Ta Yes Ta >0
3058 .It Sx \&An Ta Yes Ta Yes Ta >0
3059 .It Sx \&Ap Ta Yes Ta Yes Ta 0
3060 .It Sx \&Ar Ta Yes Ta Yes Ta n
3061 .It Sx \&At Ta Yes Ta Yes Ta 1
3062 .It Sx \&Bsx Ta Yes Ta Yes Ta n
3063 .It Sx \&Bt Ta \&No Ta \&No Ta 0
3064 .It Sx \&Bx Ta Yes Ta Yes Ta n
3065 .It Sx \&Cd Ta Yes Ta Yes Ta >0
3066 .It Sx \&Cm Ta Yes Ta Yes Ta >0
3067 .It Sx \&Db Ta \&No Ta \&No Ta 1
3068 .It Sx \&Dd Ta \&No Ta \&No Ta n
3069 .It Sx \&Dt Ta \&No Ta \&No Ta n
3070 .It Sx \&Dv Ta Yes Ta Yes Ta >0
3071 .It Sx \&Dx Ta Yes Ta Yes Ta n
3072 .It Sx \&Em Ta Yes Ta Yes Ta >0
3073 .It Sx \&Er Ta Yes Ta Yes Ta >0
3074 .It Sx \&Es Ta Yes Ta Yes Ta 2
3075 .It Sx \&Ev Ta Yes Ta Yes Ta >0
3076 .It Sx \&Ex Ta \&No Ta \&No Ta n
3077 .It Sx \&Fa Ta Yes Ta Yes Ta >0
3078 .It Sx \&Fd Ta \&No Ta \&No Ta >0
3079 .It Sx \&Fl Ta Yes Ta Yes Ta n
3080 .It Sx \&Fn Ta Yes Ta Yes Ta >0
3081 .It Sx \&Fr Ta Yes Ta Yes Ta >0
3082 .It Sx \&Ft Ta Yes Ta Yes Ta >0
3083 .It Sx \&Fx Ta Yes Ta Yes Ta n
3084 .It Sx \&Hf Ta \&No Ta \&No Ta n
3085 .It Sx \&Ic Ta Yes Ta Yes Ta >0
3086 .It Sx \&In Ta \&No Ta \&No Ta 1
3087 .It Sx \&Lb Ta \&No Ta \&No Ta 1
3088 .It Sx \&Li Ta Yes Ta Yes Ta >0
3089 .It Sx \&Lk Ta Yes Ta Yes Ta >0
3090 .It Sx \&Lp Ta \&No Ta \&No Ta 0
3091 .It Sx \&Ms Ta Yes Ta Yes Ta >0
3092 .It Sx \&Mt Ta Yes Ta Yes Ta >0
3093 .It Sx \&Nm Ta Yes Ta Yes Ta n
3094 .It Sx \&No Ta Yes Ta Yes Ta 0
3095 .It Sx \&Ns Ta Yes Ta Yes Ta 0
3096 .It Sx \&Nx Ta Yes Ta Yes Ta n
3097 .It Sx \&Os Ta \&No Ta \&No Ta n
3098 .It Sx \&Ot Ta Yes Ta Yes Ta >0
3099 .It Sx \&Ox Ta Yes Ta Yes Ta n
3100 .It Sx \&Pa Ta Yes Ta Yes Ta n
3101 .It Sx \&Pf Ta Yes Ta Yes Ta 1
3102 .It Sx \&Pp Ta \&No Ta \&No Ta 0
3103 .It Sx \&Rv Ta \&No Ta \&No Ta n
3104 .It Sx \&Sm Ta \&No Ta \&No Ta <2
3105 .It Sx \&St Ta \&No Ta Yes Ta 1
3106 .It Sx \&Sx Ta Yes Ta Yes Ta >0
3107 .It Sx \&Sy Ta Yes Ta Yes Ta >0
3108 .It Sx \&Tn Ta Yes Ta Yes Ta >0
3109 .It Sx \&Ud Ta \&No Ta \&No Ta 0
3110 .It Sx \&Ux Ta Yes Ta Yes Ta n
3111 .It Sx \&Va Ta Yes Ta Yes Ta n
3112 .It Sx \&Vt Ta Yes Ta Yes Ta >0
3113 .It Sx \&Xr Ta Yes Ta Yes Ta >0
3114 .It Sx \&br Ta \&No Ta \&No Ta 0
3115 .It Sx \&sp Ta \&No Ta \&No Ta 1
3118 When a macro argument consists of one single input character
3119 considered as a delimiter, the argument gets special handling.
3120 This does not apply when delimiters appear in arguments containing
3121 more than one character.
3122 Consequently, to prevent special handling and just handle it
3123 like any other argument, a delimiter can be escaped by prepending
3126 In text lines, delimiters never need escaping, but may be used
3127 as normal punctuation.
3129 For many macros, when the leading arguments are opening delimiters,
3130 these delimiters are put before the macro scope,
3131 and when the trailing arguments are closing delimiters,
3132 these delimiters are put after the macro scope.
3135 .D1 Pf \. \&Aq "( [ word ] ) ."
3139 .D1 Aq ( [ word ] ) .
3141 Opening delimiters are:
3143 .Bl -tag -width Ds -offset indent -compact
3150 Closing delimiters are:
3152 .Bl -tag -width Ds -offset indent -compact
3171 Note that even a period preceded by a backslash
3173 gets this special handling; use
3177 Many in-line macros interrupt their scope when they encounter
3178 delimiters, and resume their scope when more arguments follow that
3182 .D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e"
3186 .D1 Fl a ( b | c \*(Ba d ) e
3188 This applies to both opening and closing delimiters,
3189 and also to the middle delimiter:
3191 .Bl -tag -width Ds -offset indent -compact
3196 As a special case, the predefined string \e*(Ba is handled and rendered
3197 in the same way as a plain
3200 Using this predefined string is not recommended in new manuals.
3204 documents, usage of semantic markup is recommended in order to have
3205 proper fonts automatically selected; only when no fitting semantic markup
3206 is available, consider falling back to
3213 font mode, it will automatically restore the previous font when exiting
3215 Manually switching the font using the
3218 font escape sequences is never required.
3220 This section provides an incomplete list of compatibility issues
3221 between mandoc and GNU troff
3224 The following problematic behaviour is found in groff:
3229 with non-standard arguments behaves very strangely.
3230 When there are three arguments, they are printed verbatim.
3231 Any other number of arguments is replaced by the current date,
3232 but without any arguments the string
3237 only accepts a single link-name argument; the remainder is misformatted.
3240 does not format its arguments when used in the FILES section under
3244 can only be called by other macros, but not at the beginning of a line.
3247 is not implemented (up to and including groff-1.22.2).
3253 .Pq font family face
3255 escapes behave irregularly when specified within line-macro scopes.
3257 Negative scaling units return to prior lines.
3258 Instead, mandoc truncates them to zero.
3261 The following features are unimplemented in mandoc:
3267 is unsupported for security reasons.
3271 does not adjust the right margin, but is an alias for
3277 does not use a literal font, but is an alias for
3282 .Fl offset Cm center
3286 Groff does not implement centered and flush-right rendering either,
3287 but produces large indentations.
3300 language first appeared as a troff macro package in
3302 It was later significantly updated by Werner Lemberg and Ruslan Ermilov
3304 The standalone implementation that is part of the
3306 utility written by Kristaps Dzonsons appeared in
3311 reference was written by
3312 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .