1 MDOC(5) Standards, Environments, and Macros MDOC(5)
2
3 NAME
4 mdoc - semantic markup language for formatting manual pages
5
6 DESCRIPTION
7 The mdoc language supports authoring of manual pages for the man(1)
8 utility by allowing semantic annotations of words, phrases, page sections
9 and complete manual pages. Such annotations are used by formatting tools
10 to achieve a uniform presentation across all manuals written in mdoc, and
11 to support hyperlinking if supported by the output medium.
12
13 This reference document describes the structure of manual pages and the
14 syntax and usage of the mdoc language. The reference implementation of a
15 parsing and formatting tool is mandoc(1); the COMPATIBILITY section
16 describes compatibility with other implementations.
17
18 In an mdoc document, lines beginning with the control character `.' are
19 called "macro lines". The first word is the macro name. It consists of
20 two or three letters. Most macro names begin with a capital letter. For
21 a list of available macros, see MACRO OVERVIEW. The words following the
22 macro name are arguments to the macro, optionally including the names of
23 other, callable macros; see MACRO SYNTAX for details.
24
25 Lines not beginning with the control character are called "text lines".
26 They provide free-form text to be printed; the formatting of the text
27 depends on the respective processing context:
28
29 .Sh Macro lines change control state.
30 Text lines are interpreted within the current state.
31
32 Many aspects of the basic syntax of the mdoc language are based on the
33 mandoc_roff(5) language; see the LANGUAGE SYNTAX and MACRO SYNTAX
34 sections in the mandoc_roff(5) manual for details, in particular
35 regarding comments, escape sequences, whitespace, and quoting. However,
36 using mandoc_roff(5) requests in mdoc documents is discouraged; mandoc(1)
37 supports some of them merely for backward compatibility.
38
39 MANUAL STRUCTURE
40 A well-formed mdoc document consists of a document prologue followed by
41 one or more sections.
42
43 The prologue, which consists of the Dd, Dt, and Os macros in that order,
44 is required for every document.
45
46 The first section (sections are denoted by Sh) must be the NAME section,
47 consisting of at least one Nm followed by Nd.
48
49 Following that, convention dictates specifying at least the SYNOPSIS and
50 DESCRIPTION sections, although this varies between manual sections.
51
52 The following is a well-formed skeleton mdoc file for a utility
53 "progname":
54
55 .Dd Jan 1, 1970
56 .Dt PROGNAME section
57 .Os
58 .Sh NAME
59 .Nm progname
60 .Nd one line about what it does
61 .\" .Sh LIBRARY
62 .\" For sections 2, 3, and 9 only.
63 .Sh SYNOPSIS
64 .Nm progname
65 .Op Fl options
66 .Ar
67 .Sh DESCRIPTION
68 The
69 .Nm
70 utility processes files ...
71 .\" .Sh IMPLEMENTATION NOTES
72 .\" .Sh RETURN VALUES
73 .\" For sections 2, 3, and 9 only.
74 .\" .Sh CONTEXT
75 .\" For section 9 functions only.
76 .\" .Sh ENVIRONMENT
77 .\" For sections 1, 1M, and 5.
78 .\" .Sh FILES
79 .\" .Sh EXIT STATUS
80 .\" For sections 1, 1M, and 5.
81 .\" .Sh EXAMPLES
82 .\" .Sh DIAGNOSTICS
83 .\" .Sh ERRORS
84 .\" For sections 2, 3, and 9 only.
85 .\" .Sh ARCHITECTURE
86 .\" .Sh CODE SET INDEPENDENCE
87 .\" For sections 1, 1M, and 3 only.
88 .\" .Sh INTERFACE STABILITY
89 .\" .Sh MT-LEVEL
90 .\" For sections 2 and 3 only.
91 .\" .Sh SECURITY
92 .\" .Sh SEE ALSO
93 .\" .Xr foobar 1
94 .\" .Sh STANDARDS
95 .\" .Sh HISTORY
96 .\" .Sh AUTHORS
97 .\" .Sh CAVEATS
98 .\" .Sh BUGS
99
100 The sections in an mdoc document are conventionally ordered as they
101 appear above. Sections should be composed as follows:
102
103 NAME
104 The name(s) and a one line description of the documented material.
105 The syntax for this as follows:
106
107 .Nm name0 ,
108 .Nm name1 ,
109 .Nm name2
110 .Nd a one line description
111
112 Multiple `Nm' names should be separated by commas.
113
114 The Nm macro(s) must precede the Nd macro.
115
116 See Nm and Nd.
117
118 LIBRARY
119 The name of the library containing the documented material, which
120 is assumed to be a function in a section 2, 3, or 9 manual. The
121 syntax for this is as follows:
122
123 .Lb libarm
124
125 See Lb.
126
127 SYNOPSIS
128 Documents the utility invocation syntax, function call syntax, or
129 device configuration.
130
131 For the first, utilities (sections 1 and 1M), this is generally
132 structured as follows:
133
134 .Nm bar
135 .Op Fl v
136 .Op Fl o Ar file
137 .Op Ar
138 .Nm foo
139 .Op Fl v
140 .Op Fl o Ar file
141 .Op Ar
142
143 Commands should be ordered alphabetically.
144
145 For the second, function calls (sections 2, 3, 7I, 7P, 9):
146
147 .In header.h
148 .Vt extern const char *global;
149 .Ft "char *"
150 .Fn foo "const char *src"
151 .Ft "char *"
152 .Fn bar "const char *src"
153
154 Ordering of In, Vt, Fn, and Fo macros should follow C header-file
155 conventions.
156
157 And for the third, configurations (section 7D):
158
159 .Pa /dev/device_node
160
161 Manuals not in these sections generally don't need a SYNOPSIS.
162
163 Some macros are displayed differently in the SYNOPSIS section,
164 particularly Nm, Cd, Fd, Fn, Fo, In, Vt, and Ft. All of these
165 macros are output on their own line. If two such dissimilar macros
166 are pairwise invoked (except for Ft before Fo or Fn), they are
167 separated by a vertical space, unless in the case of Fo, Fn, and
168 Ft, which are always separated by vertical space.
169
170 When text and macros following an Nm macro starting an input line
171 span multiple output lines, all output lines but the first will be
172 indented to align with the text immediately following the Nm macro,
173 up to the next Nm, Sh, or Ss macro or the end of an enclosing
174 block, whichever comes first.
175
176 DESCRIPTION
177 This begins with an expansion of the brief, one line description in
178 NAME:
179
180 The
181 .Nm
182 utility does this, that, and the other.
183
184 It usually follows with a breakdown of the options (if documenting
185 a command), such as:
186
187 The arguments are as follows:
188 .Bl -tag -width Ds
189 .It Fl v
190 Print verbose information.
191 .El
192
193 List the options in alphabetical order, uppercase before lowercase
194 for each letter and with no regard to whether an option takes an
195 argument. Put digits in ascending order before all letter options.
196
197 Manuals not documenting a command won't include the above fragment.
198
199 Since the DESCRIPTION section usually contains most of the text of
200 a manual, longer manuals often use the Ss macro to form
201 subsections. In very long manuals, the DESCRIPTION may be split
202 into multiple sections, each started by an Sh macro followed by a
203 non-standard section name, and each having several subsections,
204 like in the present mdoc manual.
205
206 IMPLEMENTATION NOTES
207 Implementation-specific notes should be kept here. This is useful
208 when implementing standard functions that may have side effects or
209 notable algorithmic implications.
210
211 RETURN VALUES
212 This section documents the return values of functions in sections
213 2, 3, and 9.
214
215 See Rv.
216
217 CONTEXT
218 This section lists the contexts in which functions can be called in
219 section 9. The contexts are user, kernel, or interrupt.
220
221 ENVIRONMENT
222 Lists the environment variables used by the utility, and explains
223 the syntax and semantics of their values. The environ(5) manual
224 provides examples of typical content and formatting.
225
226 See Ev.
227
228 FILES
229 Documents files used. It's helpful to document both the file name
230 and a short description of how the file is used (created, modified,
231 etc.).
232
233 See Pa.
234
235 EXIT STATUS
236 This section documents the command exit status for sections 1 and
237 1M. Historically, this information was described in DIAGNOSTICS, a
238 practise that is now discouraged.
239
240 See Ex.
241
242 EXAMPLES
243 Example usages. This often contains snippets of well-formed, well-
244 tested invocations. Make sure that examples work properly!
245
246 DIAGNOSTICS
247 Documents error and diagnostic messages displayed to the user or
248 sent to logs. Note that exit status and return values should be
249 documented in the EXIT STATUS and RETURN VALUES sections.
250
251 See Bl -diag.
252
253 ERRORS
254 Documents error handling in sections 2, 3, and 9.
255
256 See Er.
257
258 ARCHITECTURE
259 This section is usually absent, but will be present when the
260 interface is specific to one or more architectures.
261
262 CODE SET INDEPENDENCE
263 Indicates whether the interface operates correctly with various
264 different code sets. True independent code sets will support not
265 only ASCII and Extended UNIX Codesets (EUC), but also other multi-
266 byte encodings such as UTF-8 and GB2312.
267
268 Generally there will be some limitations that are fairly standard.
269 See standards(5) for more information about some of these. Most
270 interfaces should support at least UTF-8 in addition to ASCII.
271
272 INTERFACE STABILITY
273 Indicates the level of commitment to the interface. Interfaces can
274 be described with in the following ways:
275
276 Standard
277 Indicates that the interface is defined by one or more
278 standards bodies. Generally, changes to the interface will
279 be carefully managed to conform to the relevant standards.
280 These interfaces are generally the most suitable for use in
281 portable programs.
282
283 Committed
284 Indicates that the interface is intended to be preserved
285 for the long-haul, and will rarely, if ever change, and
286 never without notification (barring extraordinary and
287 extenuating circumstances). These interfaces are preferred
288 over other interfaces with the exeception of Standard
289 interfaces.
290
291 Uncommitted
292 Indicates that the interface may change. Generally,
293 changes to these interfaces should be infrequent, and some
294 effort will be made to address compatibility considerations
295 when changing or removing such interfaces. However, there
296 is no firm commitment to the preservation of the interface.
297 Most often this is applied to interfaces where operational
298 experience with the interface is still limited and some
299 need to change may be anticipated.
300
301 Consumers should expect to revalidate any Uncommitted
302 interfaces when crossing release boundaries. Products
303 intended for use on many releases or intended to support
304 compatibility with future releases should avoid these
305 interfaces.
306
307 Volatile
308 The interface can change at any time for any reason. Often
309 this relates to interfaces that are part of external
310 software components that are still evolving rapidly.
311 Consumers should not expect that the interface (either
312 binary or source level) will be unchanged from one release
313 to the next.
314
315 Not-an-Interface
316 Describes something that is specifically not intended for
317 programmatic consumption. For example, specific human-
318 readable output, or the layout of graphical items on a user
319 interface, may be described this way. Generally
320 programmatic alternatives to these will be available, and
321 should be used when programmatic consumption is needed.
322
323 Private
324 This is an internal interface. Generally these interfaces
325 should only be used within the project, and should not be
326 used by other programs or modules. The interface can and
327 will change without notice as the project needs, at any
328 time.
329
330 Most often, Private interfaces will lack any documentation
331 whatsoever, and generally any undocumented interface can be
332 assumed to be Private.
333
334 Obsolete
335 The interface is not intended for use in new projects or
336 programs, and may be removed at a future date. The
337 Obsolete word is a modifier that can be applied to other
338 commitment levels. For example an Obsolete Committed
339 interface is unlikely to be removed or changed, but
340 nonetheless new use is discouraged (perhaps a better newer
341 alternative is present).
342
343 MT-LEVEL
344 This section describes considerations for the interface when used
345 within programs that use multiple threads. More discussion of
346 these considerations is made in the MT-Level section of
347 attributes(5). The interface can be described in the following
348 ways.
349
350 Safe Indicates the interface is safe for use within multiple
351 threads. There may be additional caveats that apply, in
352 which case those will be described. Note that some
353 interfaces have semantics which may affect other threads,
354 but these should be an intrinsic part of the interface
355 rather than an unexpected side effect. For example,
356 closing a file in one thread will cause that file to be
357 closed in all threads.
358
359 Unsafe Indicates the interface is unsuitable for concurrent use
360 within multiple threads. A threaded application may still
361 make use of the interface, but will be required to provide
362 external synchronization means to ensure that only a single
363 thread calls the interface at a time.
364
365 MT-Safe
366 Indicates that the interface is not only safe for
367 concurrent use, but is designed for such use. For example,
368 a Safe interface may make use of a global lock to provide
369 safety, but at reduced internal concurrency, whereas an
370 MT-Safe interface will be designed to be efficient even
371 when used concurrently.
372
373 Async-Signal-Safe
374 Indicates that the library is safe for use within a signal
375 handler. An MT-Safe interface can be made
376 Async-Signal-Safe by ensuring that it blocks signals when
377 acquiring locks.
378
379 Safe with Exceptions
380 As for Safe but with specific exceptions noted.
381
382 MT-Safe with Exceptions
383 As for MT-Safe but with specific exceptions noted.
384
385 SECURITY
386 Documents any security precautions that operators should consider.
387
388 SEE ALSO
389 References other manuals with related topics. This section should
390 exist for most manuals. Cross-references should conventionally be
391 ordered first by section, then alphabetically (ignoring case).
392
393 References to other documentation concerning the topic of the
394 manual page, for example authoritative books or journal articles,
395 may also be provided in this section.
396
397 See Rs and Xr.
398
399 STANDARDS
400 References any standards implemented or used. If not adhering to
401 any standards, the HISTORY section should be used instead.
402
403 See St.
404
405 HISTORY
406 A brief history of the subject, including where it was first
407 implemented, and when it was ported to or reimplemented for the
408 operating system at hand.
409
410 AUTHORS
411 Credits to the person or persons who wrote the code and/or
412 documentation. Authors should generally be noted by both name and
413 email address.
414
415 See An.
416
417 CAVEATS
418 Common misuses and misunderstandings should be explained in this
419 section.
420
421 BUGS
422 Known bugs, limitations, and work-arounds should be described in
423 this section.
424
425 MACRO OVERVIEW
426 This overview is sorted such that macros of similar purpose are listed
427 together, to help find the best macro for any given purpose. Deprecated
428 macros are not included in the overview, but can be found below in the
429 alphabetical MACRO REFERENCE.
430
431 Document preamble and NAME section macros
432 Dd document date: month day, year
433 Dt document title: TITLE SECTION [arch]
434 Os operating system version: [system [version]]
435 Nm document name (one argument)
436 Nd document description (one line)
437
438 Sections and cross references
439 Sh section header (one line)
440 Ss subsection header (one line)
441 Sx internal cross reference to a section or subsection
442 Xr cross reference to another manual page: name section
443 Pp, Lp start a text paragraph (no arguments)
444
445 Displays and lists
446 Bd, Ed display block: -type [-offset width] [-compact]
447 D1 indented display (one line)
448 Dl indented literal display (one line)
449 Ql in-line literal display: `text'
450 Bl, El list block: -type [-width val] [-offset val] [-compact]
451 It list item (syntax depends on -type)
452 Ta table cell separator in Bl -column lists
453 Rs, %*, Re bibliographic block (references)
454
455 Spacing control
456 Pf prefix, no following horizontal space (one argument)
457 Ns roman font, no preceding horizontal space (no arguments)
458 Ap apostrophe without surrounding whitespace (no arguments)
459 Sm switch horizontal spacing mode: [on | off]
460 Bk, Ek keep block: -words
461
462 Semantic markup for command line utilities
463 Nm start a SYNOPSIS block with the name of a utility
464 Fl command line options (flags) (>=0 arguments)
465 Cm command modifier (>0 arguments)
466 Ar command arguments (>=0 arguments)
467 Op, Oo, Oc optional syntax elements (enclosure)
468 Ic internal or interactive command (>0 arguments)
469 Ev environmental variable (>0 arguments)
470 Pa file system path (>=0 arguments)
471
472 Semantic markup for function libraries
473 Lb function library (one argument)
474 In include file (one argument)
475 Fd other preprocessor directive (>0 arguments)
476 Ft function type (>0 arguments)
477 Fo, Fc function block: funcname
478 Fn function name: [functype] funcname [[argtype] argname]
479 Fa function argument (>0 arguments)
480 Vt variable type (>0 arguments)
481 Va variable name (>0 arguments)
482 Dv defined variable or preprocessor constant (>0 arguments)
483 Er error constant (>0 arguments)
484 Ev environmental variable (>0 arguments)
485
486 Various semantic markup
487 An author name (>0 arguments)
488 Lk hyperlink: uri [name]
489 Mt "mailto" hyperlink: address
490 Cd kernel configuration declaration (>0 arguments)
491 Ad memory address (>0 arguments)
492 Ms mathematical symbol (>0 arguments)
493
494 Physical markup
495 Em italic font or underline (emphasis) (>0 arguments)
496 Sy boldface font (symbolic) (>0 arguments)
497 Li typewriter font (literal) (>0 arguments)
498 No return to roman font (normal) (no arguments)
499 Bf, Ef font block: [-type | Em | Li | Sy]
500
501 Physical enclosures
502 Dq, Do, Dc enclose in typographic double quotes: "text"
503 Qq, Qo, Qc enclose in typewriter double quotes: "text"
504 Sq, So, Sc enclose in single quotes: `text'
505 Pq, Po, Pc enclose in parentheses: (text)
506 Bq, Bo, Bc enclose in square brackets: [text]
507 Brq, Bro, Brc enclose in curly braces: {text}
508 Aq, Ao, Ac enclose in angle brackets: <text>
509 Eo, Ec generic enclosure
510
511 Text production
512 Ex -std standard command exit values: [utility ...]
513 Rv -std standard function return values: [function ...]
514 St reference to a standards document (one argument)
515 At AT&T UNIX
516 Bx BSD
517 Bsx BSD/OS
518 Nx NetBSD
519 Fx FreeBSD
520 Ox OpenBSD
521 Dx DragonFly
522
523 MACRO REFERENCE
524 This section is a canonical reference of all macros, arranged
525 alphabetically. For the scoping of individual macros, see MACRO SYNTAX.
526
527 %A
528 Author name of an Rs block. Multiple authors should each be accorded
529 their own %A line. Author names should be ordered with full or
530 abbreviated forename(s) first, then full surname.
531
532 %B
533 Book title of an Rs block. This macro may also be used in a non-
534 bibliographic context when referring to book titles.
535
536 %C
537 Publication city or location of an Rs block.
538
539 %D
540 Publication date of an Rs block. Recommended formats of arguments are
541 month day, year or just year.
542
543 %I
544 Publisher or issuer name of an Rs block.
545
546 %J
547 Journal name of an Rs block.
548
549 %N
550 Issue number (usually for journals) of an Rs block.
551
552 %O
553 Optional information of an Rs block.
554
555 %P
556 Book or journal page number of an Rs block.
557
558 %Q
559 Institutional author (school, government, etc.) of an Rs block. Multiple
560 institutional authors should each be accorded their own %Q line.
561
562 %R
563 Technical report name of an Rs block.
564
565 %T
566 Article title of an Rs block. This macro may also be used in a non-
567 bibliographical context when referring to article titles.
568
569 %U
570 URI of reference document.
571
572 %V
573 Volume number of an Rs block.
574
575 Ac
576 Close an Ao block. Does not have any tail arguments.
577
578 Ad
579 Memory address. Do not use this for postal addresses.
580
581 Examples:
582 .Ad [0,$]
583 .Ad 0x00000000
584
585 An
586 Author name. Can be used both for the authors of the program, function,
587 or driver documented in the manual, or for the authors of the manual
588 itself. Requires either the name of an author or one of the following
589 arguments:
590
591 -split Start a new output line before each subsequent
592 invocation of An.
593 -nosplit The opposite of -split.
594
595 The default is -nosplit. The effect of selecting either of the -split
596 modes ends at the beginning of the AUTHORS section. In the AUTHORS
597 section, the default is -nosplit for the first author listing and -split
598 for all other author listings.
599
600 Examples:
601 .An -nosplit
602 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
603
604 Ao
605 Begin a block enclosed by angle brackets. Does not have any head
606 arguments. This macro is almost never useful. See Aq for more details.
607
608 Ap
609 Inserts an apostrophe without any surrounding whitespace. This is
610 generally used as a grammatical device when referring to the verb form of
611 a function.
612
613 Examples:
614 .Fn execve Ap d
615
616 Aq
617 Encloses its arguments in angle brackets. The only important use case is
618 for email addresses. See Mt for an example.
619
620 Occasionally, it is used for names of characters and keys, for example:
621
622 Press the
623 .Aq escape
624 key to ...
625
626 For URIs, use Lk instead, and In for "#include" directives. Never wrap
627 Ar in Aq.
628
629 Since Aq usually renders with non-ASCII characters in non-ASCII output
630 modes, do not use it where the ASCII characters `<' and `>' are required
631 as syntax elements. Instead, use these characters directly in such
632 cases, combining them with the macros Pf, Ns, or Eo as needed.
633
634 See also Ao.
635
636 Ar
637 Command arguments. If an argument is not provided, the string "file ..."
638 is used as a default.
639
640 Examples:
641 .Fl o Ar file
642 .Ar
643 .Ar arg1 , arg2 .
644
645 The arguments to the Ar macro are names and placeholders for command
646 arguments; for fixed strings to be passed verbatim as arguments, use Fl
647 or Cm.
648
649 At
650 Formats an AT&T UNIX version. Accepts one optional argument:
651
652 v[1-7] | 32v A version of AT&T UNIX.
653 III AT&T System III UNIX.
654 V | V.[1-4] A version of AT&T System V UNIX.
655
656 Note that these arguments do not begin with a hyphen.
657
658 Examples:
659 .At
660 .At III
661 .At V.1
662
663 See also Bsx, Bx, Dx, Fx, Nx, and Ox.
664
665 Bc
666 Close a Bo block. Does not have any tail arguments.
667
668 Bd
669 Begin a display block. Its syntax is as follows:
670
671 .Bd -type [-offset width] [-compact]
672
673 Display blocks are used to select a different indentation and
674 justification than the one used by the surrounding text. They may
675 contain both macro lines and text lines. By default, a display block is
676 preceded by a vertical space.
677
678 The type must be one of the following:
679
680 -centered Produce one output line from each input line, and
681 center-justify each line. Using this display type
682 is not recommended; many mdoc implementations render
683 it poorly.
684
685 -filled Change the positions of line breaks to fill each
686 line, and left- and right-justify the resulting
687 block.
688
689 -literal Produce one output line from each input line, and do
690 not justify the block at all. Preserve white space
691 as it appears in the input. Always use a constant-
692 width font. Use this for displaying source code.
693
694 -ragged Change the positions of line breaks to fill each
695 line, and left-justify the resulting block.
696
697 -unfilled The same as -literal, but using the same font as for
698 normal text, which is a variable width font if
699 supported by the output device.
700
701 The type must be provided first. Additional arguments may follow:
702
703 -offset width Indent the display by the width, which may be one of
704 the following:
705
706 One of the pre-defined strings indent, the width of
707 a standard indentation (six constant width
708 characters); indent-two, twice indent; left, which
709 has no effect; right, which justifies to the right
710 margin; or center, which aligns around an imagined
711 center axis.
712
713 A macro invocation, which selects a predefined width
714 associated with that macro. The most popular is the
715 imaginary macro Ds, which resolves to 6n.
716
717 A scaling width as described in mandoc_roff(5).
718
719 An arbitrary string, which indents by the length of
720 this string.
721
722 When the argument is missing, -offset is ignored.
723
724 -compact Do not assert vertical space before the display.
725
726 Examples:
727
728 .Bd -literal -offset indent -compact
729 Hello world.
730 .Ed
731
732 See also D1 and Dl.
733
734 Bf
735 Change the font mode for a scoped block of text. Its syntax is as
736 follows:
737
738 .Bf [-emphasis | -literal | -symbolic | Em | Li | Sy]
739
740 The -emphasis and Em argument are equivalent, as are -symbolic and Sy,
741 and -literal and Li. Without an argument, this macro does nothing. The
742 font mode continues until broken by a new font mode in a nested scope or
743 Ef is encountered.
744
745 See also Li, Ef, Em, and Sy.
746
747 Bk
748 For each macro, keep its output together on the same output line, until
749 the end of the macro or the end of the input line is reached, whichever
750 comes first. Line breaks in text lines are unaffected. The syntax is as
751 follows:
752
753 .Bk -words
754
755 The -words argument is required; additional arguments are ignored.
756
757 The following example will not break within each Op macro line:
758
759 .Bk -words
760 .Op Fl f Ar flags
761 .Op Fl o Ar output
762 .Ek
763
764 Be careful in using over-long lines within a keep block! Doing so will
765 clobber the right margin.
766
767 Bl
768 Begin a list. Lists consist of items specified using the It macro,
769 containing a head or a body or both. The list syntax is as follows:
770
771 .Bl -type [-width val] [-offset val] [-compact] [HEAD ...]
772
773 The list type is mandatory and must be specified first. The -width and
774 -offset arguments accept macro names as described for Bd -offset, scaling
775 widths as described in mandoc_roff(5), or use the length of the given
776 string. The -offset is a global indentation for the whole list,
777 affecting both item heads and bodies. For those list types supporting
778 it, the -width argument requests an additional indentation of item
779 bodies, to be added to the -offset. Unless the -compact argument is
780 specified, list entries are separated by vertical space.
781
782 A list must specify one of the following list types:
783
784 -bullet No item heads can be specified, but a bullet will be
785 printed at the head of each item. Item bodies start
786 on the same output line as the bullet and are
787 indented according to the -width argument.
788
789 -column A columnated list. The -width argument has no
790 effect; instead, the string length of each argument
791 specifies the width of one column. If the first line
792 of the body of a -column list is not an It macro
793 line, It contexts spanning one input line each are
794 implied until an It macro line is encountered, at
795 which point items start being interpreted as
796 described in the It documentation.
797
798 -dash Like -bullet, except that dashes are used in place of
799 bullets.
800
801 -diag Like -inset, except that item heads are not parsed
802 for macro invocations. Most often used in the
803 DIAGNOSTICS section with error constants in the item
804 heads.
805
806 -enum A numbered list. No item heads can be specified.
807 Formatted like -bullet, except that cardinal numbers
808 are used in place of bullets, starting at 1.
809
810 -hang Like -tag, except that the first lines of item bodies
811 are not indented, but follow the item heads like in
812 -inset lists.
813
814 -hyphen Synonym for -dash.
815
816 -inset Item bodies follow items heads on the same line,
817 using normal inter-word spacing. Bodies are not
818 indented, and the -width argument is ignored.
819
820 -item No item heads can be specified, and none are printed.
821 Bodies are not indented, and the -width argument is
822 ignored.
823
824 -ohang Item bodies start on the line following item heads
825 and are not indented. The -width argument is
826 ignored.
827
828 -tag Item bodies are indented according to the -width
829 argument. When an item head fits inside the
830 indentation, the item body follows this head on the
831 same output line. Otherwise, the body starts on the
832 output line following the head.
833
834 Lists may be nested within lists and displays. Nesting of -column and
835 -enum lists may not be portable.
836
837 See also El and It.
838
839 Bo
840 Begin a block enclosed by square brackets. Does not have any head
841 arguments.
842
843 Examples:
844 .Bo 1 ,
845 .Dv BUFSIZ Bc
846
847 See also Bq.
848
849 Bq
850 Encloses its arguments in square brackets.
851
852 Examples:
853 .Bq 1, Dv BUFSIZ
854
855 Remarks: this macro is sometimes abused to emulate optional arguments for
856 commands; the correct macros to use for this purpose are Op, Oo, and Oc.
857
858 See also Bo.
859
860 Brc
861 Close a Bro block. Does not have any tail arguments.
862
863 Bro
864 Begin a block enclosed by curly braces. Does not have any head
865 arguments.
866
867 Examples:
868 .Bro 1 , ... ,
869 .Va n Brc
870
871 See also Brq.
872
873 Brq
874 Encloses its arguments in curly braces.
875
876 Examples:
877 .Brq 1, ..., Va n
878
879 See also Bro.
880
881 Bsx
882 Format the BSD/OS version provided as an argument, or a default value if
883 no argument is provided.
884
885 Examples:
886 .Bsx 1.0
887 .Bsx
888
889 See also At, Bx, Dx, Fx, Nx, and Ox.
890
891 Bt
892 Supported only for compatibility, do not use this in new manuals. Prints
893 "is currently in beta test."
894
895 Bx
896 Format the BSD version provided as an argument, or a default value if no
897 argument is provided.
898
899 Examples:
900 .Bx 4.3 Tahoe
901 .Bx 4.4
902 .Bx
903
904 See also At, Bsx, Dx, Fx, Nx, and Ox.
905
906 Cd
907 Kernel configuration declaration. It is found in pages for BSD and not
908 used here.
909
910 Examples:
911 .Cd device le0 at scode?
912
913 Remarks: this macro is commonly abused by using quoted literals to retain
914 whitespace and align consecutive Cd declarations. This practise is
915 discouraged.
916
917 Cm
918 Command modifiers. Typically used for fixed strings passed as arguments,
919 unless Fl is more appropriate. Also useful when specifying configuration
920 options or keys.
921
922 Examples:
923 .Nm mt Fl f Ar device Cm rewind
924 .Nm ps Fl o Cm pid , Ns Cm command
925 .Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2
926 .Cm IdentityFile Pa ~/.ssh/id_rsa
927 .Cm LogLevel Dv DEBUG
928
929 D1
930 One-line indented display. This is formatted by the default rules and is
931 useful for simple indented statements. It is followed by a newline.
932
933 Examples:
934 .D1 Fl abcdefgh
935
936 See also Bd and Dl.
937
938 Db
939 This macro is obsolete. No replacement is needed. It is ignored by
940 mandoc(1) and groff including its arguments. It was formerly used to
941 toggle a debugging mode.
942
943 Dc
944 Close a Do block. Does not have any tail arguments.
945
946 Dd
947 Document date for display in the page footer. This is the mandatory
948 first macro of any mdoc manual. Its syntax is as follows:
949
950 .Dd month day, year
951
952 The month is the full English month name, the day is an integer number,
953 and the year is the full four-digit year.
954
955 Other arguments are not portable; the mandoc(1) utility handles them as
956 follows:
957 - To have the date automatically filled in by the OpenBSD version of
958 cvs(1), the special string "$Mdocdate$" can be given as an
959 argument.
960 - The traditional, purely numeric man(5) format year-month-day is
961 accepted, too.
962 - If a date string cannot be parsed, it is used verbatim.
963 - If no date string is given, the current date is used.
964
965 Examples:
966 .Dd $Mdocdate$
967 .Dd $Mdocdate: July 2 2018$
968 .Dd July 2, 2018
969
970 See also Dt and Os.
971
972 Dl
973 One-line indented display. This is formatted as literal text and is
974 useful for commands and invocations. It is followed by a newline.
975
976 Examples:
977 .Dl % mandoc mdoc.5 \(ba less
978
979 See also Ql, Bd -literal, and D1.
980
981 Do
982 Begin a block enclosed by double quotes. Does not have any head
983 arguments.
984
985 Examples:
986 .Do
987 April is the cruellest month
988 .Dc
989 \(em T.S. Eliot
990
991 See also Dq.
992
993 Dq
994 Encloses its arguments in "typographic" double-quotes.
995
996 Examples:
997 .Dq April is the cruellest month
998 \(em T.S. Eliot
999
1000 See also Qq, Sq, and Do.
1001
1002 Dt
1003 Document title for display in the page header. This is the mandatory
1004 second macro of any mdoc file. Its syntax is as follows:
1005
1006 .Dt TITLE section [arch]
1007
1008 Its arguments are as follows:
1009
1010 TITLE The document's title (name), defaulting to "UNTITLED" if
1011 unspecified. To achieve a uniform appearance of page header
1012 lines, it should by convention be all caps.
1013
1014 SECTION The manual section. It should correspond to the manual's
1015 filename suffix and defaults to the empty string if
1016 unspecified. This field is optional. To achieve a uniform
1017 appearance of page header lines, it should by convention be
1018 all caps.
1019
1020 arch This specifies the machine architecture a manual page applies
1021 to, where relevant.
1022
1023 Dv
1024 Defined variables such as preprocessor constants, constant symbols,
1025 enumeration values, and so on.
1026
1027 Examples:
1028 .Dv NULL
1029 .Dv BUFSIZ
1030 .Dv STDOUT_FILENO
1031
1032 See also Er and Ev for special-purpose constants, Va for variable
1033 symbols, and Fd for listing preprocessor variable definitions in the
1034 SYNOPSIS.
1035
1036 Dx
1037 Format the DragonFly version provided as an argument, or a default value
1038 if no argument is provided.
1039
1040 Examples:
1041 .Dx 2.4.1
1042 .Dx
1043
1044 See also At, Bsx, Bx, Fx, Nx, and Ox.
1045
1046 Ec
1047 Close a scope started by Eo. Its syntax is as follows:
1048
1049 .Ec [TERM]
1050
1051 The TERM argument is used as the enclosure tail, for example, specifying
1052 \(rq will emulate Dc.
1053
1054 Ed
1055 End a display context started by Bd.
1056
1057 Ef
1058 End a font mode context started by Bf.
1059
1060 Ek
1061 End a keep context started by Bk.
1062
1063 El
1064 End a list context started by Bl.
1065
1066 See also Bl and It.
1067
1068 Em
1069 Request an italic font. If the output device does not provide that,
1070 underline.
1071
1072 This is most often used for stress emphasis (not to be confused with
1073 importance, see Sy). In the rare cases where none of the semantic markup
1074 macros fit, it can also be used for technical terms and placeholders,
1075 except that for syntax elements, Sy and Ar are preferred, respectively.
1076
1077 Examples:
1078 Selected lines are those
1079 .Em not
1080 matching any of the specified patterns.
1081 Some of the functions use a
1082 .Em hold space
1083 to save the pattern space for subsequent retrieval.
1084
1085 See also Bf, Li, No, and Sy.
1086
1087 En
1088 This macro is obsolete. Use Eo or any of the other enclosure macros.
1089
1090 It encloses its argument in the delimiters specified by the last Es
1091 macro.
1092
1093 Eo
1094 An arbitrary enclosure. Its syntax is as follows:
1095
1096 .Eo [TERM]
1097
1098 The TERM argument is used as the enclosure head, for example, specifying
1099 \(lq will emulate Do.
1100
1101 Er
1102 Error constants for definitions of the errno libc global variable. This
1103 is most often used in section 2 and 3 manual pages.
1104
1105 Examples:
1106 .Er EPERM
1107 .Er ENOENT
1108
1109 See also Dv for general constants.
1110
1111 Es
1112 This macro is obsolete. Use Eo or any of the other enclosure macros.
1113
1114 It takes two arguments, defining the delimiters to be used by subsequent
1115 En macros.
1116
1117 Ev
1118 Environmental variables such as those specified in environ(5).
1119
1120 Examples:
1121 .Ev DISPLAY
1122 .Ev PATH
1123
1124 See also Dv for general constants.
1125
1126 Ex
1127 Insert a standard sentence regarding command exit values of 0 on success
1128 and >0 on failure. This is most often used in section 1 and 1M manual
1129 pages. Its syntax is as follows:
1130
1131 .Ex -std [utility ...]
1132
1133 If utility is not specified, the document's name set by Nm is used.
1134 Multiple utility arguments are treated as separate utilities.
1135
1136 See also Rv.
1137
1138 Fa
1139 Function argument or parameter. Its syntax is as follows:
1140
1141 .Fa "[argtype] [argname]" ...
1142
1143 Each argument may be a name and a type (recommended for the SYNOPSIS
1144 section), a name alone (for function invocations), or a type alone (for
1145 function prototypes). If both a type and a name are given or if the type
1146 consists of multiple words, all words belonging to the same function
1147 argument have to be given in a single argument to the Fa macro.
1148
1149 This macro is also used to specify the field name of a structure.
1150
1151 Most often, the Fa macro is used in the SYNOPSIS within Fo blocks when
1152 documenting multi-line function prototypes. If invoked with multiple
1153 arguments, the arguments are separated by a comma. Furthermore, if the
1154 following macro is another Fa, the last argument will also have a
1155 trailing comma.
1156
1157 Examples:
1158 .Fa "const char *p"
1159 .Fa "int a" "int b" "int c"
1160 .Fa "char *" size_t
1161
1162 See also Fo.
1163
1164 Fc
1165 End a function context started by Fo.
1166
1167 Fd
1168 Preprocessor directive, in particular for listing it in the SYNOPSIS.
1169 Historically, it was also used to document include files. The latter
1170 usage has been deprecated in favour of In.
1171
1172 Its syntax is as follows:
1173
1174 .Fd #directive [argument ...]
1175
1176 Examples:
1177 .Fd #define sa_handler __sigaction_u.__sa_handler
1178 .Fd #define SIO_MAXNFDS
1179 .Fd #ifdef FS_DEBUG
1180 .Ft void
1181 .Fn dbg_open "const char *"
1182 .Fd #endif
1183
1184 See also MANUAL STRUCTURE, In, and Dv.
1185
1186 Fl
1187 Command-line flag or option. Used when listing arguments to command-line
1188 utilities. Prints a fixed-width hyphen `-' directly followed by each
1189 argument. If no arguments are provided, a hyphen is printed followed by
1190 a space. If the argument is a macro, a hyphen is prefixed to the
1191 subsequent macro output.
1192
1193 Examples:
1194 .Fl R Op Fl H | L | P
1195 .Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux
1196 .Fl type Cm d Fl name Pa CVS
1197 .Fl Ar signal_number
1198 .Fl o Fl
1199
1200 See also Cm.
1201
1202 Fn
1203 A function name. Its syntax is as follows:
1204
1205 .Fn [functype] funcname [[argtype] argname]
1206
1207 Function arguments are surrounded in parenthesis and are delimited by
1208 commas. If no arguments are specified, blank parenthesis are output. In
1209 the SYNOPSIS section, this macro starts a new output line, and a blank
1210 line is automatically inserted between function definitions.
1211
1212 Examples:
1213 .Fn "int funcname" "int arg0" "int arg1"
1214 .Fn funcname "int arg0"
1215 .Fn funcname arg0
1216
1217 .Ft functype
1218 .Fn funcname
1219
1220 When referring to a function documented in another manual page, use Xr
1221 instead. See also MANUAL STRUCTURE, Fo, and Ft.
1222
1223 Fo
1224 Begin a function block. This is a multi-line version of Fn. Its syntax
1225 is as follows:
1226
1227 .Fo funcname
1228
1229 Invocations usually occur in the following context:
1230
1231 .Ft functype
1232 .Fo funcname
1233 .Fa "argtype argname"
1234 ...
1235 .Fc
1236
1237 A Fo scope is closed by Fc.
1238
1239 See also MANUAL STRUCTURE, Fa, Fc, and Ft.
1240
1241 Fr
1242 This macro is obsolete. No replacement markup is needed.
1243
1244 It was used to show numerical function return values in an italic font.
1245
1246 Ft
1247 A function type. Its syntax is as follows:
1248
1249 .Ft functype
1250
1251 In the SYNOPSIS section, a new output line is started after this macro.
1252
1253 Examples:
1254 .Ft int
1255 .Ft functype
1256 .Fn funcname
1257
1258 See also MANUAL STRUCTURE, Fn, and Fo.
1259
1260 Fx
1261 Format the FreeBSD version provided as an argument, or a default value if
1262 no argument is provided.
1263
1264 Examples:
1265 .Fx 7.1
1266 .Fx
1267
1268 See also At, Bsx, Bx, Dx, Nx, and Ox.
1269
1270 Hf
1271 This macro is not implemented in mandoc(1).
1272
1273 It was used to include the contents of a (header) file literally. The
1274 syntax was:
1275
1276 .Hf filename
1277
1278 Ic
1279 Designate an internal or interactive command. This is similar to Cm but
1280 used for instructions rather than values.
1281
1282 Examples:
1283 .Ic :wq
1284 .Ic hash
1285 .Ic alias
1286
1287 Note that using Bd -literal or D1 is preferred for displaying code; the
1288 Ic macro is used when referring to specific instructions.
1289
1290 In
1291 The name of an include file. This macro is most often used in section 2,
1292 3, and 9 manual pages.
1293
1294 When invoked as the first macro on an input line in the SYNOPSIS section,
1295 the argument is displayed in angle brackets and preceded by "#include",
1296 and a blank line is inserted in front if there is a preceding function
1297 declaration. In other sections, it only encloses its argument in angle
1298 brackets and causes no line break.
1299
1300 Examples:
1301 .In sys/types.h
1302
1303 See also MANUAL STRUCTURE.
1304
1305 It
1306 A list item. The syntax of this macro depends on the list type.
1307
1308 Lists of type -hang, -ohang, -inset, and -diag have the following syntax:
1309
1310 .It args
1311
1312 Lists of type -bullet, -dash, -enum, -hyphen and -item have the following
1313 syntax:
1314
1315 .It
1316
1317 with subsequent lines interpreted within the scope of the It until either
1318 a closing El or another It.
1319
1320 The -tag list has the following syntax:
1321
1322 .It [args]
1323
1324 Subsequent lines are interpreted as with -bullet and family. The line
1325 arguments correspond to the list's left-hand side; body arguments
1326 correspond to the list's contents.
1327
1328 The -column list is the most complicated. Its syntax is as follows:
1329
1330 .It cell [Ta cell ...]
1331 .It cell [<TAB> cell ...]
1332
1333 The arguments consist of one or more lines of text and macros
1334 representing a complete table line. Cells within the line are delimited
1335 by the special Ta block macro or by literal tab characters.
1336
1337 Using literal tabs is strongly discouraged because they are very hard to
1338 use correctly and mdoc code using them is very hard to read. In
1339 particular, a blank character is syntactically significant before and
1340 after the literal tab character. If a word precedes or follows the tab
1341 without an intervening blank, that word is never interpreted as a macro
1342 call, but always output literally.
1343
1344 The tab cell delimiter may only be used within the It line itself; on
1345 following lines, only the Ta macro can be used to delimit cells, and
1346 portability requires that Ta is called by other macros: some parsers do
1347 not recognize it when it appears as the first macro on a line.
1348
1349 Note that quoted strings may span tab-delimited cells on an It line. For
1350 example,
1351
1352 .It "col1 , <TAB> col2 ," ;
1353
1354 will preserve the whitespace before both commas, but not the whitespace
1355 before the semicolon.
1356
1357 See also Bl.
1358
1359 Lb
1360 Specify a library. The syntax is as follows:
1361
1362 .Lb library
1363
1364 The library parameter may be a system library, such as libz or libpam, in
1365 which case a small library description is printed next to the linker
1366 invocation; or a custom library, in which case the library name is
1367 printed in quotes. This is most commonly used in the SYNOPSIS section as
1368 described in MANUAL STRUCTURE.
1369
1370 Examples:
1371 .Lb libz
1372 .Lb mdoc
1373
1374 Li
1375 Denotes text that should be in a literal font mode. Note that this is a
1376 presentation term and should not be used for stylistically decorating
1377 technical terms.
1378
1379 On terminal output devices, this is often indistinguishable from normal
1380 text.
1381
1382 See also Bf, Em, No, and Sy.
1383
1384 Lk
1385 Format a hyperlink. Its syntax is as follows:
1386
1387 .Lk uri [name]
1388
1389 Examples:
1390 .Lk http://bsd.lv "The BSD.lv Project"
1391 .Lk http://bsd.lv
1392
1393 See also Mt.
1394
1395 Lp
1396 Synonym for Pp.
1397
1398 Ms
1399 Display a mathematical symbol. Its syntax is as follows:
1400
1401 .Ms symbol
1402
1403 Examples:
1404 .Ms sigma
1405 .Ms aleph
1406
1407 Mt
1408 Format a "mailto:" hyperlink. Its syntax is as follows:
1409
1410 .Mt address
1411
1412 Examples:
1413 .Mt discuss@manpages.bsd.lv
1414 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1415
1416 Nd
1417 A one line description of the manual's content. This is the mandatory
1418 last macro of the NAME section and not appropriate for other sections.
1419
1420 Examples:
1421 .Nd mdoc language reference
1422 .Nd format and display UNIX manuals
1423
1424 The Nd macro technically accepts child macros and terminates with a
1425 subsequent Sh invocation. Do not assume this behaviour: some whatis(1)
1426 database generators are not smart enough to parse more than the line
1427 arguments and will display macros verbatim.
1428
1429 See also Nm.
1430
1431 Nm
1432 The name of the manual page, or -- in particular in section 1 pages -- of
1433 an additional command or feature documented in the manual page. When
1434 first invoked, the Nm macro expects a single argument, the name of the
1435 manual page. Usually, the first invocation happens in the NAME section
1436 of the page. The specified name will be remembered and used whenever the
1437 macro is called again without arguments later in the page. The Nm macro
1438 uses Block full-implicit semantics when invoked as the first macro on an
1439 input line in the SYNOPSIS section; otherwise, it uses ordinary In-line
1440 semantics.
1441
1442 Examples:
1443
1444 .Sh SYNOPSIS
1445 .Nm cat
1446 .Op Fl benstuv
1447 .Op Ar
1448
1449 In the SYNOPSIS of section 2, 3 and 9 manual pages, use the Fn macro
1450 rather than Nm to mark up the name of the manual page.
1451
1452 No
1453 Normal text. Closes the scope of any preceding in-line macro. When used
1454 after physical formatting macros like Em or Sy, switches back to the
1455 standard font face and weight. Can also be used to embed plain text
1456 strings in macro lines using semantic annotation macros.
1457
1458 Examples:
1459 .Em italic , Sy bold , No and roman
1460
1461 .Sm off
1462 .Cm :C No / Ar pattern No / Ar replacement No /
1463 .Sm on
1464
1465 See also Em, Li, and Sy.
1466
1467 Ns
1468 Suppress a space between the output of the preceding macro and the
1469 following text or macro. Following invocation, input is interpreted as
1470 normal text just like after an No macro.
1471
1472 This has no effect when invoked at the start of a macro line.
1473
1474 Examples:
1475 .Ar name Ns = Ns Ar value
1476 .Cm :M Ns Ar pattern
1477 .Fl o Ns Ar output
1478
1479 See also No and Sm.
1480
1481 Nx
1482 Format the NetBSD version provided as an argument, or a default value if
1483 no argument is provided.
1484
1485 Examples:
1486 .Nx 5.01
1487 .Nx
1488
1489 See also At, Bsx, Bx, Dx, Fx, and Ox.
1490
1491 Oc
1492 Close multi-line Oo context.
1493
1494 Oo
1495 Multi-line version of Op.
1496
1497 Examples:
1498 .Oo
1499 .Op Fl flag Ns Ar value
1500 .Oc
1501
1502 Op
1503 Optional part of a command line. Prints the argument(s) in brackets.
1504 This is most often used in the SYNOPSIS section of section 1 and 1M
1505 manual pages.
1506
1507 Examples:
1508 .Op Fl a Ar b
1509 .Op Ar a | b
1510
1511 See also Oo.
1512
1513 Os
1514 Operating system version for display in the page footer. This is the
1515 mandatory third macro of any mdoc file. Its syntax is as follows:
1516
1517 .Os [system [version]]
1518
1519 The optional system parameter specifies the relevant operating system or
1520 environment. It is suggested to leave it unspecified, in which case
1521 mandoc(1) uses its -Ios argument or, if that isn't specified either,
1522 sysname and release as returned by uname(3).
1523
1524 Examples:
1525 .Os
1526 .Os KTH/CSC/TCS
1527 .Os BSD 4.3
1528
1529 See also Dd and Dt.
1530
1531 Ot
1532 This macro is obsolete. Use Ft instead; with mandoc(1), both have the
1533 same effect.
1534
1535 Historical mdoc packages described it as "old function type (FORTRAN)".
1536
1537 Ox
1538 Format the OpenBSD version provided as an argument, or a default value if
1539 no argument is provided.
1540
1541 Examples:
1542 .Ox 4.5
1543 .Ox
1544
1545 See also At, Bsx, Bx, Dx, Fx, and Nx.
1546
1547 Pa
1548 An absolute or relative file system path, or a file or directory name.
1549 If an argument is not provided, the character `~' is used as a default.
1550
1551 Examples:
1552 .Pa /usr/bin/mandoc
1553 .Pa /usr/share/man/man5/mdoc.5
1554
1555 See also Lk.
1556
1557 Pc
1558 Close parenthesised context opened by Po.
1559
1560 Pf
1561 Removes the space between its argument and the following macro. Its
1562 syntax is as follows:
1563
1564 .Pf prefix macro arguments ...
1565
1566 This is equivalent to:
1567
1568 .No \&prefix Ns macro arguments ...
1569
1570 The prefix argument is not parsed for macro names or delimiters, but used
1571 verbatim as if it were escaped.
1572
1573 Examples:
1574 .Pf $ Ar variable_name
1575 .Pf . Ar macro_name
1576 .Pf 0x Ar hex_digits
1577
1578 See also Ns and Sm.
1579
1580 Po
1581 Multi-line version of Pq.
1582
1583 Pp
1584 Break a paragraph. This will assert vertical space between prior and
1585 subsequent macros and/or text.
1586
1587 Paragraph breaks are not needed before or after Sh or Ss macros or before
1588 displays (Bd) or lists (Bl) unless the -compact flag is given.
1589
1590 Pq
1591 Parenthesised enclosure.
1592
1593 See also Po.
1594
1595 Qc
1596 Close quoted context opened by Qo.
1597
1598 Ql
1599 In-line literal display. This can for example be used for complete
1600 command invocations and for multi-word code fragments when more specific
1601 markup is not appropriate and an indented display is not desired. While
1602 mandoc(1) always encloses the arguments in single quotes, other
1603 formatters usually omit the quotes on non-terminal output devices when
1604 the arguments have three or more characters.
1605
1606 See also Dl and Bd -literal.
1607
1608 Qo
1609 Multi-line version of Qq.
1610
1611 Qq
1612 Encloses its arguments in "typewriter" double-quotes. Consider using Dq.
1613
1614 See also Dq, Sq, and Qo.
1615
1616 Re
1617 Close an Rs block. Does not have any tail arguments.
1618
1619 Rs
1620 Begin a bibliographic ("reference") block. Does not have any head
1621 arguments. The block macro may only contain %A, %B, %C, %D, %I, %J, %N,
1622 %O, %P, %Q, %R, %T, %U, and %V child macros (at least one must be
1623 specified).
1624
1625 Examples:
1626 .Rs
1627 .%A J. E. Hopcroft
1628 .%A J. D. Ullman
1629 .%B Introduction to Automata Theory, Languages, and Computation
1630 .%I Addison-Wesley
1631 .%C Reading, Massachusetts
1632 .%D 1979
1633 .Re
1634
1635 If an Rs block is used within a SEE ALSO section, a vertical space is
1636 asserted before the rendered output, else the block continues on the
1637 current line.
1638
1639 Rv
1640 Insert a standard sentence regarding a function call's return value of 0
1641 on success and -1 on error, with the errno libc global variable set on
1642 error. Its syntax is as follows:
1643
1644 .Rv -std [function ...]
1645
1646 If function is not specified, the document's name set by Nm is used.
1647 Multiple function arguments are treated as separate functions.
1648
1649 See also Ex.
1650
1651 Sc
1652 Close single-quoted context opened by So.
1653
1654 Sh
1655 Begin a new section. For a list of conventional manual sections, see
1656 MANUAL STRUCTURE. These sections should be used unless it's absolutely
1657 necessary that custom sections be used.
1658
1659 Section names should be unique so that they may be keyed by Sx. Although
1660 this macro is parsed, it should not consist of child node or it may not
1661 be linked with Sx.
1662
1663 See also Pp, Ss, and Sx.
1664
1665 Sm
1666 Switches the spacing mode for output generated from macros. Its syntax
1667 is as follows:
1668
1669 .Sm [on | off]
1670
1671 By default, spacing is on. When switched off, no white space is inserted
1672 between macro arguments and between the output generated from adjacent
1673 macros, but text lines still get normal spacing between words and
1674 sentences.
1675
1676 When called without an argument, the Sm macro toggles the spacing mode.
1677 Using this is not recommended because it makes the code harder to read.
1678
1679 So
1680 Multi-line version of Sq.
1681
1682 Sq
1683 Encloses its arguments in `typewriter' single-quotes.
1684
1685 See also Dq, Qq, and So.
1686
1687 Ss
1688 Begin a new subsection. Unlike with Sh, there is no convention for the
1689 naming of subsections. Except DESCRIPTION, the conventional sections
1690 described in MANUAL STRUCTURE rarely have subsections.
1691
1692 Sub-section names should be unique so that they may be keyed by Sx.
1693 Although this macro is parsed, it should not consist of child node or it
1694 may not be linked with Sx.
1695
1696 See also Pp, Sh, and Sx.
1697
1698 St
1699 Replace an abbreviation for a standard with the full form. The following
1700 standards are recognised. Where multiple lines are given without a blank
1701 line in between, they all refer to the same standard, and using the first
1702 form is recommended.
1703
1704 C language standards
1705
1706 -ansiC ANSI X3.159-1989 ("ANSI C89")
1707 -ansiC-89 ANSI X3.159-1989 ("ANSI C89")
1708 -isoC ISO/IEC 9899:1990 ("ISO C90")
1709 -isoC-90 ISO/IEC 9899:1990 ("ISO C90")
1710 The original C standard.
1711
1712 -isoC-amd1 ISO/IEC 9899/AMD1:1995 ("ISO C90, Amendment 1")
1713
1714 -isoC-tcor1 ISO/IEC 9899/TCOR1:1994 ("ISO C90, Technical
1715 Corrigendum 1")
1716
1717 -isoC-tcor2 ISO/IEC 9899/TCOR2:1995 ("ISO C90, Technical
1718 Corrigendum 2")
1719
1720 -isoC-99 ISO/IEC 9899:1999 ("ISO C99")
1721 The second major version of the C language standard.
1722
1723 -isoC-2011 ISO/IEC 9899:2011 ("ISO C11")
1724 The third major version of the C language standard.
1725
1726 POSIX.1 before the Single UNIX Specification
1727
1728 -p1003.1-88 IEEE Std 1003.1-1988 ("POSIX.1")
1729 -p1003.1 IEEE Std 1003.1 ("POSIX.1")
1730 The original POSIX standard, based on ANSI C.
1731
1732 -p1003.1-90 IEEE Std 1003.1-1990 ("POSIX.1")
1733 -iso9945-1-90 ISO/IEC 9945-1:1990 ("POSIX.1")
1734 The first update of POSIX.1.
1735
1736 -p1003.1b-93 IEEE Std 1003.1b-1993 ("POSIX.1b")
1737 -p1003.1b IEEE Std 1003.1b ("POSIX.1b")
1738 Real-time extensions.
1739
1740 -p1003.1c-95 IEEE Std 1003.1c-1995 ("POSIX.1c")
1741 POSIX thread interfaces.
1742
1743 -p1003.1i-95 IEEE Std 1003.1i-1995 ("POSIX.1i")
1744 Technical Corrigendum.
1745
1746 -p1003.1-96 ISO/IEC 9945-1:1996 ("POSIX.1")
1747 -iso9945-1-96 ISO/IEC 9945-1:1996 ("POSIX.1")
1748 Includes POSIX.1-1990, 1b, 1c, and 1i.
1749
1750 X/Open Portability Guide version 4 and related standards
1751
1752 -xpg3 X/Open Portability Guide Issue 3 ("XPG3")
1753 An XPG4 precursor, published in 1989.
1754
1755 -p1003.2 IEEE Std 1003.2 ("POSIX.2")
1756 -p1003.2-92 IEEE Std 1003.2-1992 ("POSIX.2")
1757 -iso9945-2-93 ISO/IEC 9945-2:1993 ("POSIX.2")
1758 An XCU4 precursor.
1759
1760 -p1003.2a-92 IEEE Std 1003.2a-1992 ("POSIX.2")
1761 Updates to POSIX.2.
1762
1763 -xpg4 X/Open Portability Guide Issue 4 ("XPG4")
1764 Based on POSIX.1 and POSIX.2, published in 1992.
1765
1766 Single UNIX Specification version 1 and related standards
1767
1768 -susv1 Version 1 of the Single UNIX Specification ("SUSv1")
1769 -xpg4.2 X/Open Portability Guide Issue 4, Version 2 ("XPG4.2")
1770 This standard was published in 1994. It was used as
1771 the basis for UNIX 95 certification. The following
1772 three refer to parts of it.
1773
1774 -xsh4.2 X/Open System Interfaces and Headers Issue 4,
1775 Version 2 ("XSH4.2")
1776
1777 -xcurses4.2 X/Open Curses Issue 4, Version 2 ("XCURSES4.2")
1778
1779 -p1003.1g-2000 IEEE Std 1003.1g-2000 ("POSIX.1g")
1780 Networking APIs, including sockets.
1781
1782 -svid4 System V Interface Definition, Fourth Edition
1783 ("SVID4"),
1784 Published in 1995.
1785
1786 Single UNIX Specification version 2 and related standards
1787
1788 -susv2 Version 2 of the Single UNIX Specification ("SUSv2")
1789 This Standard was published in 1997 and is also called
1790 X/Open Portability Guide version 5. It was used as
1791 the basis for UNIX 98 certification. The following
1792 refer to parts of it.
1793
1794 -xbd5 X/Open Base Definitions Issue 5 ("XBD5")
1795
1796 -xsh5 X/Open System Interfaces and Headers Issue 5 ("XSH5")
1797
1798 -xcu5 X/Open Commands and Utilities Issue 5 ("XCU5")
1799
1800 -xns5 X/Open Networking Services Issue 5 ("XNS5")
1801 -xns5.2 X/Open Networking Services Issue 5.2 ("XNS5.2")
1802
1803 Single UNIX Specification version 3
1804
1805 -p1003.1-2001 IEEE Std 1003.1-2001 ("POSIX.1")
1806 -susv3 Version 3 of the Single UNIX Specification ("SUSv3")
1807 This standard is based on C99, SUSv2, POSIX.1-1996, 1d,
1808 and 1j. It is also called X/Open Portability Guide
1809 version 6. It is used as the basis for UNIX 03
1810 certification.
1811
1812 -p1003.1-2004 IEEE Std 1003.1-2004 ("POSIX.1")
1813 The second and last Technical Corrigendum.
1814
1815 Single UNIX Specification version 4
1816
1817 -p1003.1-2008 IEEE Std 1003.1-2008 ("POSIX.1")
1818 -susv4 Version 4 of the Single UNIX Specification ("SUSv4")
1819 This standard is also called X/Open Portability Guide
1820 version 7.
1821
1822 Other standards
1823
1824 -ieee754 IEEE Std 754-1985
1825 Floating-point arithmetic.
1826
1827 -iso8601 ISO 8601
1828 Representation of dates and times, published in 1988.
1829
1830 -iso8802-3 ISO 8802-3: 1989
1831 Ethernet local area networks.
1832
1833 -ieee1275-94 IEEE Std 1275-1994 ("Open Firmware")
1834
1835 Sx
1836 Reference a section or subsection in the same manual page. The
1837 referenced section or subsection name must be identical to the enclosed
1838 argument, including whitespace.
1839
1840 Examples:
1841 .Sx MANUAL STRUCTURE
1842
1843 See also Sh and Ss.
1844
1845 Sy
1846 Request a boldface font.
1847
1848 This is most often used to indicate importance or seriousness (not to be
1849 confused with stress emphasis, see Em). When none of the semantic macros
1850 fit, it is also adequate for syntax elements that have to be given or
1851 that appear verbatim.
1852
1853 Examples:
1854 .Sy Warning :
1855 If
1856 .Sy s
1857 appears in the owner permissions, set-user-ID mode is set.
1858 This utility replaces the former
1859 .Sy dumpdir
1860 program.
1861
1862 See also Bf, Em, Li, and No.
1863
1864 Ta
1865 Table cell separator in Bl -column lists; can only be used below It.
1866
1867 Tn
1868 Supported only for compatibility, do not use this in new manuals. Even
1869 though the macro name ("tradename") suggests a semantic function,
1870 historic usage is inconsistent, mostly using it as a presentation-level
1871 macro to request a small caps font.
1872
1873 Ud
1874 Supported only for compatibility, do not use this in new manuals. Prints
1875 out "currently under development."
1876
1877 Ux
1878 Supported only for compatibility, do not use this in new manuals. Prints
1879 out "UNIX".
1880
1881 Va
1882 A variable name.
1883
1884 Examples:
1885 .Va foo
1886 .Va const char *bar;
1887
1888 For function arguments and parameters, use Fa instead. For declarations
1889 of global variables in the SYNOPSIS section, use Vt.
1890
1891 Vt
1892 A variable type.
1893
1894 This is also used for indicating global variables in the SYNOPSIS
1895 section, in which case a variable name is also specified. Note that it
1896 accepts Block partial-implicit syntax when invoked as the first macro on
1897 an input line in the SYNOPSIS section, else it accepts ordinary In-line
1898 syntax. In the former case, this macro starts a new output line, and a
1899 blank line is inserted in front if there is a preceding function
1900 definition or include directive.
1901
1902 Examples:
1903 .Vt unsigned char
1904 .Vt extern const char * const sys_signame[] ;
1905
1906 For parameters in function prototypes, use Fa instead, for function
1907 return types Ft, and for variable names outside the SYNOPSIS section Va,
1908 even when including a type with the name. See also MANUAL STRUCTURE.
1909
1910 Xc
1911 Close a scope opened by Xo.
1912
1913 Xo
1914 Extend the header of an It macro or the body of a partial-implicit block
1915 macro beyond the end of the input line. This macro originally existed to
1916 work around the 9-argument limit of historic mandoc_roff(5).
1917
1918 Xr
1919 Link to another manual ("cross-reference"). Its syntax is as follows:
1920
1921 .Xr name section
1922
1923 Cross reference the name and section number of another man page.
1924
1925 Examples:
1926 .Xr mandoc 1
1927 .Xr mandoc 1 ;
1928 .Xr mandoc 1 Ns s behaviour
1929
1930 MACRO SYNTAX
1931 The syntax of a macro depends on its classification. In this section,
1932 `-arg' refers to macro arguments, which may be followed by zero or more
1933 `parm' parameters; `Yo' opens the scope of a macro; and if specified,
1934 `Yc' closes it out.
1935
1936 The Callable column indicates that the macro may also be called by
1937 passing its name as an argument to another macro. For example, `.Op Fl O
1938 Ar file' produces `[-O file]'. To prevent a macro call and render the
1939 macro name literally, escape it by prepending a zero-width space, `\&'.
1940 For example, `Op \&Fl O' produces `[Fl O]'. If a macro is not callable
1941 but its name appears as an argument to another macro, it is interpreted
1942 as opaque text. For example, `.Fl Sh' produces `-Sh'.
1943
1944 The Parsed column indicates whether the macro may call other macros by
1945 receiving their names as arguments. If a macro is not parsed but the
1946 name of another macro appears as an argument, it is interpreted as opaque
1947 text.
1948
1949 The Scope column, if applicable, describes closure rules.
1950
1951 Block full-explicit
1952 Multi-line scope closed by an explicit closing macro. All macros
1953 contains bodies; only Bf and (optionally) Bl contain a head.
1954
1955 .Yo [-arg [parm...]] [head...]
1956 [body...]
1957 .Yc
1958
1959 Macro Callable Parsed Scope
1960 Bd No No closed by Ed
1961 Bf No No closed by Ef
1962 Bk No No closed by Ek
1963 Bl No No closed by El
1964 Ed No No opened by Bd
1965 Ef No No opened by Bf
1966 Ek No No opened by Bk
1967 El No No opened by Bl
1968
1969 Block full-implicit
1970 Multi-line scope closed by end-of-file or implicitly by another macro.
1971 All macros have bodies; some (It -bullet, -hyphen, -dash, -enum, -item)
1972 don't have heads; only one (It in Bl -column) has multiple heads.
1973
1974 .Yo [-arg [parm...]] [head... [Ta head...]]
1975 [body...]
1976
1977 Macro Callable Parsed Scope
1978 It No Yes closed by It, El
1979 Nd No No closed by Sh
1980 Nm No Yes closed by Nm, Sh, Ss
1981 Sh No Yes closed by Sh
1982 Ss No Yes closed by Sh, Ss
1983
1984 Note that the Nm macro is a Block full-implicit macro only when invoked
1985 as the first macro in a SYNOPSIS section line, else it is In-line.
1986
1987 Block partial-explicit
1988 Like block full-explicit, but also with single-line scope. Each has at
1989 least a body and, in limited circumstances, a head (Fo, Eo) and/or tail
1990 (Ec).
1991
1992 .Yo [-arg [parm...]] [head...]
1993 [body...]
1994 .Yc [tail...]
1995
1996 .Yo [-arg [parm...]] [head...] [body...] Yc [tail...]
1997
1998 Macro Callable Parsed Scope
1999 Ac Yes Yes opened by Ao
2000 Ao Yes Yes closed by Ac
2001 Bc Yes Yes closed by Bo
2002 Bo Yes Yes opened by Bc
2003 Brc Yes Yes opened by Bro
2004 Bro Yes Yes closed by Brc
2005 Dc Yes Yes opened by Do
2006 Do Yes Yes closed by Dc
2007 Ec Yes Yes opened by Eo
2008 Eo Yes Yes closed by Ec
2009 Fc Yes Yes opened by Fo
2010 Fo No No closed by Fc
2011 Oc Yes Yes closed by Oo
2012 Oo Yes Yes opened by Oc
2013 Pc Yes Yes closed by Po
2014 Po Yes Yes opened by Pc
2015 Qc Yes Yes opened by Oo
2016 Qo Yes Yes closed by Oc
2017 Re No No opened by Rs
2018 Rs No No closed by Re
2019 Sc Yes Yes opened by So
2020 So Yes Yes closed by Sc
2021 Xc Yes Yes opened by Xo
2022 Xo Yes Yes closed by Xc
2023
2024 Block partial-implicit
2025 Like block full-implicit, but with single-line scope closed by the end of
2026 the line.
2027
2028 .Yo [-arg [val...]] [body...] [res...]
2029
2030 Macro Callable Parsed
2031 Aq Yes Yes
2032 Bq Yes Yes
2033 Brq Yes Yes
2034 D1 No Yes
2035 Dl No Yes
2036 Dq Yes Yes
2037 En Yes Yes
2038 Op Yes Yes
2039 Pq Yes Yes
2040 Ql Yes Yes
2041 Qq Yes Yes
2042 Sq Yes Yes
2043 Vt Yes Yes
2044
2045 Note that the Vt macro is a Block partial-implicit only when invoked as
2046 the first macro in a SYNOPSIS section line, else it is In-line.
2047
2048 Special block macro
2049 The Ta macro can only be used below It in Bl -column lists. It delimits
2050 blocks representing table cells; these blocks have bodies, but no heads.
2051
2052 Macro Callable Parsed Scope
2053 Ta Yes Yes closed by Ta, It
2054
2055 In-line
2056 Closed by the end of the line, fixed argument lengths, and/or subsequent
2057 macros. In-line macros have only text children. If a number (or
2058 inequality) of arguments is (n), then the macro accepts an arbitrary
2059 number of arguments.
2060
2061 .Yo [-arg [val...]] [args...] [res...]
2062
2063 .Yo [-arg [val...]] [args...] Yc...
2064
2065 .Yo [-arg [val...]] arg0 arg1 argN
2066
2067 Macro Callable Parsed Arguments
2068 %A No No >0
2069 %B No No >0
2070 %C No No >0
2071 %D No No >0
2072 %I No No >0
2073 %J No No >0
2074 %N No No >0
2075 %O No No >0
2076 %P No No >0
2077 %Q No No >0
2078 %R No No >0
2079 %T No No >0
2080 %U No No >0
2081 %V No No >0
2082 Ad Yes Yes >0
2083 An Yes Yes >0
2084 Ap Yes Yes 0
2085 Ar Yes Yes n
2086 At Yes Yes 1
2087 Bsx Yes Yes n
2088 Bt No No 0
2089 Bx Yes Yes n
2090 Cd Yes Yes >0
2091 Cm Yes Yes >0
2092 Db No No 1
2093 Dd No No n
2094 Dt No No n
2095 Dv Yes Yes >0
2096 Dx Yes Yes n
2097 Em Yes Yes >0
2098 Er Yes Yes >0
2099 Es Yes Yes 2
2100 Ev Yes Yes >0
2101 Ex No No n
2102 Fa Yes Yes >0
2103 Fd No No >0
2104 Fl Yes Yes n
2105 Fn Yes Yes >0
2106 Fr Yes Yes >0
2107 Ft Yes Yes >0
2108 Fx Yes Yes n
2109 Hf No No n
2110 Ic Yes Yes >0
2111 In No No 1
2112 Lb No No 1
2113 Li Yes Yes >0
2114 Lk Yes Yes >0
2115 Lp No No 0
2116 Ms Yes Yes >0
2117 Mt Yes Yes >0
2118 Nm Yes Yes n
2119 No Yes Yes 0
2120 Ns Yes Yes 0
2121 Nx Yes Yes n
2122 Os No No n
2123 Ot Yes Yes >0
2124 Ox Yes Yes n
2125 Pa Yes Yes n
2126 Pf Yes Yes 1
2127 Pp No No 0
2128 Rv No No n
2129 Sm No No <2
2130 St No Yes 1
2131 Sx Yes Yes >0
2132 Sy Yes Yes >0
2133 Tn Yes Yes >0
2134 Ud No No 0
2135 Ux Yes Yes n
2136 Va Yes Yes n
2137 Vt Yes Yes >0
2138 Xr Yes Yes 2
2139
2140 Delimiters
2141 When a macro argument consists of one single input character considered
2142 as a delimiter, the argument gets special handling. This does not apply
2143 when delimiters appear in arguments containing more than one character.
2144 Consequently, to prevent special handling and just handle it like any
2145 other argument, a delimiter can be escaped by prepending a zero-width
2146 space (`\&'). In text lines, delimiters never need escaping, but may be
2147 used as normal punctuation.
2148
2149 For many macros, when the leading arguments are opening delimiters, these
2150 delimiters are put before the macro scope, and when the trailing
2151 arguments are closing delimiters, these delimiters are put after the
2152 macro scope. Spacing is suppressed after opening delimiters and before
2153 closing delimiters. For example,
2154
2155 .Aq ( [ word ] ) .
2156
2157 renders as:
2158
2159 ([<word>]).
2160
2161 Opening delimiters are:
2162
2163 ( left parenthesis
2164 [ left bracket
2165
2166 Closing delimiters are:
2167
2168 . period
2169 , comma
2170 : colon
2171 ; semicolon
2172 ) right parenthesis
2173 ] right bracket
2174 ? question mark
2175 ! exclamation mark
2176
2177 Note that even a period preceded by a backslash (`\.') gets this special
2178 handling; use `\&.' to prevent that.
2179
2180 Many in-line macros interrupt their scope when they encounter delimiters,
2181 and resume their scope when more arguments follow that are not
2182 delimiters. For example,
2183
2184 .Fl a ( b | c \*(Ba d ) e
2185
2186 renders as:
2187
2188 -a (-b | -c | -d) -e
2189
2190 This applies to both opening and closing delimiters, and also to the
2191 middle delimiter, which does not suppress spacing:
2192
2193 | vertical bar
2194
2195 As a special case, the predefined string \*(Ba is handled and rendered in
2196 the same way as a plain `|' character. Using this predefined string is
2197 not recommended in new manuals.
2198
2199 Font handling
2200 In mdoc documents, usage of semantic markup is recommended in order to
2201 have proper fonts automatically selected; only when no fitting semantic
2202 markup is available, consider falling back to Physical markup macros.
2203 Whenever any mdoc macro switches the mandoc_roff(5) font mode, it will
2204 automatically restore the previous font when exiting its scope. Manually
2205 switching the font using the mandoc_roff(5) `\f' font escape sequences is
2206 never required.
2207
2208 COMPATIBILITY
2209 This section provides an incomplete list of compatibility issues between
2210 mandoc and GNU troff ("groff").
2211
2212 The following problematic behaviour is found in groff:
2213
2214 - Dd with non-standard arguments behaves very strangely. When there
2215 are three arguments, they are printed verbatim. Any other number of
2216 arguments is replaced by the current date, but without any arguments
2217 the string "Epoch" is printed.
2218 - Lk only accepts a single link-name argument; the remainder is
2219 misformatted.
2220 - Pa does not format its arguments when used in the FILES section under
2221 certain list types.
2222 - Ta can only be called by other macros, but not at the beginning of a
2223 line.
2224 - %C is not implemented (up to and including groff-1.22.2).
2225 - `\f' (font face) and `\F' (font family face) Text Decoration escapes
2226 behave irregularly when specified within line-macro scopes.
2227 - Negative scaling units return to prior lines. Instead, mandoc
2228 truncates them to zero.
2229
2230 The following features are unimplemented in mandoc:
2231
2232 - Bd -file file is unsupported for security reasons.
2233 - Bd -filled does not adjust the right margin, but is an alias for Bd
2234 -ragged.
2235 - Bd -literal does not use a literal font, but is an alias for Bd
2236 -unfilled.
2237 - Bd -offset center and -offset right don't work. Groff does not
2238 implement centered and flush-right rendering either, but produces
2239 large indentations.
2240
2241 SEE ALSO
2242 man(1), mandoc(1), eqn(5), man(5), mandoc_char(5), mandoc_roff(5), tbl(5)
2243
2244 The web page extended documentation for the mdoc language:
2245 http://mandoc.bsd.lv/mdoc/ provides a few tutorial-style pages for
2246 beginners, an extensive style guide for advanced authors, and an
2247 alphabetic index helping to choose the best macros for various kinds of
2248 content.
2249
2250 HISTORY
2251 The mdoc language first appeared as a troff macro package in 4.4BSD. It
2252 was later significantly updated by Werner Lemberg and Ruslan Ermilov in
2253 groff-1.17. The standalone implementation that is part of the mandoc(1)
2254 utility written by Kristaps Dzonsons appeared in OpenBSD 4.6.
2255
2256 AUTHORS
2257 The mdoc reference was written by Kristaps Dzonsons <kristaps@bsd.lv>.
2258
2259 illumos July 28, 2018 illumos