1MDOC(7)              BSD Miscellaneous Information Manual              MDOC(7)
2

NAME

4     mdoc — semantic markup language for formatting manual pages
5

DESCRIPTION

7     The mdoc language supports authoring of manual pages for the man(1) util‐
8     ity by allowing semantic annotations of words, phrases, page sections and
9     complete manual pages.  Such annotations are used by formatting tools to
10     achieve a uniform presentation across all manuals written in mdoc, and to
11     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     roff(7) language; see the LANGUAGE SYNTAX and MACRO SYNTAX sections in
34     the roff(7) manual for details, in particular regarding comments, escape
35     sequences, whitespace, and quoting.  However, using roff(7) requests in
36     mdoc documents is discouraged; mandoc(1) supports some of them merely for
37     backward compatibility.
38

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 $Mdocdate$
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           .\" Not used in OpenBSD.
64           .Sh SYNOPSIS
65           .Nm progname
66           .Op Fl options
67           .Ar
68           .Sh DESCRIPTION
69           The
70           .Nm
71           utility processes files ...
72           .\" .Sh CONTEXT
73           .\" For section 9 functions only.
74           .\" .Sh IMPLEMENTATION NOTES
75           .\" Not used in OpenBSD.
76           .\" .Sh RETURN VALUES
77           .\" For sections 2, 3, and 9 function return values only.
78           .\" .Sh ENVIRONMENT
79           .\" For sections 1, 6, 7, and 8 only.
80           .\" .Sh FILES
81           .\" .Sh EXIT STATUS
82           .\" For sections 1, 6, and 8 only.
83           .\" .Sh EXAMPLES
84           .\" .Sh DIAGNOSTICS
85           .\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
86           .\" .Sh ERRORS
87           .\" For sections 2, 3, 4, and 9 errno settings only.
88           .\" .Sh SEE ALSO
89           .\" .Xr foobar 1
90           .\" .Sh STANDARDS
91           .\" .Sh HISTORY
92           .\" .Sh AUTHORS
93           .\" .Sh CAVEATS
94           .\" .Sh BUGS
95           .\" .Sh SECURITY CONSIDERATIONS
96           .\" Not used in OpenBSD.
97
98     The sections in an mdoc document are conventionally ordered as they
99     appear above.  Sections should be composed as follows:
100
101           NAME
102           The name(s) and a one line description of the documented material.
103           The syntax for this as follows:
104
105                 .Nm name0 ,
106                 .Nm name1 ,
107                 .Nm name2
108                 .Nd a one line description
109
110           Multiple ‘Nm’ names should be separated by commas.
111
112           The Nm macro(s) must precede the Nd macro.
113
114           See Nm and Nd.
115
116           LIBRARY
117           The name of the library containing the documented material, which
118           is assumed to be a function in a section 2, 3, or 9 manual.  The
119           syntax for this is as follows:
120
121                 .Lb libarm
122
123           See Lb.
124
125           SYNOPSIS
126           Documents the utility invocation syntax, function call syntax, or
127           device configuration.
128
129           For the first, utilities (sections 1, 6, and 8), this is generally
130           structured as follows:
131
132                 .Nm bar
133                 .Op Fl v
134                 .Op Fl o Ar file
135                 .Op Ar
136                 .Nm foo
137                 .Op Fl v
138                 .Op Fl o Ar file
139                 .Op Ar
140
141           Commands should be ordered alphabetically.
142
143           For the second, function calls (sections 2, 3, 9):
144
145                 .In header.h
146                 .Vt extern const char *global;
147                 .Ft "char *"
148                 .Fn foo "const char *src"
149                 .Ft "char *"
150                 .Fn bar "const char *src"
151
152           Ordering of In, Vt, Fn, and Fo macros should follow C header-file
153           conventions.
154
155           And for the third, configurations (section 4):
156
157                 .Cd "it* at isa? port 0x2e"
158                 .Cd "it* at isa? port 0x4e"
159
160           Manuals not in these sections generally don't need a SYNOPSIS.
161
162           Some macros are displayed differently in the SYNOPSIS section, par‐
163           ticularly Nm, Cd, Fd, Fn, Fo, In, Vt, and Ft.  All of these macros
164           are output on their own line.  If two such dissimilar macros are
165           pairwise invoked (except for Ft before Fo or Fn), they are sepa‐
166           rated by a vertical space, unless in the case of Fo, Fn, and Ft,
167           which are always separated by vertical space.
168
169           When text and macros following an Nm macro starting an input line
170           span multiple output lines, all output lines but the first will be
171           indented to align with the text immediately following the Nm macro,
172           up to the next Nm, Sh, or Ss macro or the end of an enclosing
173           block, whichever comes first.
174
175           DESCRIPTION
176           This begins with an expansion of the brief, one line description in
177           NAME:
178
179                 The
180                 .Nm
181                 utility does this, that, and the other.
182
183           It usually follows with a breakdown of the options (if documenting
184           a command), such as:
185
186                 The arguments are as follows:
187                 .Bl -tag -width Ds
188                 .It Fl v
189                 Print verbose information.
190                 .El
191
192           List the options in alphabetical order, uppercase before lowercase
193           for each letter and with no regard to whether an option takes an
194           argument.  Put digits in ascending order before all letter options.
195
196           Manuals not documenting a command won't include the above fragment.
197
198           Since the DESCRIPTION section usually contains most of the text of
199           a manual, longer manuals often use the Ss macro to form subsec‐
200           tions.  In very long manuals, the DESCRIPTION may be split into
201           multiple sections, each started by an Sh macro followed by a non-
202           standard section name, and each having several subsections, like in
203           the present mdoc manual.
204
205           CONTEXT
206           This section lists the contexts in which functions can be called in
207           section 9.  The contexts are autoconf, process, or interrupt.
208
209           IMPLEMENTATION NOTES
210           Implementation-specific notes should be kept here.  This is useful
211           when implementing standard functions that may have side effects or
212           notable algorithmic implications.
213
214           RETURN VALUES
215           This section documents the return values of functions in sections
216           2, 3, and 9.
217
218           See Rv.
219
220           ENVIRONMENT
221           Lists the environment variables used by the utility, and explains
222           the syntax and semantics of their values.  The environ(7) manual
223           provides examples of typical content and formatting.
224
225           See Ev.
226
227           FILES
228           Documents files used.  It's helpful to document both the file name
229           and a short description of how the file is used (created, modified,
230           etc.).
231
232           See Pa.
233
234           EXIT STATUS
235           This section documents the command exit status for section 1, 6,
236           and 8 utilities.  Historically, this information was described in
237           DIAGNOSTICS, a practise that is now discouraged.
238
239           See Ex.
240
241           EXAMPLES
242           Example usages.  This often contains snippets of well-formed, well-
243           tested invocations.  Make sure that examples work properly!
244
245           DIAGNOSTICS
246           Documents error messages.  In section 4 and 9 manuals, these are
247           usually messages printed by the kernel to the console and to the
248           kernel log.  In section 1, 6, 7, and 8, these are usually messages
249           printed by userland programs to the standard error output.
250
251           Historically, this section was used in place of EXIT STATUS for
252           manuals in sections 1, 6, and 8; however, this practise is discour‐
253           aged.
254
255           See Bl -diag.
256
257           ERRORS
258           Documents errno(2) settings in sections 2, 3, 4, and 9.
259
260           See Er.
261
262           SEE ALSO
263           References other manuals with related topics.  This section should
264           exist for most manuals.  Cross-references should conventionally be
265           ordered first by section, then alphabetically (ignoring case).
266
267           References to other documentation concerning the topic of the man‐
268           ual page, for example authoritative books or journal articles, may
269           also be provided in this section.
270
271           See Rs and Xr.
272
273           STANDARDS
274           References any standards implemented or used.  If not adhering to
275           any standards, the HISTORY section should be used instead.
276
277           See St.
278
279           HISTORY
280           A brief history of the subject, including where it was first imple‐
281           mented, and when it was ported to or reimplemented for the operat‐
282           ing system at hand.
283
284           AUTHORS
285           Credits to the person or persons who wrote the code and/or documen‐
286           tation.  Authors should generally be noted by both name and email
287           address.
288
289           See An.
290
291           CAVEATS
292           Common misuses and misunderstandings should be explained in this
293           section.
294
295           BUGS
296           Known bugs, limitations, and work-arounds should be described in
297           this section.
298
299           SECURITY CONSIDERATIONS
300           Documents any security precautions that operators should consider.
301

MACRO OVERVIEW

303     This overview is sorted such that macros of similar purpose are listed
304     together, to help find the best macro for any given purpose.  Deprecated
305     macros are not included in the overview, but can be found below in the
306     alphabetical MACRO REFERENCE.
307
308   Document preamble and NAME section macros
309     Dd               document date: $Mdocdate$ | month day, year
310     Dt               document title: TITLE section [arch]
311     Os               operating system version: [system [version]]
312     Nm               document name (one argument)
313     Nd               document description (one line)
314
315   Sections and cross references
316     Sh               section header (one line)
317     Ss               subsection header (one line)
318     Sx               internal cross reference to a section or subsection
319     Xr               cross reference to another manual page: name section
320     Pp               start a text paragraph (no arguments)
321
322   Displays and lists
323     Bd, Ed           display block: -type [-offset width] [-compact]
324     D1               indented display (one line)
325     Dl               indented literal display (one line)
326     Ql               in-line literal display: ‘text’
327     Bl, El           list block: -type [-width val] [-offset val] [-compact]
328     It               list item (syntax depends on -type)
329     Ta               table cell separator in Bl -column lists
330     Rs, %*, Re       bibliographic block (references)
331
332   Spacing control
333     Pf               prefix, no following horizontal space (one argument)
334     Ns               roman font, no preceding horizontal space (no arguments)
335     Ap               apostrophe without surrounding whitespace (no arguments)
336     Sm               switch horizontal spacing mode: [on | off]
337     Bk, Ek           keep block: -words
338
339   Semantic markup for command line utilities
340     Nm               start a SYNOPSIS block with the name of a utility
341     Fl               command line options (flags) (>=0 arguments)
342     Cm               command modifier (>0 arguments)
343     Ar               command arguments (>=0 arguments)
344     Op, Oo, Oc       optional syntax elements (enclosure)
345     Ic               internal or interactive command (>0 arguments)
346     Ev               environmental variable (>0 arguments)
347     Pa               file system path (>=0 arguments)
348
349   Semantic markup for function libraries
350     Lb               function library (one argument)
351     In               include file (one argument)
352     Fd               other preprocessor directive (>0 arguments)
353     Ft               function type (>0 arguments)
354     Fo, Fc           function block: funcname
355     Fn               function name: funcname [argument ...]
356     Fa               function argument (>0 arguments)
357     Vt               variable type (>0 arguments)
358     Va               variable name (>0 arguments)
359     Dv               defined variable or preprocessor constant (>0 arguments)
360     Er               error constant (>0 arguments)
361     Ev               environmental variable (>0 arguments)
362
363   Various semantic markup
364     An               author name (>0 arguments)
365     Lk               hyperlink: uri [display_name]
366     Mt               “mailto” hyperlink: localpart@domain
367     Cd               kernel configuration declaration (>0 arguments)
368     Ad               memory address (>0 arguments)
369     Ms               mathematical symbol (>0 arguments)
370
371   Physical markup
372     Em               italic font or underline (emphasis) (>0 arguments)
373     Sy               boldface font (symbolic) (>0 arguments)
374     No               return to roman font (normal) (>0 arguments)
375     Bf, Ef           font block: -type | Em | Li | Sy
376
377   Physical enclosures
378     Dq, Do, Dc       enclose in typographic double quotes: “text”
379     Qq, Qo, Qc       enclose in typewriter double quotes: "text"
380     Sq, So, Sc       enclose in single quotes: ‘text’
381     Pq, Po, Pc       enclose in parentheses: (text)
382     Bq, Bo, Bc       enclose in square brackets: [text]
383     Brq, Bro, Brc    enclose in curly braces: {text}
384     Aq, Ao, Ac       enclose in angle brackets: ⟨text⟩
385     Eo, Ec           generic enclosure
386
387   Text production
388     Ex -std          standard command exit values: [utility ...]
389     Rv -std          standard function return values: [function ...]
390     St               reference to a standards document (one argument)
391     At               AT&T UNIX
392     Bx               BSD
393     Bsx              BSD/OS
394     Nx               NetBSD
395     Fx               FreeBSD
396     Ox               OpenBSD
397     Dx               DragonFly
398

MACRO REFERENCE

400     This section is a canonical reference of all macros, arranged alphabeti‐
401     cally.  For the scoping of individual macros, see MACRO SYNTAX.
402
403     %A first_name ... last_name
404          Author name of an Rs block.  Multiple authors should each be
405          accorded their own %A line.  Author names should be ordered with
406          full or abbreviated forename(s) first, then full surname.
407
408     %B title
409          Book title of an Rs block.  This macro may also be used in a non-
410          bibliographic context when referring to book titles.
411
412     %C location
413          Publication city or location of an Rs block.
414
415     %D [month day,] year
416          Publication date of an Rs block.  Provide the full English name of
417          the month and all four digits of the year.
418
419     %I name
420          Publisher or issuer name of an Rs block.
421
422     %J name
423          Journal name of an Rs block.
424
425     %N number
426          Issue number (usually for journals) of an Rs block.
427
428     %O line
429          Optional information of an Rs block.
430
431     %P number
432          Book or journal page number of an Rs block.
433
434     %Q name
435          Institutional author (school, government, etc.) of an Rs block.
436          Multiple institutional authors should each be accorded their own %Q
437          line.
438
439     %R name
440          Technical report name of an Rs block.
441
442     %T title
443          Article title of an Rs block.  This macro may also be used in a non-
444          bibliographical context when referring to article titles.
445
446     %U protocol://path
447          URI of reference document.
448
449     %V number
450          Volume number of an Rs block.
451
452     Ac   Close an Ao block.  Does not have any tail arguments.
453
454     Ad address
455          Memory address.  Do not use this for postal addresses.
456
457          Examples:
458                .Ad [0,$]
459                .Ad 0x00000000
460
461     An -split | -nosplit | first_name ... last_name
462          Author name.  Can be used both for the authors of the program, func‐
463          tion, or driver documented in the manual, or for the authors of the
464          manual itself.  Requires either the name of an author or one of the
465          following arguments:
466
467                -split     Start a new output line before each subsequent
468                           invocation of An.
469                -nosplit   The opposite of -split.
470
471          The default is -nosplit.  The effect of selecting either of the
472          -split modes ends at the beginning of the AUTHORS section.  In the
473          AUTHORS section, the default is -nosplit for the first author list‐
474          ing and -split for all other author listings.
475
476          Examples:
477                .An -nosplit
478                .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
479
480     Ao block
481          Begin a block enclosed by angle brackets.  Does not have any head
482          arguments.  This macro is almost never useful.  See Aq for more
483          details.
484
485     Ap   Inserts an apostrophe without any surrounding whitespace.  This is
486          generally used as a grammatical device when referring to the verb
487          form of a function.
488
489          Examples:
490                .Fn execve Ap d
491
492     Aq line
493          Enclose the rest of the input line in angle brackets.  The only
494          important use case is for email addresses.  See Mt for an example.
495
496          Occasionally, it is used for names of characters and keys, for exam‐
497          ple:
498
499                Press the
500                .Aq escape
501                key to ...
502
503          For URIs, use Lk instead, and In for “#include” directives.  Never
504          wrap Ar in Aq.
505
506          Since Aq usually renders with non-ASCII characters in non-ASCII out‐
507          put modes, do not use it where the ASCII characters ‘<’ and ‘>’ are
508          required as syntax elements.  Instead, use these characters directly
509          in such cases, combining them with the macros Pf, Ns, or Eo as
510          needed.
511
512          See also Ao.
513
514     Ar [placeholder ...]
515          Command arguments.  If an argument is not provided, the string “file
516          ...” is used as a default.
517
518          Examples:
519                .Fl o Ar file
520                .Ar
521                .Ar arg1 , arg2 .
522
523          The arguments to the Ar macro are names and placeholders for command
524          arguments; for fixed strings to be passed verbatim as arguments, use
525          Fl or Cm.
526
527     At [version]
528          Formats an AT&T UNIX version.  Accepts one optional argument:
529
530                v[1-7] | 32v   A version of AT&T UNIX.
531                III            AT&T UNIX III.
532                V | V.[1-4]    A version of AT&T System V UNIX.
533
534          Note that these arguments do not begin with a hyphen.
535
536          Examples:
537                .At
538                .At III
539                .At V.1
540
541          See also Bsx, Bx, Dx, Fx, Nx, and Ox.
542
543     Bc   Close a Bo block.  Does not have any tail arguments.
544
545     Bd -type [-offset width] [-compact]
546          Begin a display block.  Display blocks are used to select a differ‐
547          ent indentation and justification than the one used by the surround‐
548          ing text.  They may contain both macro lines and text lines.  By
549          default, a display block is preceded by a vertical space.
550
551          The type must be one of the following:
552
553                -centered      Produce one output line from each input line,
554                               and center-justify each line.  Using this dis‐
555                               play type is not recommended; many mdoc imple‐
556                               mentations render it poorly.
557
558                -filled        Change the positions of line breaks to fill
559                               each line, and left- and right-justify the
560                               resulting block.
561
562                -literal       Produce one output line from each input line,
563                               and do not justify the block at all.  Preserve
564                               white space as it appears in the input.  Always
565                               use a constant-width font.  Use this for dis‐
566                               playing source code.
567
568                -ragged        Change the positions of line breaks to fill
569                               each line, and left-justify the resulting
570                               block.
571
572                -unfilled      The same as -literal, but using the same font
573                               as for normal text, which is a variable width
574                               font if supported by the output device.
575
576          The type must be provided first.  Additional arguments may follow:
577
578                -offset width  Indent the display by the width, which may be
579                               one of the following:
580
581                               One of the pre-defined strings indent, the
582                               width of a standard indentation (six constant
583                               width characters); indent-two, twice indent;
584                               left, which has no effect; right, which justi‐
585                               fies to the right margin; or center, which
586                               aligns around an imagined center axis.
587
588                               A macro invocation, which selects a predefined
589                               width associated with that macro.  The most
590                               popular is the imaginary macro Ds, which
591                               resolves to 6n.
592
593                               A scaling width as described in roff(7).
594
595                               An arbitrary string, which indents by the
596                               length of this string.
597
598                               When the argument is missing, -offset is
599                               ignored.
600
601                -compact       Do not assert vertical space before the dis‐
602                               play.
603
604          Examples:
605
606                .Bd -literal -offset indent -compact
607                   Hello       world.
608                .Ed
609
610          See also D1 and Dl.
611
612     Bf -emphasis | -literal | -symbolic | Em | Li | Sy
613          Change the font mode for a scoped block of text.  The -emphasis and
614          Em argument are equivalent, as are -symbolic and Sy, and -literal
615          and Li.  Without an argument, this macro does nothing.  The font
616          mode continues until broken by a new font mode in a nested scope or
617          Ef is encountered.
618
619          See also Li, Ef, Em, and Sy.
620
621     Bk -words
622          For each macro, keep its output together on the same output line,
623          until the end of the macro or the end of the input line is reached,
624          whichever comes first.  Line breaks in text lines are unaffected.
625
626          The -words argument is required; additional arguments are ignored.
627
628          The following example will not break within each Op macro line:
629
630                .Bk -words
631                .Op Fl f Ar flags
632                .Op Fl o Ar output
633                .Ek
634
635          Be careful in using over-long lines within a keep block!  Doing so
636          will clobber the right margin.
637
638     Bl -type [-width val] [-offset val] [-compact] [col ...]
639          Begin a list.  Lists consist of items specified using the It macro,
640          containing a head or a body or both.
641
642          The list type is mandatory and must be specified first.  The -width
643          and -offset arguments accept macro names as described for Bd
644          -offset, scaling widths as described in roff(7), or use the length
645          of the given string.  The -offset is a global indentation for the
646          whole list, affecting both item heads and bodies.  For those list
647          types supporting it, the -width argument requests an additional
648          indentation of item bodies, to be added to the -offset.  Unless the
649          -compact argument is specified, list entries are separated by verti‐
650          cal space.
651
652          A list must specify one of the following list types:
653
654                -bullet       No item heads can be specified, but a bullet
655                              will be printed at the head of each item.  Item
656                              bodies start on the same output line as the bul‐
657                              let and are indented according to the -width
658                              argument.
659
660                -column       A columnated list.  The -width argument has no
661                              effect; instead, the string length of each argu‐
662                              ment specifies the width of one column.  If the
663                              first line of the body of a -column list is not
664                              an It macro line, It contexts spanning one input
665                              line each are implied until an It macro line is
666                              encountered, at which point items start being
667                              interpreted as described in the It documenta‐
668                              tion.
669
670                -dash         Like -bullet, except that dashes are used in
671                              place of bullets.
672
673                -diag         Like -inset, except that item heads are not
674                              parsed for macro invocations.  Most often used
675                              in the DIAGNOSTICS section with error constants
676                              in the item heads.
677
678                -enum         A numbered list.  No item heads can be speci‐
679                              fied.  Formatted like -bullet, except that car‐
680                              dinal numbers are used in place of bullets,
681                              starting at 1.
682
683                -hang         Like -tag, except that the first lines of item
684                              bodies are not indented, but follow the item
685                              heads like in -inset lists.
686
687                -hyphen       Synonym for -dash.
688
689                -inset        Item bodies follow items heads on the same line,
690                              using normal inter-word spacing.  Bodies are not
691                              indented, and the -width argument is ignored.
692
693                -item         No item heads can be specified, and none are
694                              printed.  Bodies are not indented, and the
695                              -width argument is ignored.
696
697                -ohang        Item bodies start on the line following item
698                              heads and are not indented.  The -width argument
699                              is ignored.
700
701                -tag          Item bodies are indented according to the -width
702                              argument.  When an item head fits inside the
703                              indentation, the item body follows this head on
704                              the same output line.  Otherwise, the body
705                              starts on the output line following the head.
706
707          Lists may be nested within lists and displays.  Nesting of -column
708          and -enum lists may not be portable.
709
710          See also El and It.
711
712     Bo block
713          Begin a block enclosed by square brackets.  Does not have any head
714          arguments.
715
716          Examples:
717                .Bo 1 ,
718                .Dv BUFSIZ Bc
719
720          See also Bq.
721
722     Bq line
723          Encloses its arguments in square brackets.
724
725          Examples:
726                .Bq 1, Dv BUFSIZ
727
728          Remarks: this macro is sometimes abused to emulate optional argu‐
729          ments for commands; the correct macros to use for this purpose are
730          Op, Oo, and Oc.
731
732          See also Bo.
733
734     Brc  Close a Bro block.  Does not have any tail arguments.
735
736     Bro block
737          Begin a block enclosed by curly braces.  Does not have any head
738          arguments.
739
740          Examples:
741                .Bro 1 , ... ,
742                .Va n Brc
743
744          See also Brq.
745
746     Brq line
747          Encloses its arguments in curly braces.
748
749          Examples:
750                .Brq 1, ..., Va n
751
752          See also Bro.
753
754     Bsx [version]
755          Format the BSD/OS version provided as an argument, or a default
756          value if no argument is provided.
757
758          Examples:
759                .Bsx 1.0
760                .Bsx
761
762          See also At, Bx, Dx, Fx, Nx, and Ox.
763
764     Bt   Supported only for compatibility, do not use this in new manuals.
765          Prints “is currently in beta test.”
766
767     Bx [version [variant]]
768          Format the BSD version provided as an argument, or a default value
769          if no argument is provided.
770
771          Examples:
772                .Bx 4.3 Tahoe
773                .Bx 4.4
774                .Bx
775
776          See also At, Bsx, Dx, Fx, Nx, and Ox.
777
778     Cd line
779          Kernel configuration declaration.  This denotes strings accepted by
780          config(8).  It is most often used in section 4 manual pages.
781
782          Examples:
783                .Cd device le0 at scode?
784
785          Remarks: this macro is commonly abused by using quoted literals to
786          retain whitespace and align consecutive Cd declarations.  This prac‐
787          tise is discouraged.
788
789     Cm keyword ...
790          Command modifiers.  Typically used for fixed strings passed as argu‐
791          ments, unless Fl is more appropriate.  Also useful when specifying
792          configuration options or keys.
793
794          Examples:
795                .Nm mt Fl f Ar device Cm rewind
796                .Nm ps Fl o Cm pid , Ns Cm command
797                .Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2
798                .Cm IdentityFile Pa ~/.ssh/id_rsa
799                .Cm LogLevel Dv DEBUG
800
801     D1 line
802          One-line indented display.  This is formatted by the default rules
803          and is useful for simple indented statements.  It is followed by a
804          newline.
805
806          Examples:
807                .D1 Fl abcdefgh
808
809          See also Bd and Dl.
810
811     Db   This macro is obsolete.  No replacement is needed.  It is ignored by
812          mandoc(1) and groff including its arguments.  It was formerly used
813          to toggle a debugging mode.
814
815     Dc   Close a Do block.  Does not have any tail arguments.
816
817     Dd $Mdocdate$ | month day, year
818          Document date for display in the page footer.  This is the mandatory
819          first macro of any mdoc manual.
820
821          The month is the full English month name, the day is an integer num‐
822          ber, and the year is the full four-digit year.
823
824          Other arguments are not portable; the mandoc(1) utility handles them
825          as follows:
826             -   To have the date automatically filled in by the OpenBSD ver‐
827                 sion of cvs(1), the special string “$Mdocdate$” can be given
828                 as an argument.
829             -   The traditional, purely numeric man(7) format yearmonthday
830                 is accepted, too.
831             -   If a date string cannot be parsed, it is used verbatim.
832             -   If no date string is given, the current date is used.
833
834          Examples:
835                .Dd $Mdocdate$
836                .Dd $Mdocdate: July 2 2018$
837                .Dd July 2, 2018
838
839          See also Dt and Os.
840
841     Dl line
842          One-line indented display.  This is formatted as literal text and is
843          useful for commands and invocations.  It is followed by a newline.
844
845          Examples:
846                .Dl % mandoc mdoc.7 \(ba less
847
848          See also Ql, Bd -literal, and D1.
849
850     Do block
851          Begin a block enclosed by double quotes.  Does not have any head
852          arguments.
853
854          Examples:
855                .Do
856                April is the cruellest month
857                .Dc
858                \(em T.S. Eliot
859
860          See also Dq.
861
862     Dq line
863          Encloses its arguments in “typographic” double-quotes.
864
865          Examples:
866                .Dq April is the cruellest month
867                \(em T.S. Eliot
868
869          See also Qq, Sq, and Do.
870
871     Dt TITLE section [arch]
872          Document title for display in the page header.  This is the manda‐
873          tory second macro of any mdoc file.
874
875          Its arguments are as follows:
876
877            TITLE    The document's title (name), defaulting to “UNTITLED” if
878                     unspecified.  To achieve a uniform appearance of page
879                     header lines, it should by convention be all caps.
880
881            section  The manual section.  This may be one of 1 (General
882                     Commands), 2 (System Calls), 3 (Library Functions), 3p
883                     (Perl Library), 4 (Device Drivers), 5 (File Formats), 6
884                     (Games), 7 (Miscellaneous Information), 8 (System
885                     Manager's Manual), or 9 (Kernel Developer's Manual).  It
886                     should correspond to the manual's filename suffix and
887                     defaults to the empty string if unspecified.
888
889            arch     This specifies the machine architecture a manual page
890                     applies to, where relevant, for example alpha, amd64,
891                     i386, or sparc64.  The list of valid architectures varies
892                     by operating system.
893
894          Examples:
895                .Dt FOO 1
896                .Dt FOO 9 i386
897
898          See also Dd and Os.
899
900     Dv identifier ...
901          Defined variables such as preprocessor constants, constant symbols,
902          enumeration values, and so on.
903
904          Examples:
905                .Dv NULL
906                .Dv BUFSIZ
907                .Dv STDOUT_FILENO
908
909          See also Er and Ev for special-purpose constants, Va for variable
910          symbols, and Fd for listing preprocessor variable definitions in the
911          SYNOPSIS.
912
913     Dx [version]
914          Format the DragonFly version provided as an argument, or a default
915          value if no argument is provided.
916
917          Examples:
918                .Dx 2.4.1
919                .Dx
920
921          See also At, Bsx, Bx, Fx, Nx, and Ox.
922
923     Ec [closing_delimiter]
924          Close a scope started by Eo.
925
926          The closing_delimiter argument is used as the enclosure tail, for
927          example, specifying \(rq will emulate Dc.
928
929     Ed   End a display context started by Bd.
930
931     Ef   End a font mode context started by Bf.
932
933     Ek   End a keep context started by Bk.
934
935     El   End a list context started by Bl.  See also It.
936
937     Em word ...
938          Request an italic font.  If the output device does not provide that,
939          underline.
940
941          This is most often used for stress emphasis (not to be confused with
942          importance, see Sy).  In the rare cases where none of the semantic
943          markup macros fit, it can also be used for technical terms and
944          placeholders, except that for syntax elements, Sy and Ar are pre‐
945          ferred, respectively.
946
947          Examples:
948                Selected lines are those
949                .Em not
950                matching any of the specified patterns.
951                Some of the functions use a
952                .Em hold space
953                to save the pattern space for subsequent retrieval.
954
955          See also No, Ql, and Sy.
956
957     En word ...
958          This macro is obsolete.  Use Eo or any of the other enclosure
959          macros.
960
961          It encloses its argument in the delimiters specified by the last Es
962          macro.
963
964     Eo [opening_delimiter]
965          An arbitrary enclosure.  The opening_delimiter argument is used as
966          the enclosure head, for example, specifying \(lq will emulate Do.
967
968     Er identifier ...
969          Error constants for definitions of the errno libc global variable.
970          This is most often used in section 2 and 3 manual pages.
971
972          Examples:
973                .Er EPERM
974                .Er ENOENT
975
976          See also Dv for general constants.
977
978     Es opening_delimiter closing_delimiter
979          This macro is obsolete.  Use Eo or any of the other enclosure
980          macros.
981
982          It takes two arguments, defining the delimiters to be used by subse‐
983          quent En macros.
984
985     Ev identifier ...
986          Environmental variables such as those specified in environ(7).
987
988          Examples:
989                .Ev DISPLAY
990                .Ev PATH
991
992          See also Dv for general constants.
993
994     Ex -std [utility ...]
995          Insert a standard sentence regarding command exit values of 0 on
996          success and >0 on failure.  This is most often used in section 1, 6,
997          and 8 manual pages.
998
999          If utility is not specified, the document's name set by Nm is used.
1000          Multiple utility arguments are treated as separate utilities.
1001
1002          See also Rv.
1003
1004     Fa argument ...
1005          Function argument or parameter.  Each argument may be a name and a
1006          type (recommended for the SYNOPSIS section), a name alone (for func‐
1007          tion invocations), or a type alone (for function prototypes).  If
1008          both a type and a name are given or if the type consists of multiple
1009          words, all words belonging to the same function argument have to be
1010          given in a single argument to the Fa macro.
1011
1012          This macro is also used to specify the field name of a structure.
1013
1014          Most often, the Fa macro is used in the SYNOPSIS within Fo blocks
1015          when documenting multi-line function prototypes.  If invoked with
1016          multiple arguments, the arguments are separated by a comma.  Fur‐
1017          thermore, if the following macro is another Fa, the last argument
1018          will also have a trailing comma.
1019
1020          Examples:
1021                .Fa "const char *p"
1022                .Fa "int a" "int b" "int c"
1023                .Fa "char *" size_t
1024
1025          See also Fo.
1026
1027     Fc   End a function context started by Fo.
1028
1029     Fd #directive [argument ...]
1030          Preprocessor directive, in particular for listing it in the
1031          SYNOPSIS.  Historically, it was also used to document include files.
1032          The latter usage has been deprecated in favour of In.
1033
1034          Examples:
1035                .Fd #define sa_handler __sigaction_u.__sa_handler
1036                .Fd #define SIO_MAXNFDS
1037                .Fd #ifdef FS_DEBUG
1038                .Ft void
1039                .Fn dbg_open "const char *"
1040                .Fd #endif
1041
1042          See also MANUAL STRUCTURE, In, and Dv.
1043
1044     Fl [word ...]
1045          Command-line flag or option.  Used when listing arguments to com‐
1046          mand-line utilities.  Prints a fixed-width hyphen ‘-’ directly fol‐
1047          lowed by each argument.  If no arguments are provided, a hyphen is
1048          printed followed by a space.  If the argument is a macro, a hyphen
1049          is prefixed to the subsequent macro output.
1050
1051          Examples:
1052                .Fl R Op Fl H | L | P
1053                .Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux
1054                .Fl type Cm d Fl name Pa CVS
1055                .Fl Ar signal_number
1056                .Fl o Fl
1057
1058          See also Cm.
1059
1060     Fn funcname [argument ...]
1061          A function name.
1062
1063          Function arguments are surrounded in parenthesis and are delimited
1064          by commas.  If no arguments are specified, blank parenthesis are
1065          output.  In the SYNOPSIS section, this macro starts a new output
1066          line, and a blank line is automatically inserted between function
1067          definitions.
1068
1069          Examples:
1070                .Fn "int funcname" "int arg0" "int arg1"
1071                .Fn funcname "int arg0"
1072                .Fn funcname arg0
1073
1074                .Ft functype
1075                .Fn funcname
1076
1077          When referring to a function documented in another manual page, use
1078          Xr instead.  See also MANUAL STRUCTURE, Fo, and Ft.
1079
1080     Fo funcname
1081          Begin a function block.  This is a multi-line version of Fn.
1082
1083          Invocations usually occur in the following context:
1084
1085                .Ft functype
1086                .Fo funcname
1087                .Fa "argtype argname"
1088                ...
1089                .Fc
1090
1091          A Fo scope is closed by Fc.
1092
1093          See also MANUAL STRUCTURE, Fa, Fc, and Ft.
1094
1095     Fr number
1096          This macro is obsolete.  No replacement markup is needed.
1097
1098          It was used to show numerical function return values in an italic
1099          font.
1100
1101     Ft functype
1102          A function type.
1103
1104          In the SYNOPSIS section, a new output line is started after this
1105          macro.
1106
1107          Examples:
1108                .Ft int
1109                .Ft functype
1110                .Fn funcname
1111
1112          See also MANUAL STRUCTURE, Fn, and Fo.
1113
1114     Fx [version]
1115          Format the FreeBSD version provided as an argument, or a default
1116          value if no argument is provided.
1117
1118          Examples:
1119                .Fx 7.1
1120                .Fx
1121
1122          See also At, Bsx, Bx, Dx, Nx, and Ox.
1123
1124     Hf filename
1125          This macro is not implemented in mandoc(1).  It was used to include
1126          the contents of a (header) file literally.
1127
1128     Ic keyword ...
1129          Designate an internal or interactive command.  This is similar to Cm
1130          but used for instructions rather than values.
1131
1132          Examples:
1133                .Ic :wq
1134                .Ic hash
1135                .Ic alias
1136
1137          Note that using Ql, Dl, or Bd -literal is preferred for displaying
1138          code samples; the Ic macro is used when referring to an individual
1139          command name.
1140
1141     In filename
1142          The name of an include file.  This macro is most often used in sec‐
1143          tion 2, 3, and 9 manual pages.
1144
1145          When invoked as the first macro on an input line in the SYNOPSIS
1146          section, the argument is displayed in angle brackets and preceded by
1147          "#include", and a blank line is inserted in front if there is a pre‐
1148          ceding function declaration.  In other sections, it only encloses
1149          its argument in angle brackets and causes no line break.
1150
1151          Examples:
1152                .In sys/types.h
1153
1154          See also MANUAL STRUCTURE.
1155
1156     It [head]
1157          A list item.  The syntax of this macro depends on the list type.
1158
1159          Lists of type -hang, -ohang, -inset, and -diag have the following
1160          syntax:
1161
1162                .It args
1163
1164          Lists of type -bullet, -dash, -enum, -hyphen and -item have the fol‐
1165          lowing syntax:
1166
1167                .It
1168
1169          with subsequent lines interpreted within the scope of the It until
1170          either a closing El or another It.
1171
1172          The -tag list has the following syntax:
1173
1174                .It [args]
1175
1176          Subsequent lines are interpreted as with -bullet and family.  The
1177          line arguments correspond to the list's left-hand side; body argu‐
1178          ments correspond to the list's contents.
1179
1180          The -column list is the most complicated.  Its syntax is as follows:
1181
1182                .It cell [Ta cell ...]
1183                .It cell [<TAB> cell ...]
1184
1185          The arguments consist of one or more lines of text and macros repre‐
1186          senting a complete table line.  Cells within the line are delimited
1187          by the special Ta block macro or by literal tab characters.
1188
1189          Using literal tabs is strongly discouraged because they are very
1190          hard to use correctly and mdoc code using them is very hard to read.
1191          In particular, a blank character is syntactically significant before
1192          and after the literal tab character.  If a word precedes or follows
1193          the tab without an intervening blank, that word is never interpreted
1194          as a macro call, but always output literally.
1195
1196          The tab cell delimiter may only be used within the It line itself;
1197          on following lines, only the Ta macro can be used to delimit cells,
1198          and portability requires that Ta is called by other macros: some
1199          parsers do not recognize it when it appears as the first macro on a
1200          line.
1201
1202          Note that quoted strings may span tab-delimited cells on an It line.
1203          For example,
1204
1205                .It "col1 , <TAB> col2 ," ;
1206
1207          will preserve the whitespace before both commas, but not the white‐
1208          space before the semicolon.
1209
1210          See also Bl.
1211
1212     Lb libname
1213          Specify a library.
1214
1215          The name parameter may be a system library, such as z or pam, in
1216          which case a small library description is printed next to the linker
1217          invocation; or a custom library, in which case the library name is
1218          printed in quotes.  This is most commonly used in the SYNOPSIS sec‐
1219          tion as described in MANUAL STRUCTURE.
1220
1221          Examples:
1222                .Lb libz
1223                .Lb libmandoc
1224
1225     Li word ...
1226          Request a typewriter (literal) font.  Deprecated because on terminal
1227          output devices, this is usually indistinguishable from normal text.
1228          For literal displays, use Ql (in-line), Dl (single line), or Bd
1229          -literal (multi-line) instead.
1230
1231     Lk uri [display_name]
1232          Format a hyperlink.
1233
1234          Examples:
1235                .Lk http://bsd.lv "The BSD.lv Project"
1236                .Lk http://bsd.lv
1237
1238          See also Mt.
1239
1240     Lp   Deprecated synonym for Pp.
1241
1242     Ms name
1243          Display a mathematical symbol.
1244
1245          Examples:
1246                .Ms sigma
1247                .Ms aleph
1248
1249     Mt localpart@domain
1250          Format a “mailto:” hyperlink.
1251
1252          Examples:
1253                .Mt discuss@manpages.bsd.lv
1254                .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1255
1256     Nd line
1257          A one line description of the manual's content.  This is the manda‐
1258          tory last macro of the NAME section and not appropriate for other
1259          sections.
1260
1261          Examples:
1262                .Nd mdoc language reference
1263                .Nd format and display UNIX manuals
1264
1265          The Nd macro technically accepts child macros and terminates with a
1266          subsequent Sh invocation.  Do not assume this behaviour: some
1267          whatis(1) database generators are not smart enough to parse more
1268          than the line arguments and will display macros verbatim.
1269
1270          See also Nm.
1271
1272     Nm [name]
1273          The name of the manual page, or — in particular in section 1, 6, and
1274          8 pages — of an additional command or feature documented in the man‐
1275          ual page.  When first invoked, the Nm macro expects a single argu‐
1276          ment, the name of the manual page.  Usually, the first invocation
1277          happens in the NAME section of the page.  The specified name will be
1278          remembered and used whenever the macro is called again without argu‐
1279          ments later in the page.  The Nm macro uses Block full-implicit
1280          semantics when invoked as the first macro on an input line in the
1281          SYNOPSIS section; otherwise, it uses ordinary In-line semantics.
1282
1283          Examples:
1284
1285                .Sh SYNOPSIS
1286                .Nm cat
1287                .Op Fl benstuv
1288                .Op Ar
1289
1290          In the SYNOPSIS of section 2, 3 and 9 manual pages, use the Fn macro
1291          rather than Nm to mark up the name of the manual page.
1292
1293     No word ...
1294          Normal text.  Closes the scope of any preceding in-line macro.  When
1295          used after physical formatting macros like Em or Sy, switches back
1296          to the standard font face and weight.  Can also be used to embed
1297          plain text strings in macro lines using semantic annotation macros.
1298
1299          Examples:
1300                .Em italic , Sy bold , No and roman
1301
1302                .Sm off
1303                .Cm :C No / Ar pattern No / Ar replacement No /
1304                .Sm on
1305
1306          See also Em, Ql, and Sy.
1307
1308     Ns   Suppress a space between the output of the preceding macro and the
1309          following text or macro.  Following invocation, input is interpreted
1310          as normal text just like after an No macro.
1311
1312          This has no effect when invoked at the start of a macro line.
1313
1314          Examples:
1315                .Ar name Ns = Ns Ar value
1316                .Cm :M Ns Ar pattern
1317                .Fl o Ns Ar output
1318
1319          See also No and Sm.
1320
1321     Nx [version]
1322          Format the NetBSD version provided as an argument, or a default
1323          value if no argument is provided.
1324
1325          Examples:
1326                .Nx 5.01
1327                .Nx
1328
1329          See also At, Bsx, Bx, Dx, Fx, and Ox.
1330
1331     Oc   Close multi-line Oo context.
1332
1333     Oo block
1334          Multi-line version of Op.
1335
1336          Examples:
1337                .Oo
1338                .Op Fl flag Ns Ar value
1339                .Oc
1340
1341     Op line
1342          Optional part of a command line.  Prints the argument(s) in brack‐
1343          ets.  This is most often used in the SYNOPSIS section of section 1
1344          and 8 manual pages.
1345
1346          Examples:
1347                .Op Fl a Ar b
1348                .Op Ar a | b
1349
1350          See also Oo.
1351
1352     Os [system [version]]
1353          Operating system version for display in the page footer.  This is
1354          the mandatory third macro of any mdoc file.
1355
1356          The optional system parameter specifies the relevant operating sys‐
1357          tem or environment.  It is suggested to leave it unspecified, in
1358          which case mandoc(1) uses its -Ios argument or, if that isn't speci‐
1359          fied either, sysname and release as returned by uname(3).
1360
1361          Examples:
1362                .Os
1363                .Os KTH/CSC/TCS
1364                .Os BSD 4.3
1365
1366          See also Dd and Dt.
1367
1368     Ot functype
1369          This macro is obsolete.  Use Ft instead; with mandoc(1), both have
1370          the same effect.
1371
1372          Historical mdoc packages described it as “old function type
1373          (FORTRAN)”.
1374
1375     Ox [version]
1376          Format the OpenBSD version provided as an argument, or a default
1377          value if no argument is provided.
1378
1379          Examples:
1380                .Ox 4.5
1381                .Ox
1382
1383          See also At, Bsx, Bx, Dx, Fx, and Nx.
1384
1385     Pa name ...
1386          An absolute or relative file system path, or a file or directory
1387          name.  If an argument is not provided, the character ‘~’ is used as
1388          a default.
1389
1390          Examples:
1391                .Pa /usr/bin/mandoc
1392                .Pa /usr/share/man/man7/mdoc.7
1393
1394          See also Lk.
1395
1396     Pc   Close parenthesised context opened by Po.
1397
1398     Pf prefix macro [argument ...]
1399          Removes the space between its argument and the following macro.  It
1400          is equivalent to:
1401
1402                No \&prefix Ns macro [argument ...]
1403
1404          The prefix argument is not parsed for macro names or delimiters, but
1405          used verbatim as if it were escaped.
1406
1407          Examples:
1408                .Pf $ Ar variable_name
1409                .Pf . Ar macro_name
1410                .Pf 0x Ar hex_digits
1411
1412          See also Ns and Sm.
1413
1414     Po block
1415          Multi-line version of Pq.
1416
1417     Pp   Break a paragraph.  This will assert vertical space between prior
1418          and subsequent macros and/or text.
1419
1420          Paragraph breaks are not needed before or after Sh or Ss macros or
1421          before displays (Bd line) or lists (Bl) unless the -compact flag is
1422          given.
1423
1424     Pq line
1425          Parenthesised enclosure.
1426
1427          See also Po.
1428
1429     Qc   Close quoted context opened by Qo.
1430
1431     Ql line
1432          In-line literal display.  This can be used for complete command
1433          invocations and for multi-word code examples when an indented dis‐
1434          play is not desired.
1435
1436          See also Dl and Bd -literal.
1437
1438     Qo block
1439          Multi-line version of Qq.
1440
1441     Qq line
1442          Encloses its arguments in "typewriter" double-quotes.  Consider
1443          using Dq.
1444
1445          See also Dq, Sq, and Qo.
1446
1447     Re   Close an Rs block.  Does not have any tail arguments.
1448
1449     Rs   Begin a bibliographic (“reference”) block.  Does not have any head
1450          arguments.  The block macro may only contain %A, %B, %C, %D, %I, %J,
1451          %N, %O, %P, %Q, %R, %T, %U, and %V child macros (at least one must
1452          be specified).
1453
1454          Examples:
1455                .Rs
1456                .%A J. E. Hopcroft
1457                .%A J. D. Ullman
1458                .%B Introduction to Automata Theory, Languages, and Computation
1459                .%I Addison-Wesley
1460                .%C Reading, Massachusetts
1461                .%D 1979
1462                .Re
1463
1464          If an Rs block is used within a SEE ALSO section, a vertical space
1465          is asserted before the rendered output, else the block continues on
1466          the current line.
1467
1468     Rv -std [function ...]
1469          Insert a standard sentence regarding a function call's return value
1470          of 0 on success and -1 on error, with the errno libc global variable
1471          set on error.
1472
1473          If function is not specified, the document's name set by Nm is used.
1474          Multiple function arguments are treated as separate functions.
1475
1476          See also Ex.
1477
1478     Sc   Close single-quoted context opened by So.
1479
1480     Sh TITLE LINE
1481          Begin a new section.  For a list of conventional manual sections,
1482          see MANUAL STRUCTURE.  These sections should be used unless it's
1483          absolutely necessary that custom sections be used.
1484
1485          Section names should be unique so that they may be keyed by Sx.
1486          Although this macro is parsed, it should not consist of child node
1487          or it may not be linked with Sx.
1488
1489          See also Pp, Ss, and Sx.
1490
1491     Sm [on | off]
1492          Switches the spacing mode for output generated from macros.
1493
1494          By default, spacing is on.  When switched off, no white space is
1495          inserted between macro arguments and between the output generated
1496          from adjacent macros, but text lines still get normal spacing
1497          between words and sentences.
1498
1499          When called without an argument, the Sm macro toggles the spacing
1500          mode.  Using this is not recommended because it makes the code
1501          harder to read.
1502
1503     So block
1504          Multi-line version of Sq.
1505
1506     Sq line
1507          Encloses its arguments in ‘typewriter’ single-quotes.
1508
1509          See also Dq, Qq, and So.
1510
1511     Ss Title line
1512          Begin a new subsection.  Unlike with Sh, there is no convention for
1513          the naming of subsections.  Except DESCRIPTION, the conventional
1514          sections described in MANUAL STRUCTURE rarely have subsections.
1515
1516          Sub-section names should be unique so that they may be keyed by Sx.
1517          Although this macro is parsed, it should not consist of child node
1518          or it may not be linked with Sx.
1519
1520          See also Pp, Sh, and Sx.
1521
1522     St -abbreviation
1523          Replace an abbreviation for a standard with the full form.  The fol‐
1524          lowing standards are recognised.  Where multiple lines are given
1525          without a blank line in between, they all refer to the same stan‐
1526          dard, and using the first form is recommended.
1527
1528          C language standards
1529
1530             -ansiC          ANSI X3.159-1989 (“ANSI C89”)
1531             -ansiC-89       ANSI X3.159-1989 (“ANSI C89”)
1532             -isoC           ISO/IEC 9899:1990 (“ISO C90”)
1533             -isoC-90        ISO/IEC 9899:1990 (“ISO C90”)
1534                             The original C standard.
1535
1536             -isoC-amd1      ISO/IEC 9899/AMD1:1995 (“ISO C90, Amendment 1”)
1537
1538             -isoC-tcor1     ISO/IEC 9899/TCOR1:1994 (“ISO C90, Technical
1539                             Corrigendum 1”)
1540
1541             -isoC-tcor2     ISO/IEC 9899/TCOR2:1995 (“ISO C90, Technical
1542                             Corrigendum 2”)
1543
1544             -isoC-99        ISO/IEC 9899:1999 (“ISO C99”)
1545                             The second major version of the C language stan‐
1546                             dard.
1547
1548             -isoC-2011      ISO/IEC 9899:2011 (“ISO C11”)
1549                             The third major version of the C language stan‐
1550                             dard.
1551
1552          POSIX.1 before the Single UNIX Specification
1553
1554             -p1003.1-88     IEEE Std 1003.1-1988 (“POSIX.1”)
1555             -p1003.1        IEEE Std 1003.1 (“POSIX.1”)
1556                             The original POSIX standard, based on ANSI C.
1557
1558             -p1003.1-90     ISO/IEC 9945-1:1990 (“POSIX.1”)
1559             -iso9945-1-90   ISO/IEC 9945-1:1990 (“POSIX.1”)
1560                             The first update of POSIX.1.
1561
1562             -p1003.1b-93    IEEE Std 1003.1b-1993 (“POSIX.1”)
1563             -p1003.1b       IEEE Std 1003.1b (“POSIX.1”)
1564                             Real-time extensions.
1565
1566             -p1003.1c-95    IEEE Std 1003.1c-1995 (“POSIX.1”)
1567                             POSIX thread interfaces.
1568
1569             -p1003.1i-95    IEEE Std 1003.1i-1995 (“POSIX.1”)
1570                             Technical Corrigendum.
1571
1572             -p1003.1-96     ISO/IEC 9945-1:1996 (“POSIX.1”)
1573             -iso9945-1-96   ISO/IEC 9945-1:1996 (“POSIX.1”)
1574                             Includes POSIX.1-1990, 1b, 1c, and 1i.
1575
1576          X/Open Portability Guide version 4 and related standards
1577
1578             -xpg3           X/Open Portability Guide Issue 3 (“XPG3”)
1579                             An XPG4 precursor, published in 1989.
1580
1581             -p1003.2        IEEE Std 1003.2 (“POSIX.2”)
1582             -p1003.2-92     IEEE Std 1003.2-1992 (“POSIX.2”)
1583             -iso9945-2-93   ISO/IEC 9945-2:1993 (“POSIX.2”)
1584                             An XCU4 precursor.
1585
1586             -p1003.2a-92    IEEE Std 1003.2a-1992 (“POSIX.2”)
1587                             Updates to POSIX.2.
1588
1589             -xpg4           X/Open Portability Guide Issue 4 (“XPG4”)
1590                             Based on POSIX.1 and POSIX.2, published in 1992.
1591
1592          Single UNIX Specification version 1 and related standards
1593
1594             -susv1
1595             -xpg4.2         X/Open Portability Guide Issue 4, Version 2
1596                             (“XPG4.2”)
1597                             This standard was published in 1994.  It was used
1598                             as the basis for UNIX 95 certification.  The fol‐
1599                             lowing three refer to parts of it.
1600
1601             -xsh4.2
1602
1603             -xcurses4.2     X/Open Curses Issue 4, Version 2 (“XCURSES4.2”)
1604
1605             -p1003.1g-2000  IEEE Std 1003.1g-2000 (“POSIX.1”)
1606                             Networking APIs, including sockets.
1607
1608             -svid4          System V Interface Definition, Fourth Edition
1609                             (“SVID4”),
1610                             Published in 1995.
1611
1612          Single UNIX Specification version 2 and related standards
1613
1614             -susv2          Version 2 of the Single UNIX Specification
1615                             (“SUSv2”) This Standard was published in 1997 and
1616                             is also called X/Open Portability Guide version
1617                             5.  It was used as the basis for UNIX 98 certifi‐
1618                             cation.  The following refer to parts of it.
1619
1620             -xbd5           X/Open Base Definitions Issue 5 (“XBD5”)
1621
1622             -xsh5           X/Open System Interfaces and Headers Issue 5
1623                             (“XSH5”)
1624
1625             -xcu5           X/Open Commands and Utilities Issue 5 (“XCU5”)
1626
1627             -xns5           X/Open Networking Services Issue 5 (“XNS5”)
1628             -xns5.2         X/Open Networking Services Issue 5.2 (“XNS5.2”)
1629
1630          Single UNIX Specification version 3
1631
1632             -p1003.1-2001  IEEE Std 1003.1-2001 (“POSIX.1”)
1633             -susv3         Version 3 of the Single UNIX Specification
1634                            (“SUSv3”)
1635                            This standard is based on C99, SUSv2,
1636                            POSIX.1-1996, 1d, and 1j.  It is also called
1637                            X/Open Portability Guide version 6.  It is used as
1638                            the basis for UNIX 03 certification.
1639
1640             -p1003.1-2004  IEEE Std 1003.1-2004 (“POSIX.1”)
1641                            The second and last Technical Corrigendum.
1642
1643          Single UNIX Specification version 4
1644
1645             -p1003.1-2008   IEEE Std 1003.1-2008 (“POSIX.1”)
1646             -susv4
1647                             This standard is also called X/Open Portability
1648                             Guide version 7.
1649
1650          Other standards
1651
1652             -ieee754        IEEE Std 754-1985
1653                             Floating-point arithmetic.
1654
1655             -iso8601
1656                             Representation of dates and times, published in
1657                             1988.
1658
1659             -iso8802-3      ISO/IEC 8802-3:1989
1660                             Ethernet local area networks.
1661
1662             -ieee1275-94    IEEE Std 1275-1994 (“Open Firmware”)
1663
1664     Sx Title line
1665          Reference a section or subsection in the same manual page.  The ref‐
1666          erenced section or subsection name must be identical to the enclosed
1667          argument, including whitespace.
1668
1669          Examples:
1670                .Sx MANUAL STRUCTURE
1671
1672          See also Sh and Ss.
1673
1674     Sy word ...
1675          Request a boldface font.
1676
1677          This is most often used to indicate importance or seriousness (not
1678          to be confused with stress emphasis, see Em).  When none of the
1679          semantic macros fit, it is also adequate for syntax elements that
1680          have to be given or that appear verbatim.
1681
1682          Examples:
1683                .Sy Warning :
1684                If
1685                .Sy s
1686                appears in the owner permissions, set-user-ID mode is set.
1687                This utility replaces the former
1688                .Sy dumpdir
1689                program.
1690
1691          See also Em, No, and Ql.
1692
1693     Ta   Table cell separator in Bl -column lists; can only be used below It.
1694
1695     Tn word ...
1696          Supported only for compatibility, do not use this in new manuals.
1697          Even though the macro name (“tradename”) suggests a semantic func‐
1698          tion, historic usage is inconsistent, mostly using it as a presenta‐
1699          tion-level macro to request a small caps font.
1700
1701     Ud   Supported only for compatibility, do not use this in new manuals.
1702          Prints out “currently under development.”
1703
1704     Ux   Supported only for compatibility, do not use this in new manuals.
1705          Prints out “UNIX”.
1706
1707     Va [type] identifier ...
1708          A variable name.
1709
1710          Examples:
1711                .Va foo
1712                .Va const char *bar;
1713
1714          For function arguments and parameters, use Fa instead.  For declara‐
1715          tions of global variables in the SYNOPSIS section, use Vt.
1716
1717     Vt type [identifier]
1718          A variable type.
1719
1720          This is also used for indicating global variables in the SYNOPSIS
1721          section, in which case a variable name is also specified.  Note that
1722          it accepts Block partial-implicit syntax when invoked as the first
1723          macro on an input line in the SYNOPSIS section, else it accepts
1724          ordinary In-line syntax.  In the former case, this macro starts a
1725          new output line, and a blank line is inserted in front if there is a
1726          preceding function definition or include directive.
1727
1728          Examples:
1729                .Vt unsigned char
1730                .Vt extern const char * const sys_signame[] ;
1731
1732          For parameters in function prototypes, use Fa instead, for function
1733          return types Ft, and for variable names outside the SYNOPSIS section
1734          Va, even when including a type with the name.  See also MANUAL
1735          STRUCTURE.
1736
1737     Xc   Close a scope opened by Xo.
1738
1739     Xo block
1740          Extend the header of an It macro or the body of a partial-implicit
1741          block macro beyond the end of the input line.  This macro originally
1742          existed to work around the 9-argument limit of historic roff(7).
1743
1744     Xr name section
1745          Link to another manual ("cross-reference").
1746
1747          Cross reference the name and section number of another man page.
1748
1749          Examples:
1750                .Xr mandoc 1
1751                .Xr mandoc 1 ;
1752                .Xr mandoc 1 Ns s behaviour
1753

MACRO SYNTAX

1755     The syntax of a macro depends on its classification.  In this section,
1756     ‘-arg’ refers to macro arguments, which may be followed by zero or more
1757     ‘parm’ parameters; ‘Yo’ opens the scope of a macro; and if specified,
1758     ‘Yc’ closes it out.
1759
1760     The Callable column indicates that the macro may also be called by pass‐
1761     ing its name as an argument to another macro.  For example, ‘.Op Fl O Ar
1762     file’ produces ‘[-O file]’.  To prevent a macro call and render the macro
1763     name literally, escape it by prepending a zero-width space, ‘\&’.  For
1764     example, ‘Op \&Fl O’ produces ‘[Fl O]’.  If a macro is not callable but
1765     its name appears as an argument to another macro, it is interpreted as
1766     opaque text.  For example, ‘.Fl Sh’ produces ‘-Sh’.
1767
1768     The Parsed column indicates whether the macro may call other macros by
1769     receiving their names as arguments.  If a macro is not parsed but the
1770     name of another macro appears as an argument, it is interpreted as opaque
1771     text.
1772
1773     The Scope column, if applicable, describes closure rules.
1774
1775   Block full-explicit
1776     Multi-line scope closed by an explicit closing macro.  All macros con‐
1777     tains bodies; only Bf and (optionally) Bl contain a head.
1778
1779           .Yo [-arg [parm...]] [head...]
1780           [body...]
1781           .Yc
1782
1783           Macro     Callable     Parsed     Scope
1784           Bd        No           No         closed by Ed
1785           Bf        No           No         closed by Ef
1786           Bk        No           No         closed by Ek
1787           Bl        No           No         closed by El
1788           Ed        No           No         opened by Bd
1789           Ef        No           No         opened by Bf
1790           Ek        No           No         opened by Bk
1791           El        No           No         opened by Bl
1792
1793   Block full-implicit
1794     Multi-line scope closed by end-of-file or implicitly by another macro.
1795     All macros have bodies; some (It -bullet, -hyphen, -dash, -enum, -item)
1796     don't have heads; only one (It in Bl -column) has multiple heads.
1797
1798           .Yo [-arg [parm...]] [head... [Ta head...]]
1799           [body...]
1800
1801           Macro     Callable     Parsed     Scope
1802           It        No           Yes        closed by It, El
1803           Nd        No           No         closed by Sh
1804           Nm        No           Yes        closed by Nm, Sh, Ss
1805           Sh        No           Yes        closed by Sh
1806           Ss        No           Yes        closed by Sh, Ss
1807
1808     Note that the Nm macro is a Block full-implicit macro only when invoked
1809     as the first macro in a SYNOPSIS section line, else it is In-line.
1810
1811   Block partial-explicit
1812     Like block full-explicit, but also with single-line scope.  Each has at
1813     least a body and, in limited circumstances, a head (Fo, Eo) and/or tail
1814     (Ec).
1815
1816           .Yo [-arg [parm...]] [head...]
1817           [body...]
1818           .Yc [tail...]
1819
1820           .Yo [-arg [parm...]] [head...] [body...] Yc [tail...]
1821
1822           Macro     Callable     Parsed     Scope
1823           Ac        Yes          Yes        opened by Ao
1824           Ao        Yes          Yes        closed by Ac
1825           Bc        Yes          Yes        closed by Bo
1826           Bo        Yes          Yes        opened by Bc
1827           Brc       Yes          Yes        opened by Bro
1828           Bro       Yes          Yes        closed by Brc
1829           Dc        Yes          Yes        opened by Do
1830           Do        Yes          Yes        closed by Dc
1831           Ec        Yes          Yes        opened by Eo
1832           Eo        Yes          Yes        closed by Ec
1833           Fc        Yes          Yes        opened by Fo
1834           Fo        No           No         closed by Fc
1835           Oc        Yes          Yes        closed by Oo
1836           Oo        Yes          Yes        opened by Oc
1837           Pc        Yes          Yes        closed by Po
1838           Po        Yes          Yes        opened by Pc
1839           Qc        Yes          Yes        opened by Oo
1840           Qo        Yes          Yes        closed by Oc
1841           Re        No           No         opened by Rs
1842           Rs        No           No         closed by Re
1843           Sc        Yes          Yes        opened by So
1844           So        Yes          Yes        closed by Sc
1845           Xc        Yes          Yes        opened by Xo
1846           Xo        Yes          Yes        closed by Xc
1847
1848   Block partial-implicit
1849     Like block full-implicit, but with single-line scope closed by the end of
1850     the line.
1851
1852           .Yo [-arg [val...]] [body...] [res...]
1853
1854           Macro     Callable     Parsed
1855           Aq        Yes          Yes
1856           Bq        Yes          Yes
1857           Brq       Yes          Yes
1858           D1        No           Yes
1859           Dl        No           Yes
1860           Dq        Yes          Yes
1861           En        Yes          Yes
1862           Op        Yes          Yes
1863           Pq        Yes          Yes
1864           Ql        Yes          Yes
1865           Qq        Yes          Yes
1866           Sq        Yes          Yes
1867           Vt        Yes          Yes
1868
1869     Note that the Vt macro is a Block partial-implicit only when invoked as
1870     the first macro in a SYNOPSIS section line, else it is In-line.
1871
1872   Special block macro
1873     The Ta macro can only be used below It in Bl -column lists.  It delimits
1874     blocks representing table cells; these blocks have bodies, but no heads.
1875
1876           Macro     Callable     Parsed     Scope
1877           Ta        Yes          Yes        closed by Ta, It
1878
1879   In-line
1880     Closed by the end of the line, fixed argument lengths, and/or subsequent
1881     macros.  In-line macros have only text children.  If a number (or
1882     inequality) of arguments is (n), then the macro accepts an arbitrary num‐
1883     ber of arguments.
1884
1885           .Yo [-arg [val...]] [args...] [res...]
1886
1887           .Yo [-arg [val...]] [args...] Yc...
1888
1889           .Yo [-arg [val...]] arg0 arg1 argN
1890
1891           Macro     Callable     Parsed     Arguments
1892           %A        No           No         >0
1893           %B        No           No         >0
1894           %C        No           No         >0
1895           %D        No           No         >0
1896           %I        No           No         >0
1897           %J        No           No         >0
1898           %N        No           No         >0
1899           %O        No           No         >0
1900           %P        No           No         >0
1901           %Q        No           No         >0
1902           %R        No           No         >0
1903           %T        No           No         >0
1904           %U        No           No         >0
1905           %V        No           No         >0
1906           Ad        Yes          Yes        >0
1907           An        Yes          Yes        >0
1908           Ap        Yes          Yes        0
1909           Ar        Yes          Yes        n
1910           At        Yes          Yes        1
1911           Bsx       Yes          Yes        n
1912           Bt        No           No         0
1913           Bx        Yes          Yes        n
1914           Cd        Yes          Yes        >0
1915           Cm        Yes          Yes        >0
1916           Db        No           No         1
1917           Dd        No           No         n
1918           Dt        No           No         n
1919           Dv        Yes          Yes        >0
1920           Dx        Yes          Yes        n
1921           Em        Yes          Yes        >0
1922           Er        Yes          Yes        >0
1923           Es        Yes          Yes        2
1924           Ev        Yes          Yes        >0
1925           Ex        No           No         n
1926           Fa        Yes          Yes        >0
1927           Fd        No           No         >0
1928           Fl        Yes          Yes        n
1929           Fn        Yes          Yes        >0
1930           Fr        Yes          Yes        >0
1931           Ft        Yes          Yes        >0
1932           Fx        Yes          Yes        n
1933           Hf        No           No         n
1934           Ic        Yes          Yes        >0
1935           In        No           No         1
1936           Lb        No           No         1
1937           Li        Yes          Yes        >0
1938           Lk        Yes          Yes        >0
1939           Lp        No           No         0
1940           Ms        Yes          Yes        >0
1941           Mt        Yes          Yes        >0
1942           Nm        Yes          Yes        n
1943           No        Yes          Yes        >0
1944           Ns        Yes          Yes        0
1945           Nx        Yes          Yes        n
1946           Os        No           No         n
1947           Ot        Yes          Yes        >0
1948           Ox        Yes          Yes        n
1949           Pa        Yes          Yes        n
1950           Pf        Yes          Yes        1
1951           Pp        No           No         0
1952           Rv        No           No         n
1953           Sm        No           No         <2
1954           St        No           Yes        1
1955           Sx        Yes          Yes        >0
1956           Sy        Yes          Yes        >0
1957           Tn        Yes          Yes        >0
1958           Ud        No           No         0
1959           Ux        Yes          Yes        n
1960           Va        Yes          Yes        n
1961           Vt        Yes          Yes        >0
1962           Xr        Yes          Yes        2
1963
1964   Delimiters
1965     When a macro argument consists of one single input character considered
1966     as a delimiter, the argument gets special handling.  This does not apply
1967     when delimiters appear in arguments containing more than one character.
1968     Consequently, to prevent special handling and just handle it like any
1969     other argument, a delimiter can be escaped by prepending a zero-width
1970     space (‘\&’).  In text lines, delimiters never need escaping, but may be
1971     used as normal punctuation.
1972
1973     For many macros, when the leading arguments are opening delimiters, these
1974     delimiters are put before the macro scope, and when the trailing argu‐
1975     ments are closing delimiters, these delimiters are put after the macro
1976     scope.  Spacing is suppressed after opening delimiters and before closing
1977     delimiters.  For example,
1978
1979           .Aq ( [ word ] ) .
1980
1981     renders as:
1982
1983           ([⟨word⟩]).
1984
1985     Opening delimiters are:
1986
1987           (       left parenthesis
1988           [       left bracket
1989
1990     Closing delimiters are:
1991
1992           .       period
1993           ,       comma
1994           :       colon
1995           ;       semicolon
1996           )       right parenthesis
1997           ]       right bracket
1998           ?       question mark
1999           !       exclamation mark
2000
2001     Note that even a period preceded by a backslash (‘\.’) gets this special
2002     handling; use ‘\&.’ to prevent that.
2003
2004     Many in-line macros interrupt their scope when they encounter delimiters,
2005     and resume their scope when more arguments follow that are not delim‐
2006     iters.  For example,
2007
2008           .Fl a ( b | c \*(Ba d ) e
2009
2010     renders as:
2011
2012           -a (-b | -c | -d) -e
2013
2014     This applies to both opening and closing delimiters, and also to the mid‐
2015     dle delimiter, which does not suppress spacing:
2016
2017           |       vertical bar
2018
2019     As a special case, the predefined string \*(Ba is handled and rendered in
2020     the same way as a plain ‘|’ character.  Using this predefined string is
2021     not recommended in new manuals.
2022
2023   Font handling
2024     In mdoc documents, usage of semantic markup is recommended in order to
2025     have proper fonts automatically selected; only when no fitting semantic
2026     markup is available, consider falling back to Physical markup macros.
2027     Whenever any mdoc macro switches the roff(7) font mode, it will automati‐
2028     cally restore the previous font when exiting its scope.  Manually switch‐
2029     ing the font using the roff(7) ‘\f’ font escape sequences is never
2030     required.
2031

COMPATIBILITY

2033     This section provides an incomplete list of compatibility issues between
2034     mandoc and GNU troff ("groff").
2035
2036     The following problematic behaviour is found in groff:
2037
2038     -   Dd with non-standard arguments behaves very strangely.  When there
2039         are three arguments, they are printed verbatim.  Any other number of
2040         arguments is replaced by the current date, but without any arguments
2041         the string “Epoch” is printed.
2042     -   Lk only accepts a single link-name argument; the remainder is misfor‐
2043         matted.
2044     -   Pa does not format its arguments when used in the FILES section under
2045         certain list types.
2046     -   Ta can only be called by other macros, but not at the beginning of a
2047         line.
2048     -   %C is not implemented (up to and including groff-1.22.2).
2049     -   ‘\f’ (font face) and ‘\F’ (font family face) Text Decoration escapes
2050         behave irregularly when specified within line-macro scopes.
2051     -   Negative scaling units return to prior lines.  Instead, mandoc trun‐
2052         cates them to zero.
2053
2054     The following features are unimplemented in mandoc:
2055
2056     -   Bd -file file is unsupported for security reasons.
2057     -   Bd -filled does not adjust the right margin, but is an alias for Bd
2058         -ragged.
2059     -   Bd -literal does not use a literal font, but is an alias for Bd
2060         -unfilled.
2061     -   Bd -offset center and -offset right don't work.  Groff does not
2062         implement centered and flush-right rendering either, but produces
2063         large indentations.
2064

SEE ALSO

2066     man(1), mandoc(1), eqn(7), man(7), mandoc_char(7), roff(7), tbl(7)
2067
2068     The web page extended documentation for the mdoc language:
2069           http://mandoc.bsd.lv/mdoc/
2070     provides a few tutorial-style pages for beginners, an extensive style
2071     guide for advanced authors, and an alphabetic index helping to choose the
2072     best macros for various kinds of content.
2073

HISTORY

2075     The mdoc language first appeared as a troff macro package in 4.4BSD.  It
2076     was later significantly updated by Werner Lemberg and Ruslan Ermilov in
2077     groff-1.17.  The standalone implementation that is part of the mandoc(1)
2078     utility written by Kristaps Dzonsons appeared in OpenBSD 4.6.
2079

AUTHORS

2081     The mdoc reference was written by Kristaps Dzonsons <kristaps@bsd.lv>.
2082
2083BSD                              May 10, 2020                              BSD
Impressum