xref: /freebsd/contrib/mandoc/mdoc.7 (revision db33c6f3ae9d1231087710068ee4ea5398aacca7)
1.\" $Id: mdoc.7,v 1.294 2024/09/22 10:34:58 schwarze Exp $
2.\"
3.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4.\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze <schwarze@openbsd.org>
5.\"
6.\" Permission to use, copy, modify, and distribute this software for any
7.\" purpose with or without fee is hereby granted, provided that the above
8.\" copyright notice and this permission notice appear in all copies.
9.\"
10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17.\"
18.Dd $Mdocdate: September 22 2024 $
19.Dt MDOC 7
20.Os
21.Sh NAME
22.Nm mdoc
23.Nd semantic markup language for formatting manual pages
24.Sh DESCRIPTION
25The
26.Nm mdoc
27language supports authoring of manual pages for the
28.Xr man 1
29utility by allowing semantic annotations of words, phrases,
30page sections and complete manual pages.
31Such annotations are used by formatting tools to achieve a uniform
32presentation across all manuals written in
33.Nm ,
34and to support hyperlinking if supported by the output medium.
35.Pp
36This reference document describes the structure of manual pages
37and the syntax and usage of the
38.Nm
39language.
40The reference implementation of a parsing and formatting tool is
41.Xr mandoc 1 ;
42the
43.Sx COMPATIBILITY
44section describes compatibility with other implementations.
45.Pp
46In an
47.Nm
48document, lines beginning with the control character
49.Sq \&.
50are called
51.Dq macro lines .
52The first word is the macro name.
53It consists of two or three letters.
54Most macro names begin with a capital letter.
55For a list of available macros, see
56.Sx MACRO OVERVIEW .
57The words following the macro name are arguments to the macro, optionally
58including the names of other, callable macros; see
59.Sx MACRO SYNTAX
60for details.
61.Pp
62Lines not beginning with the control character are called
63.Dq text lines .
64They provide free-form text to be printed; the formatting of the text
65depends on the respective processing context:
66.Bd -literal -offset indent
67\&.Sh Macro lines change control state.
68Text lines are interpreted within the current state.
69.Ed
70.Pp
71Many aspects of the basic syntax of the
72.Nm
73language are based on the
74.Xr roff 7
75language; see the
76.Em LANGUAGE SYNTAX
77and
78.Em MACRO SYNTAX
79sections in the
80.Xr roff 7
81manual for details, in particular regarding
82comments, escape sequences, whitespace, and quoting.
83However, using
84.Xr roff 7
85requests in
86.Nm
87documents is discouraged;
88.Xr mandoc 1
89supports some of them merely for backward compatibility.
90.Sh MANUAL STRUCTURE
91A well-formed
92.Nm
93document consists of a document prologue followed by one or more
94sections.
95.Pp
96The prologue, which consists of the
97.Ic \&Dd ,
98.Ic \&Dt ,
99and
100.Ic \&Os
101macros in that order, is required for every document.
102.Pp
103The first section (sections are denoted by
104.Ic \&Sh )
105must be the NAME section, consisting of at least one
106.Ic \&Nm
107followed by
108.Ic \&Nd .
109.Pp
110Following that, convention dictates specifying at least the
111.Em SYNOPSIS
112and
113.Em DESCRIPTION
114sections, although this varies between manual sections.
115.Pp
116The following is a well-formed skeleton
117.Nm
118file for a utility
119.Qq progname :
120.Bd -literal -offset indent
121\&.Dd $\&Mdocdate$
122\&.Dt PROGNAME section
123\&.Os
124\&.Sh NAME
125\&.Nm progname
126\&.Nd one line about what it does
127\&.\e\(dq .Sh LIBRARY
128\&.\e\(dq For sections 2, 3, and 9 only.
129\&.\e\(dq Not used in OpenBSD.
130\&.Sh SYNOPSIS
131\&.Nm progname
132\&.Op Fl options
133\&.Ar
134\&.Sh DESCRIPTION
135The
136\&.Nm
137utility processes files ...
138\&.\e\(dq .Sh CONTEXT
139\&.\e\(dq For section 9 functions only.
140\&.\e\(dq .Sh IMPLEMENTATION NOTES
141\&.\e\(dq Not used in OpenBSD.
142\&.\e\(dq .Sh RETURN VALUES
143\&.\e\(dq For sections 2, 3, and 9 function return values only.
144\&.\e\(dq .Sh ENVIRONMENT
145\&.\e\(dq For sections 1, 6, 7, and 8 only.
146\&.\e\(dq .Sh FILES
147\&.\e\(dq .Sh EXIT STATUS
148\&.\e\(dq For sections 1, 6, and 8 only.
149\&.\e\(dq .Sh EXAMPLES
150\&.\e\(dq .Sh DIAGNOSTICS
151\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
152\&.\e\(dq .Sh ERRORS
153\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
154\&.\e\(dq .Sh SEE ALSO
155\&.\e\(dq .Xr foobar 1
156\&.\e\(dq .Sh STANDARDS
157\&.\e\(dq .Sh HISTORY
158\&.\e\(dq .Sh AUTHORS
159\&.\e\(dq .Sh CAVEATS
160\&.\e\(dq .Sh BUGS
161\&.\e\(dq .Sh SECURITY CONSIDERATIONS
162\&.\e\(dq Not used in OpenBSD.
163.Ed
164.Pp
165The sections in an
166.Nm
167document are conventionally ordered as they appear above.
168Sections should be composed as follows:
169.Bl -ohang -offset Ds
170.It Em NAME
171The name(s) and a one line description of the documented material.
172The syntax for this as follows:
173.Bd -literal -offset indent
174\&.Nm name0 ,
175\&.Nm name1 ,
176\&.Nm name2
177\&.Nd a one line description
178.Ed
179.Pp
180Multiple
181.Sq \&Nm
182names should be separated by commas.
183.Pp
184The
185.Ic \&Nm
186macro(s) must precede the
187.Ic \&Nd
188macro.
189.Pp
190See
191.Ic \&Nm
192and
193.Ic \&Nd .
194.It Em LIBRARY
195The name of the library containing the documented material, which is
196assumed to be a function in a section 2, 3, or 9 manual.
197The syntax for this is as follows:
198.Bd -literal -offset indent
199\&.Lb libarm
200.Ed
201.Pp
202See
203.Ic \&Lb .
204.It Em SYNOPSIS
205Documents the utility invocation syntax, function call syntax, or device
206configuration.
207.Pp
208For the first, utilities (sections 1, 6, and 8), this is
209generally structured as follows:
210.Bd -literal -offset indent
211\&.Nm bar
212\&.Op Fl v
213\&.Op Fl o Ar file
214\&.Op Ar
215\&.Nm foo
216\&.Op Fl v
217\&.Op Fl o Ar file
218\&.Op Ar
219.Ed
220.Pp
221Commands should be ordered alphabetically.
222.Pp
223For the second, function calls (sections 2, 3, 9):
224.Bd -literal -offset indent
225\&.In header.h
226\&.Vt extern const char *global;
227\&.Ft "char *"
228\&.Fn foo "const char *src"
229\&.Ft "char *"
230\&.Fn bar "const char *src"
231.Ed
232.Pp
233Ordering of
234.Ic \&In ,
235.Ic \&Vt ,
236.Ic \&Fn ,
237and
238.Ic \&Fo
239macros should follow C header-file conventions.
240.Pp
241And for the third, configurations (section 4):
242.Bd -literal -offset indent
243\&.Cd \(dqit* at isa? port 0x2e\(dq
244\&.Cd \(dqit* at isa? port 0x4e\(dq
245.Ed
246.Pp
247Manuals not in these sections generally don't need a
248.Em SYNOPSIS .
249.Pp
250Some macros are displayed differently in the
251.Em SYNOPSIS
252section, particularly
253.Ic \&Nm ,
254.Ic \&Cd ,
255.Ic \&Fd ,
256.Ic \&Fn ,
257.Ic \&Fo ,
258.Ic \&In ,
259.Ic \&Vt ,
260and
261.Ic \&Ft .
262All of these macros are output on their own line.
263If two such dissimilar macros are pairwise invoked (except for
264.Ic \&Ft
265before
266.Ic \&Fo
267or
268.Ic \&Fn ) ,
269they are separated by a vertical space, unless in the case of
270.Ic \&Fo ,
271.Ic \&Fn ,
272and
273.Ic \&Ft ,
274which are always separated by vertical space.
275.Pp
276When text and macros following an
277.Ic \&Nm
278macro starting an input line span multiple output lines,
279all output lines but the first will be indented to align
280with the text immediately following the
281.Ic \&Nm
282macro, up to the next
283.Ic \&Nm ,
284.Ic \&Sh ,
285or
286.Ic \&Ss
287macro or the end of an enclosing block, whichever comes first.
288.It Em DESCRIPTION
289This begins with an expansion of the brief, one line description in
290.Em NAME :
291.Bd -literal -offset indent
292The
293\&.Nm
294utility does this, that, and the other.
295.Ed
296.Pp
297It usually follows with a breakdown of the options (if documenting a
298command), such as:
299.Bd -literal -offset indent
300The options are as follows:
301\&.Bl \-tag \-width Ds
302\&.It Fl v
303Print verbose information.
304\&.El
305.Ed
306.Pp
307List the options in alphabetical order,
308uppercase before lowercase for each letter and
309with no regard to whether an option takes an argument.
310Put digits in ascending order before all letter options.
311.Pp
312Manuals not documenting a command won't include the above fragment.
313.Pp
314Since the
315.Em DESCRIPTION
316section usually contains most of the text of a manual, longer manuals
317often use the
318.Ic \&Ss
319macro to form subsections.
320In very long manuals, the
321.Em DESCRIPTION
322may be split into multiple sections, each started by an
323.Ic \&Sh
324macro followed by a non-standard section name, and each having
325several subsections, like in the present
326.Nm
327manual.
328.It Em CONTEXT
329This section lists the contexts in which functions can be called in section 9.
330The contexts are autoconf, process, or interrupt.
331.It Em IMPLEMENTATION NOTES
332Implementation-specific notes should be kept here.
333This is useful when implementing standard functions that may have side
334effects or notable algorithmic implications.
335.It Em RETURN VALUES
336This section documents the
337return values of functions in sections 2, 3, and 9.
338.Pp
339See
340.Ic \&Rv .
341.It Em ENVIRONMENT
342Lists the environment variables used by the utility,
343and explains the syntax and semantics of their values.
344The
345.Xr environ 7
346manual provides examples of typical content and formatting.
347.Pp
348See
349.Ic \&Ev .
350.It Em FILES
351Documents files used.
352It's helpful to document both the file name and a short description of how
353the file is used (created, modified, etc.).
354.Pp
355See
356.Ic \&Pa .
357.It Em EXIT STATUS
358This section documents the
359command exit status for section 1, 6, and 8 utilities.
360Historically, this information was described in
361.Em DIAGNOSTICS ,
362a practise that is now discouraged.
363.Pp
364See
365.Ic \&Ex .
366.It Em EXAMPLES
367Example usages.
368This often contains snippets of well-formed, well-tested invocations.
369Make sure that examples work properly!
370.It Em DIAGNOSTICS
371Documents error messages.
372In section 4 and 9 manuals, these are usually messages printed by the
373kernel to the console and to the kernel log.
374In section 1, 6, 7, and 8, these are usually messages printed by
375userland programs to the standard error output.
376.Pp
377Historically, this section was used in place of
378.Em EXIT STATUS
379for manuals in sections 1, 6, and 8; however, this practise is
380discouraged.
381.Pp
382See
383.Ic \&Bl
384.Fl diag .
385.It Em ERRORS
386Documents
387.Xr errno 2
388settings in sections 2, 3, 4, and 9.
389.Pp
390See
391.Ic \&Er .
392.It Em SEE ALSO
393References other manuals with related topics.
394This section should exist for most manuals.
395Cross-references should conventionally be ordered first by section, then
396alphabetically (ignoring case).
397.Pp
398References to other documentation concerning the topic of the manual page,
399for example authoritative books or journal articles, may also be
400provided in this section.
401.Pp
402See
403.Ic \&Rs
404and
405.Ic \&Xr .
406.It Em STANDARDS
407References any standards implemented or used.
408If not adhering to any standards, the
409.Em HISTORY
410section should be used instead.
411.Pp
412See
413.Ic \&St .
414.It Em HISTORY
415A brief history of the subject, including where it was first implemented,
416and when it was ported to or reimplemented for the operating system at hand.
417.It Em AUTHORS
418Credits to the person or persons who wrote the code and/or documentation.
419Authors should generally be noted by both name and email address.
420.Pp
421See
422.Ic \&An .
423.It Em CAVEATS
424Common misuses and misunderstandings should be explained
425in this section.
426.It Em BUGS
427Known bugs, limitations, and work-arounds should be described
428in this section.
429.It Em SECURITY CONSIDERATIONS
430Documents any security precautions that operators should consider.
431.El
432.Sh MACRO OVERVIEW
433This overview is sorted such that macros of similar purpose are listed
434together, to help find the best macro for any given purpose.
435Deprecated macros are not included in the overview, but can be found below
436in the alphabetical
437.Sx MACRO REFERENCE .
438.Ss Document preamble and NAME section macros
439.Bl -column "Brq, Bro, Brc" description
440.It Ic \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year
441.It Ic \&Dt Ta document title: Ar TITLE section Op Ar arch
442.It Ic \&Os Ta operating system footer: Op Ar footer text
443.It Ic \&Nm Ta document name (one argument)
444.It Ic \&Nd Ta document description (one line)
445.El
446.Ss Sections and cross references
447.Bl -column "Brq, Bro, Brc" description
448.It Ic \&Sh Ta section header (one line)
449.It Ic \&Ss Ta subsection header (one line)
450.It Ic \&Sx Ta internal cross reference to a section or subsection
451.It Ic \&Xr Ta cross reference to another manual page: Ar name section
452.It Ic \&Tg Ta tag the definition of a Ar term Pq <= 1 arguments
453.It Ic \&Pp Ta start a text paragraph (no arguments)
454.El
455.Ss Displays and lists
456.Bl -column "Brq, Bro, Brc" description
457.It Ic \&Bd , \&Ed Ta display block:
458.Fl Ar type
459.Op Fl offset Ar width
460.Op Fl compact
461.It Ic \&D1 Ta indented display (one line)
462.It Ic \&Dl Ta indented literal display (one line)
463.It Ic \&Ql Ta in-line literal display: Ql text
464.It Ic \&Bl , \&El Ta list block:
465.Fl Ar type
466.Op Fl width Ar val
467.Op Fl offset Ar val
468.Op Fl compact
469.It Ic \&It Ta list item (syntax depends on Fl Ar type )
470.It Ic \&Ta Ta table cell separator in Ic \&Bl Fl column No lists
471.It Ic \&Rs , \&%* , \&Re Ta bibliographic block (references)
472.El
473.Ss Spacing control
474.Bl -column "Brq, Bro, Brc" description
475.It Ic \&Pf Ta prefix, no following horizontal space (one argument)
476.It Ic \&Ns Ta roman font, no preceding horizontal space (no arguments)
477.It Ic \&Ap Ta apostrophe without surrounding whitespace (no arguments)
478.It Ic \&Sm Ta switch horizontal spacing mode: Op Cm on | off
479.It Ic \&Bk , \&Ek Ta keep block: Fl words
480.El
481.Ss Semantic markup for command line utilities
482.Bl -column "Brq, Bro, Brc" description
483.It Ic \&Nm Ta start a SYNOPSIS block with the name of a utility
484.It Ic \&Fl Ta command line options (flags) (>=0 arguments)
485.It Ic \&Cm Ta command modifier (>0 arguments)
486.It Ic \&Ar Ta command arguments (>=0 arguments)
487.It Ic \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure)
488.It Ic \&Ic Ta internal or interactive command (>0 arguments)
489.It Ic \&Ev Ta environmental variable (>0 arguments)
490.It Ic \&Pa Ta file system path (>=0 arguments)
491.El
492.Ss Semantic markup for function libraries
493.Bl -column "Brq, Bro, Brc" description
494.It Ic \&Lb Ta function library (one argument)
495.It Ic \&In Ta include file (one argument)
496.It Ic \&Fd Ta other preprocessor directive (>0 arguments)
497.It Ic \&Ft Ta function type (>0 arguments)
498.It Ic \&Fo , \&Fc Ta function block: Ar funcname
499.It Ic \&Fn Ta function name: Ar funcname Op Ar argument ...
500.It Ic \&Fa Ta function argument (>0 arguments)
501.It Ic \&Vt Ta variable type (>0 arguments)
502.It Ic \&Va Ta variable name (>0 arguments)
503.It Ic \&Dv Ta defined variable or preprocessor constant (>0 arguments)
504.It Ic \&Er Ta error constant (>0 arguments)
505.It Ic \&Ev Ta environmental variable (>0 arguments)
506.El
507.Ss Various semantic markup
508.Bl -column "Brq, Bro, Brc" description
509.It Ic \&An Ta author name (>0 arguments)
510.It Ic \&Lk Ta hyperlink: Ar uri Op Ar display_name
511.It Ic \&Mt Ta Do mailto Dc hyperlink: Ar localpart Ns @ Ns Ar domain
512.It Ic \&Cd Ta kernel configuration declaration (>0 arguments)
513.It Ic \&Ad Ta memory address (>0 arguments)
514.It Ic \&Ms Ta mathematical symbol (>0 arguments)
515.El
516.Ss Physical markup
517.Bl -column "Brq, Bro, Brc" description
518.It Ic \&Em Ta italic font or underline (emphasis) (>0 arguments)
519.It Ic \&Sy Ta boldface font (symbolic) (>0 arguments)
520.It Ic \&No Ta return to roman font (normal) (>0 arguments)
521.It Ic \&Bf , \&Ef Ta font block: Fl Ar type | Cm \&Em | \&Li | \&Sy
522.El
523.Ss Physical enclosures
524.Bl -column "Brq, Bro, Brc" description
525.It Ic \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text
526.It Ic \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text
527.It Ic \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text
528.It Ic \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text
529.It Ic \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text
530.It Ic \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text
531.It Ic \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text
532.It Ic \&Eo , \&Ec Ta generic enclosure
533.El
534.Ss Text production
535.Bl -column "Brq, Bro, Brc" description
536.It Ic \&Ex Fl std Ta standard command exit values: Op Ar utility ...
537.It Ic \&Rv Fl std Ta standard function return values: Op Ar function ...
538.It Ic \&St Ta reference to a standards document (one argument)
539.It Ic \&At Ta At
540.It Ic \&Bx Ta Bx
541.It Ic \&Bsx Ta Bsx
542.It Ic \&Nx Ta Nx
543.It Ic \&Fx Ta Fx
544.It Ic \&Ox Ta Ox
545.It Ic \&Dx Ta Dx
546.El
547.Sh MACRO REFERENCE
548This section is a canonical reference of all macros, arranged
549alphabetically.
550For the scoping of individual macros, see
551.Sx MACRO SYNTAX .
552.Bl -tag -width 3n
553.It Ic \&%A Ar first_name ... last_name
554Author name of an
555.Ic \&Rs
556block.
557Multiple authors should each be accorded their own
558.Ic \%%A
559line.
560Author names should be ordered with full or abbreviated forename(s)
561first, then full surname.
562.It Ic \&%B Ar title
563Book title of an
564.Ic \&Rs
565block.
566This macro may also be used in a non-bibliographic context when
567referring to book titles.
568.It Ic \&%C Ar location
569Publication city or location of an
570.Ic \&Rs
571block.
572.It Ic \&%D Oo Ar month day , Oc Ar year
573Publication date of an
574.Ic \&Rs
575block.
576Provide the full English name of the
577.Ar month
578and all four digits of the
579.Ar year .
580.It Ic \&%I Ar name
581Publisher or issuer name of an
582.Ic \&Rs
583block.
584.It Ic \&%J Ar name
585Journal name of an
586.Ic \&Rs
587block.
588.It Ic \&%N Ar number
589Issue number (usually for journals) of an
590.Ic \&Rs
591block.
592.It Ic \&%O Ar line
593Optional information of an
594.Ic \&Rs
595block.
596.It Ic \&%P Ar number
597Book or journal page number of an
598.Ic \&Rs
599block.
600Conventionally, the argument starts with
601.Ql p.\&
602for a single page or
603.Ql pp.\&
604for a range of pages, for example:
605.Pp
606.Dl .%P pp. 42\e(en47
607.It Ic \&%Q Ar name
608Institutional author (school, government, etc.) of an
609.Ic \&Rs
610block.
611Multiple institutional authors should each be accorded their own
612.Ic \&%Q
613line.
614.It Ic \&%R Ar name
615Technical report name of an
616.Ic \&Rs
617block.
618.It Ic \&%T Ar title
619Article title of an
620.Ic \&Rs
621block.
622This macro may also be used in a non-bibliographical context when
623referring to article titles.
624.It Ic \&%U Ar protocol Ns :// Ns Ar path
625URI of reference document.
626.It Ic \&%V Ar number
627Volume number of an
628.Ic \&Rs
629block.
630.It Ic \&Ac
631Close an
632.Ic \&Ao
633block.
634Does not have any tail arguments.
635.Tg Ad
636.It Ic \&Ad Ar address
637Memory address.
638Do not use this for postal addresses.
639.Pp
640Examples:
641.Dl \&.Ad [0,$]
642.Dl \&.Ad 0x00000000
643.Tg An
644.It Ic \&An Fl split | nosplit | Ar first_name ... last_name
645Author name.
646Can be used both for the authors of the program, function, or driver
647documented in the manual, or for the authors of the manual itself.
648Requires either the name of an author or one of the following arguments:
649.Pp
650.Bl -tag -width "-nosplitX" -offset indent -compact
651.It Fl split
652Start a new output line before each subsequent invocation of
653.Ic \&An .
654.It Fl nosplit
655The opposite of
656.Fl split .
657.El
658.Pp
659The default is
660.Fl nosplit .
661The effect of selecting either of the
662.Fl split
663modes ends at the beginning of the
664.Em AUTHORS
665section.
666In the
667.Em AUTHORS
668section, the default is
669.Fl nosplit
670for the first author listing and
671.Fl split
672for all other author listings.
673.Pp
674Examples:
675.Dl \&.An -nosplit
676.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
677.It Ic \&Ao Ar block
678Begin a block enclosed by angle brackets.
679Does not have any head arguments.
680This macro is almost never useful.
681See
682.Ic \&Aq
683for more details.
684.Tg Ap
685.It Ic \&Ap
686Inserts an apostrophe without any surrounding whitespace.
687This is generally used as a grammatical device when referring to the verb
688form of a function.
689.Pp
690Examples:
691.Dl \&.Fn execve \&Ap d
692.Tg Aq
693.It Ic \&Aq Ar line
694Enclose the rest of the input line in angle brackets.
695The only important use case is for email addresses.
696See
697.Ic \&Mt
698for an example.
699.Pp
700Occasionally, it is used for names of characters and keys, for example:
701.Bd -literal -offset indent
702Press the
703\&.Aq escape
704key to ...
705.Ed
706.Pp
707For URIs, use
708.Ic \&Lk
709instead, and
710.Ic \&In
711for
712.Dq #include
713directives.
714Never wrap
715.Ic \&Ar
716in
717.Ic \&Aq .
718.Pp
719Since
720.Ic \&Aq
721usually renders with non-ASCII characters in non-ASCII output modes,
722do not use it where the ASCII characters
723.Sq <
724and
725.Sq >
726are required as syntax elements.
727Instead, use these characters directly in such cases, combining them
728with the macros
729.Ic \&Pf ,
730.Ic \&Ns ,
731or
732.Ic \&Eo
733as needed.
734.Pp
735See also
736.Ic \&Ao .
737.Tg Ar
738.It Ic \&Ar Op Ar placeholder ...
739Command arguments.
740If an argument is not provided, the string
741.Dq file ...\&
742is used as a default.
743.Pp
744Examples:
745.Dl ".Fl o Ar file"
746.Dl ".Ar"
747.Dl ".Ar arg1 , arg2 ."
748.Pp
749The arguments to the
750.Ic \&Ar
751macro are names and placeholders for command arguments;
752for fixed strings to be passed verbatim as arguments, use
753.Ic \&Fl
754or
755.Ic \&Cm .
756.Tg At
757.It Ic \&At Op Ar version
758Formats an
759.At
760version.
761Accepts one optional argument:
762.Pp
763.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
764.It Cm v[1-7] | 32v
765A version of
766.At .
767.It Cm III
768.At III .
769.It Cm V | V.[1-4]
770A version of
771.At V .
772.El
773.Pp
774Note that these arguments do not begin with a hyphen.
775.Pp
776Examples:
777.Dl \&.At
778.Dl \&.At III
779.Dl \&.At V.1
780.Pp
781See also
782.Ic \&Bsx ,
783.Ic \&Bx ,
784.Ic \&Dx ,
785.Ic \&Fx ,
786.Ic \&Nx ,
787and
788.Ic \&Ox .
789.It Ic \&Bc
790Close a
791.Ic \&Bo
792block.
793Does not have any tail arguments.
794.Tg Bd
795.It Ic \&Bd Fl Ns Ar type Oo Fl offset Ar width Oc Op Fl compact
796Begin a display block.
797Display blocks are used to select a different indentation and
798justification than the one used by the surrounding text.
799They may contain both macro lines and text lines.
800By default, a display block is preceded by a vertical space.
801.Pp
802The
803.Ar type
804must be one of the following:
805.Bl -tag -width 13n -offset indent
806.It Fl centered
807Produce one output line from each input line, and center-justify each line.
808Using this display type is not recommended; many
809.Nm
810implementations render it poorly.
811.It Fl filled
812Change the positions of line breaks to fill each line, and left- and
813right-justify the resulting block.
814.It Fl literal
815Produce one output line from each input line,
816and do not justify the block at all.
817Preserve white space as it appears in the input.
818Always use a constant-width font.
819Use this for displaying source code.
820.It Fl ragged
821Change the positions of line breaks to fill each line, and left-justify
822the resulting block.
823.It Fl unfilled
824The same as
825.Fl literal ,
826but using the same font as for normal text, which is a variable width font
827if supported by the output device.
828.El
829.Pp
830The
831.Ar type
832must be provided first.
833Additional arguments may follow:
834.Bl -tag -width 13n -offset indent
835.It Fl offset Ar width
836Indent the display by the
837.Ar width ,
838which may be one of the following:
839.Bl -item
840.It
841One of the pre-defined strings
842.Cm indent ,
843the width of a standard indentation (six constant width characters);
844.Cm indent-two ,
845twice
846.Cm indent ;
847.Cm left ,
848which has no effect;
849.Cm right ,
850which justifies to the right margin; or
851.Cm center ,
852which aligns around an imagined center axis.
853.It
854A macro invocation, which selects a predefined width
855associated with that macro.
856The most popular is the imaginary macro
857.Ar \&Ds ,
858which resolves to
859.Sy 6n .
860.It
861A scaling width as described in
862.Xr roff 7 .
863.It
864An arbitrary string, which indents by the length of this string.
865.El
866.Pp
867When the argument is missing,
868.Fl offset
869is ignored.
870.It Fl compact
871Do not assert vertical space before the display.
872.El
873.Pp
874Examples:
875.Bd -literal -offset indent
876\&.Bd \-literal \-offset indent \-compact
877   Hello       world.
878\&.Ed
879.Ed
880.Pp
881See also
882.Ic \&D1
883and
884.Ic \&Dl .
885.Tg Bf
886.It Ic \&Bf Fl emphasis | literal | symbolic | Cm \&Em | \&Li | \&Sy
887Change the font mode for a scoped block of text.
888The
889.Fl emphasis
890and
891.Cm \&Em
892argument are equivalent, as are
893.Fl symbolic
894and
895.Cm \&Sy ,
896and
897.Fl literal
898and
899.Cm \&Li .
900Without an argument, this macro does nothing.
901The font mode continues until broken by a new font mode in a nested
902scope or
903.Ic \&Ef
904is encountered.
905.Pp
906See also
907.Ic \&Li ,
908.Ic \&Ef ,
909.Ic \&Em ,
910and
911.Ic \&Sy .
912.Tg Bk
913.It Ic \&Bk Fl words
914For each macro, keep its output together on the same output line,
915until the end of the macro or the end of the input line is reached,
916whichever comes first.
917Line breaks in text lines are unaffected.
918.Pp
919The
920.Fl words
921argument is required; additional arguments are ignored.
922.Pp
923The following example will not break within each
924.Ic \&Op
925macro line:
926.Bd -literal -offset indent
927\&.Bk \-words
928\&.Op Fl f Ar flags
929\&.Op Fl o Ar output
930\&.Ek
931.Ed
932.Pp
933Be careful in using over-long lines within a keep block!
934Doing so will clobber the right margin.
935.Tg Bl
936.It Xo
937.Ic \&Bl
938.Fl Ns Ar type
939.Op Fl width Ar val
940.Op Fl offset Ar val
941.Op Fl compact
942.Op Ar col ...
943.Xc
944Begin a list.
945Lists consist of items specified using the
946.Ic \&It
947macro, containing a head or a body or both.
948.Pp
949The list
950.Ar type
951is mandatory and must be specified first.
952The
953.Fl width
954and
955.Fl offset
956arguments accept macro names as described for
957.Ic \&Bd
958.Fl offset ,
959scaling widths as described in
960.Xr roff 7 ,
961or use the length of the given string.
962The
963.Fl offset
964is a global indentation for the whole list, affecting both item heads
965and bodies.
966For those list types supporting it, the
967.Fl width
968argument requests an additional indentation of item bodies,
969to be added to the
970.Fl offset .
971Unless the
972.Fl compact
973argument is specified, list entries are separated by vertical space.
974.Pp
975A list must specify one of the following list types:
976.Bl -tag -width 12n -offset indent
977.It Fl bullet
978No item heads can be specified, but a bullet will be printed at the head
979of each item.
980Item bodies start on the same output line as the bullet
981and are indented according to the
982.Fl width
983argument.
984.It Fl column
985A columnated list.
986The
987.Fl width
988argument has no effect; instead, the string length of each argument
989specifies the width of one column.
990If the first line of the body of a
991.Fl column
992list is not an
993.Ic \&It
994macro line,
995.Ic \&It
996contexts spanning one input line each are implied until an
997.Ic \&It
998macro line is encountered, at which point items start being interpreted as
999described in the
1000.Ic \&It
1001documentation.
1002.It Fl dash
1003Like
1004.Fl bullet ,
1005except that dashes are used in place of bullets.
1006.It Fl diag
1007Like
1008.Fl inset ,
1009except that item heads are not parsed for macro invocations.
1010Most often used in the
1011.Em DIAGNOSTICS
1012section with error constants in the item heads.
1013.It Fl enum
1014A numbered list.
1015No item heads can be specified.
1016Formatted like
1017.Fl bullet ,
1018except that ordinal numbers are used in place of bullets,
1019starting at 1.
1020.It Fl hang
1021Like
1022.Fl tag ,
1023except that the first lines of item bodies are not indented, but follow
1024the item heads like in
1025.Fl inset
1026lists.
1027.It Fl hyphen
1028Synonym for
1029.Fl dash .
1030.It Fl inset
1031Item bodies follow items heads on the same line, using normal inter-word
1032spacing.
1033Bodies are not indented, and the
1034.Fl width
1035argument is ignored.
1036.It Fl item
1037No item heads can be specified, and none are printed.
1038Bodies are not indented, and the
1039.Fl width
1040argument is ignored.
1041.It Fl ohang
1042Item bodies start on the line following item heads and are not indented.
1043The
1044.Fl width
1045argument is ignored.
1046.It Fl tag
1047Item bodies are indented according to the
1048.Fl width
1049argument.
1050When an item head fits inside the indentation, the item body follows
1051this head on the same output line.
1052Otherwise, the body starts on the output line following the head.
1053.El
1054.Pp
1055Lists may be nested within lists and displays.
1056Nesting of
1057.Fl column
1058and
1059.Fl enum
1060lists may not be portable.
1061.Pp
1062See also
1063.Ic \&El
1064and
1065.Ic \&It .
1066.It Ic \&Bo Ar block
1067Begin a block enclosed by square brackets.
1068Does not have any head arguments.
1069.Pp
1070Examples:
1071.Bd -literal -offset indent -compact
1072\&.Bo 1 ,
1073\&.Dv BUFSIZ \&Bc
1074.Ed
1075.Pp
1076See also
1077.Ic \&Bq .
1078.Tg Bq
1079.It Ic \&Bq Ar line
1080Encloses its arguments in square brackets.
1081.Pp
1082Examples:
1083.Dl \&.Bq 1 , \&Dv BUFSIZ
1084.Pp
1085.Em Remarks :
1086this macro is sometimes abused to emulate optional arguments for
1087commands; the correct macros to use for this purpose are
1088.Ic \&Op ,
1089.Ic \&Oo ,
1090and
1091.Ic \&Oc .
1092.Pp
1093See also
1094.Ic \&Bo .
1095.It Ic \&Brc
1096Close a
1097.Ic \&Bro
1098block.
1099Does not have any tail arguments.
1100.It Ic \&Bro Ar block
1101Begin a block enclosed by curly braces.
1102Does not have any head arguments.
1103.Pp
1104Examples:
1105.Bd -literal -offset indent -compact
1106\&.Bro 1 , ... ,
1107\&.Va n \&Brc
1108.Ed
1109.Pp
1110See also
1111.Ic \&Brq .
1112.Tg Brq
1113.It Ic \&Brq Ar line
1114Encloses its arguments in curly braces.
1115.Pp
1116Examples:
1117.Dl \&.Brq 1 , ... , \&Va n
1118.Pp
1119See also
1120.Ic \&Bro .
1121.Tg Bsx
1122.It Ic \&Bsx Op Ar version
1123Format the
1124.Bsx
1125version provided as an argument, or a default value if
1126no argument is provided.
1127.Pp
1128Examples:
1129.Dl \&.Bsx 1.0
1130.Dl \&.Bsx
1131.Pp
1132See also
1133.Ic \&At ,
1134.Ic \&Bx ,
1135.Ic \&Dx ,
1136.Ic \&Fx ,
1137.Ic \&Nx ,
1138and
1139.Ic \&Ox .
1140.It Ic \&Bt
1141Supported only for compatibility, do not use this in new manuals.
1142Prints
1143.Dq is currently in beta test.
1144.Tg Bx
1145.It Ic \&Bx Op Ar version Op Ar variant
1146Format the
1147.Bx
1148version provided as an argument, or a default value if no
1149argument is provided.
1150.Pp
1151Examples:
1152.Dl \&.Bx 4.3 Tahoe
1153.Dl \&.Bx 4.4
1154.Dl \&.Bx
1155.Pp
1156See also
1157.Ic \&At ,
1158.Ic \&Bsx ,
1159.Ic \&Dx ,
1160.Ic \&Fx ,
1161.Ic \&Nx ,
1162and
1163.Ic \&Ox .
1164.Tg Cd
1165.It Ic \&Cd Ar line
1166Kernel configuration declaration.
1167This denotes strings accepted by
1168.Xr config 8 .
1169It is most often used in section 4 manual pages.
1170.Pp
1171Examples:
1172.Dl \&.Cd device le0 at scode?
1173.Pp
1174.Em Remarks :
1175this macro is commonly abused by using quoted literals to retain
1176whitespace and align consecutive
1177.Ic \&Cd
1178declarations.
1179This practise is discouraged.
1180.Tg Cm
1181.It Ic \&Cm Ar keyword ...
1182Command modifiers.
1183Typically used for fixed strings passed as arguments to interactive
1184commands, to commands in interpreted scripts, or to configuration
1185file directives, unless
1186.Ic \&Fl
1187is more appropriate.
1188.Pp
1189Examples:
1190.Dl ".Nm mt Fl f Ar device Cm rewind"
1191.Dl ".Nm ps Fl o Cm pid , Ns Cm command"
1192.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
1193.Dl ".Ic set Fl o Cm vi"
1194.Dl ".Ic lookup Cm file bind"
1195.Dl ".Ic permit Ar identity Op Cm as Ar target"
1196.Tg D1
1197.It Ic \&D1 Ar line
1198One-line indented display.
1199This is formatted by the default rules and is useful for simple indented
1200statements.
1201It is followed by a newline.
1202.Pp
1203Examples:
1204.Dl \&.D1 \&Fl abcdefgh
1205.Pp
1206See also
1207.Ic \&Bd
1208and
1209.Ic \&Dl .
1210.It Ic \&Db
1211This macro is obsolete.
1212No replacement is needed.
1213It is ignored by
1214.Xr mandoc 1
1215and groff including its arguments.
1216It was formerly used to toggle a debugging mode.
1217.It Ic \&Dc
1218Close a
1219.Ic \&Do
1220block.
1221Does not have any tail arguments.
1222.Tg Dd
1223.It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year
1224Document date for display in the page footer,
1225by convention the date of the last change.
1226This is the mandatory first macro of any
1227.Nm
1228manual.
1229.Pp
1230The
1231.Ar month
1232is the full English month name, the
1233.Ar day
1234is an integer number, and the
1235.Ar year
1236is the full four-digit year.
1237.Pp
1238Other arguments are not portable; the
1239.Xr mandoc 1
1240utility handles them as follows:
1241.Bl -dash -offset 3n -compact
1242.It
1243To have the date automatically filled in by the
1244.Ox
1245version of
1246.Xr cvs 1 ,
1247the special string
1248.Dq $\&Mdocdate$
1249can be given as an argument.
1250.It
1251The traditional, purely numeric
1252.Xr man 7
1253format
1254.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day
1255is accepted, too.
1256.It
1257If a date string cannot be parsed, it is used verbatim.
1258.It
1259If no date string is given, the current date is used.
1260.El
1261.Pp
1262Examples:
1263.Dl \&.Dd $\&Mdocdate$
1264.Dl \&.Dd $\&Mdocdate: July 2 2018$
1265.Dl \&.Dd July 2, 2018
1266.Pp
1267See also
1268.Ic \&Dt
1269and
1270.Ic \&Os .
1271.Tg Dl
1272.It Ic \&Dl Ar line
1273One-line indented display.
1274This is formatted as literal text and is useful for commands and
1275invocations.
1276It is followed by a newline.
1277.Pp
1278Examples:
1279.Dl \&.Dl % mandoc mdoc.7 \e(ba less
1280.Pp
1281See also
1282.Ic \&Ql ,
1283.Ic \&Bd Fl literal ,
1284and
1285.Ic \&D1 .
1286.It Ic \&Do Ar block
1287Begin a block enclosed by double quotes.
1288Does not have any head arguments.
1289.Pp
1290Examples:
1291.Bd -literal -offset indent -compact
1292\&.Do
1293April is the cruellest month
1294\&.Dc
1295\e(em T.S. Eliot
1296.Ed
1297.Pp
1298See also
1299.Ic \&Dq .
1300.Tg Dq
1301.It Ic \&Dq Ar line
1302Encloses its arguments in
1303.Dq typographic
1304double-quotes.
1305.Pp
1306Examples:
1307.Bd -literal -offset indent -compact
1308\&.Dq April is the cruellest month
1309\e(em T.S. Eliot
1310.Ed
1311.Pp
1312See also
1313.Ic \&Qq ,
1314.Ic \&Sq ,
1315and
1316.Ic \&Do .
1317.Tg Dt
1318.It Ic \&Dt Ar TITLE section Op Ar arch
1319Document title for display in the page header.
1320This is the mandatory second macro of any
1321.Nm
1322file.
1323.Pp
1324Its arguments are as follows:
1325.Bl -tag -width section -offset 2n
1326.It Ar TITLE
1327The document's title (name), defaulting to
1328.Dq UNTITLED
1329if unspecified.
1330To achieve a uniform appearance of page header lines,
1331it should by convention be all caps.
1332.It Ar section
1333The manual section.
1334This may be one of
1335.Cm 1
1336.Pq General Commands ,
1337.Cm 2
1338.Pq System Calls ,
1339.Cm 3
1340.Pq Library Functions ,
1341.Cm 3p
1342.Pq Perl Library ,
1343.Cm 4
1344.Pq Device Drivers ,
1345.Cm 5
1346.Pq File Formats ,
1347.Cm 6
1348.Pq Games ,
1349.Cm 7
1350.Pq Miscellaneous Information ,
1351.Cm 8
1352.Pq System Manager's Manual ,
1353or
1354.Cm 9
1355.Pq Kernel Developer's Manual .
1356It should correspond to the manual's filename suffix and defaults to
1357the empty string if unspecified.
1358.It Ar arch
1359This specifies the machine architecture a manual page applies to,
1360where relevant, for example
1361.Cm alpha ,
1362.Cm amd64 ,
1363.Cm i386 ,
1364or
1365.Cm sparc64 .
1366The list of valid architectures varies by operating system.
1367.El
1368.Pp
1369Examples:
1370.Dl \&.Dt FOO 1
1371.Dl \&.Dt FOO 9 i386
1372.Pp
1373See also
1374.Ic \&Dd
1375and
1376.Ic \&Os .
1377.Tg Dv
1378.It Ic \&Dv Ar identifier ...
1379Defined variables such as preprocessor constants, constant symbols,
1380enumeration values, and so on.
1381.Pp
1382Examples:
1383.Dl \&.Dv NULL
1384.Dl \&.Dv BUFSIZ
1385.Dl \&.Dv STDOUT_FILENO
1386.Pp
1387See also
1388.Ic \&Er
1389and
1390.Ic \&Ev
1391for special-purpose constants,
1392.Ic \&Va
1393for variable symbols, and
1394.Ic \&Fd
1395for listing preprocessor variable definitions in the
1396.Em SYNOPSIS .
1397.Tg Dx
1398.It Ic \&Dx Op Ar version
1399Format the
1400.Dx
1401version provided as an argument, or a default
1402value if no argument is provided.
1403.Pp
1404Examples:
1405.Dl \&.Dx 2.4.1
1406.Dl \&.Dx
1407.Pp
1408See also
1409.Ic \&At ,
1410.Ic \&Bsx ,
1411.Ic \&Bx ,
1412.Ic \&Fx ,
1413.Ic \&Nx ,
1414and
1415.Ic \&Ox .
1416.It Ic \&Ec Op Ar closing_delimiter
1417Close a scope started by
1418.Ic \&Eo .
1419.Pp
1420The
1421.Ar closing_delimiter
1422argument is used as the enclosure tail, for example, specifying \e(rq
1423will emulate
1424.Ic \&Dc .
1425.It Ic \&Ed
1426End a display context started by
1427.Ic \&Bd .
1428.It Ic \&Ef
1429End a font mode context started by
1430.Ic \&Bf .
1431.It Ic \&Ek
1432End a keep context started by
1433.Ic \&Bk .
1434.It Ic \&El
1435End a list context started by
1436.Ic \&Bl .
1437See also
1438.Ic \&It .
1439.Tg Em
1440.It Ic \&Em Ar word ...
1441Request an italic font.
1442If the output device does not provide that, underline.
1443.Pp
1444This is most often used for stress emphasis (not to be confused with
1445importance, see
1446.Ic \&Sy ) .
1447In the rare cases where none of the semantic markup macros fit,
1448it can also be used for technical terms and placeholders, except
1449that for syntax elements,
1450.Ic \&Sy
1451and
1452.Ic \&Ar
1453are preferred, respectively.
1454.Pp
1455Examples:
1456.Bd -literal -compact -offset indent
1457Selected lines are those
1458\&.Em not
1459matching any of the specified patterns.
1460Some of the functions use a
1461\&.Em hold space
1462to save the pattern space for subsequent retrieval.
1463.Ed
1464.Pp
1465See also
1466.Ic \&No ,
1467.Ic \&Ql ,
1468and
1469.Ic \&Sy .
1470.It Ic \&En Ar word ...
1471This macro is obsolete.
1472Use
1473.Ic \&Eo
1474or any of the other enclosure macros.
1475.Pp
1476It encloses its argument in the delimiters specified by the last
1477.Ic \&Es
1478macro.
1479.Tg Eo
1480.It Ic \&Eo Op Ar opening_delimiter
1481An arbitrary enclosure.
1482The
1483.Ar opening_delimiter
1484argument is used as the enclosure head, for example, specifying \e(lq
1485will emulate
1486.Ic \&Do .
1487.Tg Er
1488.It Ic \&Er Ar identifier ...
1489Error constants for definitions of the
1490.Va errno
1491libc global variable.
1492This is most often used in section 2 and 3 manual pages.
1493.Pp
1494Examples:
1495.Dl \&.Er EPERM
1496.Dl \&.Er ENOENT
1497.Pp
1498See also
1499.Ic \&Dv
1500for general constants.
1501.It Ic \&Es Ar opening_delimiter closing_delimiter
1502This macro is obsolete.
1503Use
1504.Ic \&Eo
1505or any of the other enclosure macros.
1506.Pp
1507It takes two arguments, defining the delimiters to be used by subsequent
1508.Ic \&En
1509macros.
1510.Tg Ev
1511.It Ic \&Ev Ar identifier ...
1512Environmental variables such as those specified in
1513.Xr environ 7 .
1514.Pp
1515Examples:
1516.Dl \&.Ev DISPLAY
1517.Dl \&.Ev PATH
1518.Pp
1519See also
1520.Ic \&Dv
1521for general constants.
1522.Tg Ex
1523.It Ic \&Ex Fl std Op Ar utility ...
1524Insert a standard sentence regarding command exit values of 0 on success
1525and >0 on failure.
1526This is most often used in section 1, 6, and 8 manual pages.
1527.Pp
1528If
1529.Ar utility
1530is not specified, the document's name set by
1531.Ic \&Nm
1532is used.
1533Multiple
1534.Ar utility
1535arguments are treated as separate utilities.
1536.Pp
1537See also
1538.Ic \&Rv .
1539.Tg Fa
1540.It Ic \&Fa Ar argument ...
1541Function argument or parameter.
1542Each argument may be a name and a type (recommended for the
1543.Em SYNOPSIS
1544section), a name alone (for function invocations),
1545or a type alone (for function prototypes).
1546If both a type and a name are given or if the type consists of multiple
1547words, all words belonging to the same function argument have to be
1548given in a single argument to the
1549.Ic \&Fa
1550macro.
1551.Pp
1552This macro is also used to specify the field name of a structure.
1553.Pp
1554Most often, the
1555.Ic \&Fa
1556macro is used in the
1557.Em SYNOPSIS
1558within
1559.Ic \&Fo
1560blocks when documenting multi-line function prototypes.
1561If invoked with multiple arguments, the arguments are separated by a
1562comma.
1563Furthermore, if the following macro is another
1564.Ic \&Fa ,
1565the last argument will also have a trailing comma.
1566.Pp
1567Examples:
1568.Dl \&.Fa \(dqconst char *p\(dq
1569.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
1570.Dl \&.Fa \(dqchar *\(dq size_t
1571.Pp
1572See also
1573.Ic \&Fo .
1574.It Ic \&Fc
1575End a function context started by
1576.Ic \&Fo .
1577.Tg Fd
1578.It Ic \&Fd Pf # Ar directive Op Ar argument ...
1579Preprocessor directive, in particular for listing it in the
1580.Em SYNOPSIS .
1581Historically, it was also used to document include files.
1582The latter usage has been deprecated in favour of
1583.Ic \&In .
1584.Pp
1585Examples:
1586.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler
1587.Dl \&.Fd #define SIO_MAXNFDS
1588.Dl \&.Fd #ifdef FS_DEBUG
1589.Dl \&.Ft void
1590.Dl \&.Fn dbg_open \(dqconst char *\(dq
1591.Dl \&.Fd #endif
1592.Pp
1593See also
1594.Sx MANUAL STRUCTURE ,
1595.Ic \&In ,
1596and
1597.Ic \&Dv .
1598.Tg Fl
1599.It Ic \&Fl Op Ar word ...
1600Command-line flag or option.
1601Used when listing arguments to command-line utilities.
1602For each argument, prints an ASCII hyphen-minus character
1603.Sq \- ,
1604immediately followed by the argument.
1605If no arguments are provided, a hyphen-minus is printed followed by a space.
1606If the argument is a macro, a hyphen-minus is prefixed
1607to the subsequent macro output.
1608.Pp
1609Examples:
1610.Dl ".Nm du Op Fl H | L | P"
1611.Dl ".Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
1612.Dl ".Nm route Cm add Fl inet Ar destination gateway"
1613.Dl ".Nm locate.updatedb Op Fl \e-fcodes Ns = Ns Ar dbfile"
1614.Dl ".Nm aucat Fl o Fl"
1615.Dl ".Nm kill Fl Ar signal_number"
1616.Pp
1617For GNU-style long options, escaping the additional hyphen-minus is not
1618strictly required, but may be safer with future versions of GNU troff; see
1619.Xr mandoc_char 7
1620for details.
1621.Pp
1622See also
1623.Ic \&Cm .
1624.Tg Fn
1625.It Ic \&Fn Ar funcname Op Ar argument ...
1626A function name.
1627.Pp
1628Function arguments are surrounded in parenthesis and
1629are delimited by commas.
1630If no arguments are specified, blank parenthesis are output.
1631In the
1632.Em SYNOPSIS
1633section, this macro starts a new output line,
1634and a blank line is automatically inserted between function definitions.
1635.Pp
1636Examples:
1637.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
1638.Dl \&.Fn funcname \(dqint arg0\(dq
1639.Dl \&.Fn funcname arg0
1640.Bd -literal -offset indent
1641\&.Ft functype
1642\&.Fn funcname
1643.Ed
1644.Pp
1645When referring to a function documented in another manual page, use
1646.Ic \&Xr
1647instead.
1648See also
1649.Sx MANUAL STRUCTURE ,
1650.Ic \&Fo ,
1651and
1652.Ic \&Ft .
1653.Tg Fo
1654.It Ic \&Fo Ar funcname
1655Begin a function block.
1656This is a multi-line version of
1657.Ic \&Fn .
1658.Pp
1659Invocations usually occur in the following context:
1660.Bd -ragged -offset indent
1661.Pf \. Ic \&Ft Ar functype
1662.br
1663.Pf \. Ic \&Fo Ar funcname
1664.br
1665.Pf \. Ic \&Fa Qq Ar argtype Ar argname
1666.br
1667\&.\.\.
1668.br
1669.Pf \. Ic \&Fc
1670.Ed
1671.Pp
1672A
1673.Ic \&Fo
1674scope is closed by
1675.Ic \&Fc .
1676.Pp
1677See also
1678.Sx MANUAL STRUCTURE ,
1679.Ic \&Fa ,
1680.Ic \&Fc ,
1681and
1682.Ic \&Ft .
1683.It Ic \&Fr Ar number
1684This macro is obsolete.
1685No replacement markup is needed.
1686.Pp
1687It was used to show numerical function return values in an italic font.
1688.Tg Ft
1689.It Ic \&Ft Ar functype
1690A function type.
1691.Pp
1692In the
1693.Em SYNOPSIS
1694section, a new output line is started after this macro.
1695.Pp
1696Examples:
1697.Dl \&.Ft int
1698.Bd -literal -offset indent -compact
1699\&.Ft functype
1700\&.Fn funcname
1701.Ed
1702.Pp
1703See also
1704.Sx MANUAL STRUCTURE ,
1705.Ic \&Fn ,
1706and
1707.Ic \&Fo .
1708.Tg Fx
1709.It Ic \&Fx Op Ar version
1710Format the
1711.Fx
1712version provided as an argument, or a default value
1713if no argument is provided.
1714.Pp
1715Examples:
1716.Dl \&.Fx 7.1
1717.Dl \&.Fx
1718.Pp
1719See also
1720.Ic \&At ,
1721.Ic \&Bsx ,
1722.Ic \&Bx ,
1723.Ic \&Dx ,
1724.Ic \&Nx ,
1725and
1726.Ic \&Ox .
1727.It Ic \&Hf Ar filename
1728This macro is not implemented in
1729.Xr mandoc 1 .
1730It was used to include the contents of a (header) file literally.
1731.Tg Ic
1732.It Ic \&Ic Ar keyword ...
1733Internal or interactive command, or configuration instruction
1734in a configuration file.
1735See also
1736.Ic \&Cm .
1737.Pp
1738Examples:
1739.Dl \&.Ic :wq
1740.Dl \&.Ic hash
1741.Dl \&.Ic alias
1742.Pp
1743Note that using
1744.Ic \&Ql ,
1745.Ic \&Dl ,
1746or
1747.Ic \&Bd Fl literal
1748is preferred for displaying code samples; the
1749.Ic \&Ic
1750macro is used when referring to an individual command name.
1751.Tg In
1752.It Ic \&In Ar filename
1753The name of an include file.
1754This macro is most often used in section 2, 3, and 9 manual pages.
1755.Pp
1756When invoked as the first macro on an input line in the
1757.Em SYNOPSIS
1758section, the argument is displayed in angle brackets
1759and preceded by
1760.Qq #include ,
1761and a blank line is inserted in front if there is a preceding
1762function declaration.
1763In other sections, it only encloses its argument in angle brackets
1764and causes no line break.
1765.Pp
1766Examples:
1767.Dl \&.In sys/types.h
1768.Pp
1769See also
1770.Sx MANUAL STRUCTURE .
1771.Tg It
1772.It Ic \&It Op Ar head
1773A list item.
1774The syntax of this macro depends on the list type.
1775.Pp
1776Lists
1777of type
1778.Fl hang ,
1779.Fl ohang ,
1780.Fl inset ,
1781and
1782.Fl diag
1783have the following syntax:
1784.Pp
1785.D1 Pf \. Ic \&It Ar args
1786.Pp
1787Lists of type
1788.Fl bullet ,
1789.Fl dash ,
1790.Fl enum ,
1791.Fl hyphen
1792and
1793.Fl item
1794have the following syntax:
1795.Pp
1796.D1 Pf \. Ic \&It
1797.Pp
1798with subsequent lines interpreted within the scope of the
1799.Ic \&It
1800until either a closing
1801.Ic \&El
1802or another
1803.Ic \&It .
1804.Pp
1805The
1806.Fl tag
1807list has the following syntax:
1808.Pp
1809.D1 Pf \. Ic \&It Op Cm args
1810.Pp
1811Subsequent lines are interpreted as with
1812.Fl bullet
1813and family.
1814The line arguments correspond to the list's left-hand side; body
1815arguments correspond to the list's contents.
1816.Pp
1817The
1818.Fl column
1819list is the most complicated.
1820Its syntax is as follows:
1821.Pp
1822.D1 Pf \. Ic \&It Ar cell Op Ic \&Ta Ar cell ...
1823.D1 Pf \. Ic \&It Ar cell Op <TAB> Ar cell ...
1824.Pp
1825The arguments consist of one or more lines of text and macros
1826representing a complete table line.
1827Cells within the line are delimited by the special
1828.Ic \&Ta
1829block macro or by literal tab characters.
1830.Pp
1831Using literal tabs is strongly discouraged because they are very
1832hard to use correctly and
1833.Nm
1834code using them is very hard to read.
1835In particular, a blank character is syntactically significant
1836before and after the literal tab character.
1837If a word precedes or follows the tab without an intervening blank,
1838that word is never interpreted as a macro call, but always output
1839literally.
1840.Pp
1841The tab cell delimiter may only be used within the
1842.Ic \&It
1843line itself; on following lines, only the
1844.Ic \&Ta
1845macro can be used to delimit cells, and portability requires that
1846.Ic \&Ta
1847is called by other macros: some parsers do not recognize it when
1848it appears as the first macro on a line.
1849.Pp
1850Note that quoted strings may span tab-delimited cells on an
1851.Ic \&It
1852line.
1853For example,
1854.Pp
1855.Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&;
1856.Pp
1857will preserve the whitespace before both commas,
1858but not the whitespace before the semicolon.
1859.Pp
1860See also
1861.Ic \&Bl .
1862.Tg Lb
1863.It Ic \&Lb Cm lib Ns Ar name
1864Specify a library.
1865.Pp
1866The
1867.Ar name
1868parameter may be a system library, such as
1869.Cm z
1870or
1871.Cm pam ,
1872in which case a small library description is printed next to the linker
1873invocation; or a custom library, in which case the library name is
1874printed in quotes.
1875This is most commonly used in the
1876.Em SYNOPSIS
1877section as described in
1878.Sx MANUAL STRUCTURE .
1879.Pp
1880Examples:
1881.Dl \&.Lb libz
1882.Dl \&.Lb libmandoc
1883.Tg Li
1884.It Ic \&Li Ar word ...
1885Request a typewriter (literal) font.
1886Deprecated because on terminal output devices, this is usually
1887indistinguishable from normal text.
1888For literal displays, use
1889.Ic \&Ql Pq in-line ,
1890.Ic \&Dl Pq single line ,
1891or
1892.Ic \&Bd Fl literal Pq multi-line
1893instead.
1894.Tg Lk
1895.It Ic \&Lk Ar uri Op Ar display_name
1896Format a hyperlink.
1897.Pp
1898Examples:
1899.Dl \&.Lk https://bsd.lv \(dqThe BSD.lv Project\(dq
1900.Dl \&.Lk https://bsd.lv
1901.Pp
1902See also
1903.Ic \&Mt .
1904.It Ic \&Lp
1905Deprecated synonym for
1906.Ic \&Pp .
1907.Tg Ms
1908.It Ic \&Ms Ar name
1909Display a mathematical symbol.
1910.Pp
1911Examples:
1912.Dl \&.Ms sigma
1913.Dl \&.Ms aleph
1914.Tg Mt
1915.It Ic \&Mt Ar localpart Ns @ Ns Ar domain
1916Format a
1917.Dq mailto:
1918hyperlink.
1919.Pp
1920Examples:
1921.Dl \&.Mt discuss@manpages.bsd.lv
1922.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
1923.Tg Nd
1924.It Ic \&Nd Ar line
1925A one line description of the manual's content.
1926This is the mandatory last macro of the
1927.Em NAME
1928section and not appropriate for other sections.
1929.Pp
1930Examples:
1931.Dl Pf . Ic \&Nd mdoc language reference
1932.Dl Pf . Ic \&Nd format and display UNIX manuals
1933.Pp
1934The
1935.Ic \&Nd
1936macro technically accepts child macros and terminates with a subsequent
1937.Ic \&Sh
1938invocation.
1939Do not assume this behaviour: some
1940.Xr whatis 1
1941database generators are not smart enough to parse more than the line
1942arguments and will display macros verbatim.
1943.Pp
1944See also
1945.Ic \&Nm .
1946.Tg Nm
1947.It Ic \&Nm Op Ar name
1948The name of the manual page, or \(em in particular in section 1, 6,
1949and 8 pages \(em of an additional command or feature documented in
1950the manual page.
1951When first invoked, the
1952.Ic \&Nm
1953macro expects a single argument, the name of the manual page.
1954Usually, the first invocation happens in the
1955.Em NAME
1956section of the page.
1957The specified name will be remembered and used whenever the macro is
1958called again without arguments later in the page.
1959The
1960.Ic \&Nm
1961macro uses
1962.Sx Block full-implicit
1963semantics when invoked as the first macro on an input line in the
1964.Em SYNOPSIS
1965section; otherwise, it uses ordinary
1966.Sx In-line
1967semantics.
1968.Pp
1969Examples:
1970.Bd -literal -offset indent
1971\&.Sh SYNOPSIS
1972\&.Nm cat
1973\&.Op Fl benstuv
1974\&.Op Ar
1975.Ed
1976.Pp
1977In the
1978.Em SYNOPSIS
1979of section 2, 3 and 9 manual pages, use the
1980.Ic \&Fn
1981macro rather than
1982.Ic \&Nm
1983to mark up the name of the manual page.
1984.Tg No
1985.It Ic \&No Ar word ...
1986Normal text.
1987Closes the scope of any preceding in-line macro.
1988When used after physical formatting macros like
1989.Ic \&Em
1990or
1991.Ic \&Sy ,
1992switches back to the standard font face and weight.
1993Can also be used to embed plain text strings in macro lines
1994using semantic annotation macros.
1995.Pp
1996Examples:
1997.Dl ".Em italic , Sy bold , No and roman"
1998.Bd -literal -offset indent
1999\&.Sm off
2000\&.Cm :C No / Ar pattern No / Ar replacement No /
2001\&.Sm on
2002.Ed
2003.Pp
2004See also
2005.Ic \&Em ,
2006.Ic \&Ql ,
2007and
2008.Ic \&Sy .
2009.Tg Ns
2010.It Ic \&Ns
2011Suppress a space between the output of the preceding macro
2012and the following text or macro.
2013Following invocation, input is interpreted as normal text
2014just like after an
2015.Ic \&No
2016macro.
2017.Pp
2018This has no effect when invoked at the start of a macro line.
2019.Pp
2020Examples:
2021.Dl ".Ar name Ns = Ns Ar value"
2022.Dl ".Cm :M Ns Ar pattern"
2023.Dl ".Fl o Ns Ar output"
2024.Pp
2025See also
2026.Ic \&No
2027and
2028.Ic \&Sm .
2029.Tg Nx
2030.It Ic \&Nx Op Ar version
2031Format the
2032.Nx
2033version provided as an argument, or a default value if
2034no argument is provided.
2035.Pp
2036Examples:
2037.Dl \&.Nx 5.01
2038.Dl \&.Nx
2039.Pp
2040See also
2041.Ic \&At ,
2042.Ic \&Bsx ,
2043.Ic \&Bx ,
2044.Ic \&Dx ,
2045.Ic \&Fx ,
2046and
2047.Ic \&Ox .
2048.It Ic \&Oc
2049Close multi-line
2050.Ic \&Oo
2051context.
2052.It Ic \&Oo Ar block
2053Multi-line version of
2054.Ic \&Op .
2055.Pp
2056Examples:
2057.Bd -literal -offset indent -compact
2058\&.Oo
2059\&.Op Fl flag Ns Ar value
2060\&.Oc
2061.Ed
2062.Tg Op
2063.It Ic \&Op Ar line
2064Optional part of a command line.
2065Prints the argument(s) in brackets.
2066This is most often used in the
2067.Em SYNOPSIS
2068section of section 1 and 8 manual pages.
2069.Pp
2070Examples:
2071.Dl \&.Op \&Fl a \&Ar b
2072.Dl \&.Op \&Ar a | b
2073.Pp
2074See also
2075.Ic \&Oo .
2076.Tg Os
2077.It Ic \&Os Op Ar footer text
2078The mandatory third macro of every
2079.Nm
2080file.
2081Usually, do not specify any arguments,
2082in particular not the operating system name and/or version.
2083.Pp
2084If no argument is given,
2085.Xr mandoc 1
2086prints its
2087.Fl Ios
2088argument in the page footer, or
2089.Fa sysname
2090and
2091.Fa release
2092as returned by
2093.Xr uname 3
2094by default.
2095.Pp
2096Manual pages that are part of a portable software project can override
2097the default by giving the project name and version number as arguments,
2098but leaving it blank is never a bad choice.
2099.Pp
2100See also
2101.Ic \&Dd
2102and
2103.Ic \&Dt .
2104.It Ic \&Ot Ar functype
2105This macro is obsolete.
2106Use
2107.Ic \&Ft
2108instead; with
2109.Xr mandoc 1 ,
2110both have the same effect.
2111.Pp
2112Historical
2113.Nm
2114packages described it as
2115.Dq "old function type (FORTRAN)" .
2116.Tg Ox
2117.It Ic \&Ox Op Ar version
2118Format the
2119.Ox
2120version provided as an argument, or a default value
2121if no argument is provided.
2122.Pp
2123Examples:
2124.Dl \&.Ox 4.5
2125.Dl \&.Ox
2126.Pp
2127See also
2128.Ic \&At ,
2129.Ic \&Bsx ,
2130.Ic \&Bx ,
2131.Ic \&Dx ,
2132.Ic \&Fx ,
2133and
2134.Ic \&Nx .
2135.Tg Pa
2136.It Ic \&Pa Ar name ...
2137An absolute or relative file system path, or a file or directory name.
2138If an argument is not provided, the character
2139.Sq \(ti
2140is used as a default.
2141.Pp
2142Examples:
2143.Dl \&.Pa /usr/bin/mandoc
2144.Dl \&.Pa /usr/share/man/man7/mdoc.7
2145.Pp
2146See also
2147.Ic \&Lk .
2148.It Ic \&Pc
2149Close parenthesised context opened by
2150.Ic \&Po .
2151.Tg Pf
2152.It Ic \&Pf Ar prefix macro Op Ar argument ...
2153Removes the space between its argument and the following macro.
2154It is equivalent to:
2155.Pp
2156.D1 Ic \&No Pf \e& Ar prefix Ic \&Ns Ar macro Op Ar argument ...
2157.Pp
2158The
2159.Ar prefix
2160argument is not parsed for macro names or delimiters,
2161but used verbatim as if it were escaped.
2162.Pp
2163Examples:
2164.Dl ".Pf $ Ar variable_name"
2165.Dl ".Pf . Ar macro_name"
2166.Dl ".Pf 0x Ar hex_digits"
2167.Pp
2168See also
2169.Ic \&Ns
2170and
2171.Ic \&Sm .
2172.It Ic \&Po Ar block
2173Multi-line version of
2174.Ic \&Pq .
2175.Tg Pp
2176.It Ic \&Pp
2177Break a paragraph.
2178This will assert vertical space between prior and subsequent macros
2179and/or text.
2180.Pp
2181Paragraph breaks are not needed before or after
2182.Ic \&Sh
2183or
2184.Ic \&Ss
2185macros or before displays
2186.Pq Ic \&Bd Ar line
2187or lists
2188.Pq Ic \&Bl
2189unless the
2190.Fl compact
2191flag is given.
2192.Tg Pq
2193.It Ic \&Pq Ar line
2194Parenthesised enclosure.
2195.Pp
2196See also
2197.Ic \&Po .
2198.It Ic \&Qc
2199Close quoted context opened by
2200.Ic \&Qo .
2201.Tg Ql
2202.It Ic \&Ql Ar line
2203In-line literal display.
2204This can be used for complete command invocations and for multi-word
2205code examples when an indented display is not desired.
2206.Pp
2207See also
2208.Ic \&Dl
2209and
2210.Ic \&Bd
2211.Fl literal .
2212.It Ic \&Qo Ar block
2213Multi-line version of
2214.Ic \&Qq .
2215.Tg Qq
2216.It Ic \&Qq Ar line
2217Encloses its arguments in
2218.Qq typewriter
2219double-quotes.
2220Consider using
2221.Ic \&Dq .
2222.Pp
2223See also
2224.Ic \&Dq ,
2225.Ic \&Sq ,
2226and
2227.Ic \&Qo .
2228.It Ic \&Re
2229Close an
2230.Ic \&Rs
2231block.
2232Does not have any tail arguments.
2233.Tg Rs
2234.It Ic \&Rs
2235Begin a bibliographic
2236.Pq Dq reference
2237block.
2238Does not have any head arguments.
2239The block macro may only contain
2240.Ic \&%A ,
2241.Ic \&%B ,
2242.Ic \&%C ,
2243.Ic \&%D ,
2244.Ic \&%I ,
2245.Ic \&%J ,
2246.Ic \&%N ,
2247.Ic \&%O ,
2248.Ic \&%P ,
2249.Ic \&%Q ,
2250.Ic \&%R ,
2251.Ic \&%T ,
2252.Ic \&%U ,
2253and
2254.Ic \&%V
2255child macros (at least one must be specified).
2256.Pp
2257Examples:
2258.Bd -literal -offset indent -compact
2259\&.Rs
2260\&.%A J. E. Hopcroft
2261\&.%A J. D. Ullman
2262\&.%B Introduction to Automata Theory, Languages, and Computation
2263\&.%I Addison-Wesley
2264\&.%C Reading, Massachusetts
2265\&.%D 1979
2266\&.Re
2267.Ed
2268.Pp
2269If an
2270.Ic \&Rs
2271block is used within a SEE ALSO section, a vertical space is asserted
2272before the rendered output, else the block continues on the current
2273line.
2274.Tg Rv
2275.It Ic \&Rv Fl std Op Ar function ...
2276Insert a standard sentence regarding a function call's return value of 0
2277on success and \-1 on error, with the
2278.Va errno
2279libc global variable set on error.
2280.Pp
2281If
2282.Ar function
2283is not specified, the document's name set by
2284.Ic \&Nm
2285is used.
2286Multiple
2287.Ar function
2288arguments are treated as separate functions.
2289.Pp
2290See also
2291.Ic \&Ex .
2292.It Ic \&Sc
2293Close single-quoted context opened by
2294.Ic \&So .
2295.Tg Sh
2296.It Ic \&Sh Ar TITLE LINE
2297Begin a new section.
2298For a list of conventional manual sections, see
2299.Sx MANUAL STRUCTURE .
2300These sections should be used unless it's absolutely necessary that
2301custom sections be used.
2302.Pp
2303Section names should be unique so that they may be keyed by
2304.Ic \&Sx .
2305Although this macro is parsed, it should not consist of child node or it
2306may not be linked with
2307.Ic \&Sx .
2308.Pp
2309See also
2310.Ic \&Pp ,
2311.Ic \&Ss ,
2312and
2313.Ic \&Sx .
2314.Tg Sm
2315.It Ic \&Sm Op Cm on | off
2316Switches the spacing mode for output generated from macros.
2317.Pp
2318By default, spacing is
2319.Cm on .
2320When switched
2321.Cm off ,
2322no white space is inserted between macro arguments and between the
2323output generated from adjacent macros, but text lines
2324still get normal spacing between words and sentences.
2325.Pp
2326When called without an argument, the
2327.Ic \&Sm
2328macro toggles the spacing mode.
2329Using this is not recommended because it makes the code harder to read.
2330.It Ic \&So Ar block
2331Multi-line version of
2332.Ic \&Sq .
2333.Tg Sq
2334.It Ic \&Sq Ar line
2335Encloses its arguments in
2336.Sq typewriter
2337single-quotes.
2338.Pp
2339See also
2340.Ic \&Dq ,
2341.Ic \&Qq ,
2342and
2343.Ic \&So .
2344.Tg Ss
2345.It Ic \&Ss Ar Title line
2346Begin a new subsection.
2347Unlike with
2348.Ic \&Sh ,
2349there is no convention for the naming of subsections.
2350Except
2351.Em DESCRIPTION ,
2352the conventional sections described in
2353.Sx MANUAL STRUCTURE
2354rarely have subsections.
2355.Pp
2356Sub-section names should be unique so that they may be keyed by
2357.Ic \&Sx .
2358Although this macro is parsed, it should not consist of child node or it
2359may not be linked with
2360.Ic \&Sx .
2361.Pp
2362See also
2363.Ic \&Pp ,
2364.Ic \&Sh ,
2365and
2366.Ic \&Sx .
2367.Tg St
2368.It Ic \&St Fl Ns Ar abbreviation
2369Replace an abbreviation for a standard with the full form.
2370The following standards are recognised.
2371Where multiple lines are given without a blank line in between,
2372they all refer to the same standard, and using the first form
2373is recommended.
2374.Bl -tag -width 1n
2375.It C language standards
2376.Pp
2377.Bl -tag -width "-p1003.1g-2000" -compact
2378.It \-ansiC
2379.St -ansiC
2380.It \-ansiC-89
2381.St -ansiC-89
2382.It \-isoC
2383.St -isoC
2384.It \-isoC-90
2385.St -isoC-90
2386.br
2387The original C standard.
2388.Pp
2389.It \-isoC-amd1
2390.St -isoC-amd1
2391.Pp
2392.It \-isoC-tcor1
2393.St -isoC-tcor1
2394.Pp
2395.It \-isoC-tcor2
2396.St -isoC-tcor2
2397.Pp
2398.It \-isoC-99
2399.St -isoC-99
2400.br
2401The second major version of the C language standard.
2402.Pp
2403.It \-isoC-2011
2404.St -isoC-2011
2405.br
2406The third major version of the C language standard.
2407.El
2408.It POSIX.1 before XPG4.2
2409.Pp
2410.Bl -tag -width "-p1003.1g-2000" -compact
2411.It \-p1003.1-88
2412.St -p1003.1-88
2413.It \-p1003.1
2414.St -p1003.1
2415.br
2416The original POSIX standard, based on ANSI C.
2417.Pp
2418.It \-p1003.1-90
2419.St -p1003.1-90
2420.It \-iso9945-1-90
2421.St -iso9945-1-90
2422.br
2423The first update of POSIX.1.
2424.Pp
2425.It \-p1003.1b-93
2426.St -p1003.1b-93
2427.It \-p1003.1b
2428.St -p1003.1b
2429.br
2430Real-time extensions.
2431.Pp
2432.It \-p1003.1c-95
2433.St -p1003.1c-95
2434.br
2435POSIX thread interfaces.
2436.Pp
2437.It \-p1003.1i-95
2438.St -p1003.1i-95
2439.br
2440Technical Corrigendum.
2441.Pp
2442.It \-p1003.1-96
2443.St -p1003.1-96
2444.It \-iso9945-1-96
2445.St -iso9945-1-96
2446.br
2447Includes POSIX.1-1990, 1b, 1c, and 1i.
2448.El
2449.It X/Open Portability Guide before XPG4.2
2450.Pp
2451.Bl -tag -width "-p1003.1g-2000" -compact
2452.It \-xpg3
2453.St -xpg3
2454.br
2455An XPG4 precursor, published in 1989.
2456.Pp
2457.It \-p1003.2
2458.St -p1003.2
2459.It \-p1003.2-92
2460.St -p1003.2-92
2461.It \-iso9945-2-93
2462.St -iso9945-2-93
2463.br
2464An XCU4 precursor.
2465.Pp
2466.It \-p1003.2a-92
2467.St -p1003.2a-92
2468.br
2469Updates to POSIX.2.
2470.Pp
2471.It \-xpg4
2472.St -xpg4
2473.br
2474Based on POSIX.1 and POSIX.2, published in 1992.
2475.El
2476.It X/Open Portability Guide Issue 4 Version 2 and related standards
2477.Pp
2478.Bl -tag -width "-p1003.1g-2000" -compact
2479.It \-susv1
2480.St -susv1
2481.It \-xpg4.2
2482.St -xpg4.2
2483.br
2484This standard was published in 1994.
2485It was used as the basis for UNIX 95 certification.
2486The following two refer to parts of it.
2487.Pp
2488.It \-xcurses4.2
2489.St -xcurses4.2
2490.Pp
2491.It \-p1003.1g-2000
2492.St -p1003.1g-2000
2493.br
2494Networking APIs, including sockets.
2495.Pp
2496.It \-svid4
2497.St -svid4 ,
2498.br
2499Published in 1995.
2500.El
2501.It X/Open Portability Guide Issue 5 and related standards
2502.Pp
2503.Bl -tag -width "-p1003.1g-2000" -compact
2504.It \-susv2
2505.St -susv2
2506.br
2507This Standard was published in 1997
2508and is also called X/Open Portability Guide Issue 5.
2509It was used as the basis for UNIX 98 certification.
2510The following refer to parts of it.
2511.Pp
2512.It \-xbd5
2513.St -xbd5
2514.Pp
2515.It \-xsh5
2516.St -xsh5
2517.Pp
2518.It \-xcu5
2519.St -xcu5
2520.Pp
2521.It \-xns5
2522.St -xns5
2523.It \-xns5.2
2524.St -xns5.2
2525.El
2526.It POSIX Issue 6
2527.Pp
2528.Bl -tag -width "-p1003.1-2001" -compact
2529.It \-p1003.1-2001
2530.St -p1003.1-2001
2531.It \-susv3
2532.St -susv3
2533.br
2534This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j.
2535It is also called X/Open Portability Guide Issue 6.
2536It is used as the basis for UNIX 03 certification.
2537.Pp
2538.It \-p1003.1-2004
2539.St -p1003.1-2004
2540.br
2541The second and last Technical Corrigendum.
2542.El
2543.It POSIX Issues 7 and 8
2544.Pp
2545.Bl -tag -width "-p1003.1g-2000" -compact
2546.It \-p1003.1-2008
2547.St -p1003.1-2008
2548.It \-susv4
2549.St -susv4
2550.br
2551This standard is based on C99.
2552It is also called the
2553Open Group Standard Base Specifications, Issue 7.
2554.El
2555.Pp
2556.Bl -tag -width "-p1003.1g-2000" -compact
2557.It \-p1003.1-2024
2558.St -p1003.1-2024
2559.br
2560This standard is based on C17.
2561It is also called the
2562Open Group Standard Base Specifications, Issue 8.
2563.El
2564.It Other standards
2565.Pp
2566.Bl -tag -width "-p1003.1g-2000" -compact
2567.It \-ieee754
2568.St -ieee754
2569.br
2570Floating-point arithmetic.
2571.Pp
2572.It \-iso8601
2573.St -iso8601
2574.br
2575Representation of dates and times, published in 1988.
2576.Pp
2577.It \-iso8802-3
2578.St -iso8802-3
2579.br
2580Ethernet local area networks.
2581.Pp
2582.It \-ieee1275-94
2583.St -ieee1275-94
2584.El
2585.El
2586.Tg Sx
2587.It Ic \&Sx Ar Title line
2588Reference a section or subsection in the same manual page.
2589The referenced section or subsection name must be identical to the
2590enclosed argument, including whitespace.
2591.Pp
2592Examples:
2593.Dl \&.Sx MANUAL STRUCTURE
2594.Pp
2595See also
2596.Ic \&Sh
2597and
2598.Ic \&Ss .
2599.Tg Sy
2600.It Ic \&Sy Ar word ...
2601Request a boldface font.
2602.Pp
2603This is most often used to indicate importance or seriousness (not to be
2604confused with stress emphasis, see
2605.Ic \&Em ) .
2606When none of the semantic macros fit, it is also adequate for syntax
2607elements that have to be given or that appear verbatim.
2608.Pp
2609Examples:
2610.Bd -literal -compact -offset indent
2611\&.Sy Warning :
2612If
2613\&.Sy s
2614appears in the owner permissions, set-user-ID mode is set.
2615This utility replaces the former
2616\&.Sy dumpdir
2617program.
2618.Ed
2619.Pp
2620See also
2621.Ic \&Em ,
2622.Ic \&No ,
2623and
2624.Ic \&Ql .
2625.Tg Ta
2626.It Ic \&Ta
2627Table cell separator in
2628.Ic \&Bl Fl column
2629lists; can only be used below
2630.Ic \&It .
2631.Tg Tg
2632.It Ic \&Tg Op Ar term
2633Announce that the next input line starts a definition of the
2634.Ar term .
2635This macro must appear alone on its own input line.
2636The argument defaults to the first argument of the first macro
2637on the next line.
2638The argument may not contain whitespace characters, not even when it is quoted.
2639This macro is a
2640.Xr mandoc 1
2641extension and is typically ignored by other formatters.
2642.Pp
2643When viewing terminal output with
2644.Xr less 1 ,
2645the interactive
2646.Ic :t
2647command can be used to go to the definition of the
2648.Ar term
2649as described for the
2650.Ev MANPAGER
2651variable in
2652.Xr man 1 ;
2653when producing HTML output, a fragment identifier
2654.Pq Ic id No attribute
2655is generated, to be used for deep linking to this place of the document.
2656.Pp
2657In most cases, adding a
2658.Ic \&Tg
2659macro would be redundant because
2660.Xr mandoc 1
2661is able to automatically tag most definitions.
2662This macro is intended for cases where automatic tagging of a
2663.Ar term
2664is unsatisfactory, for example if a definition is not tagged
2665automatically (false negative) or if places are tagged that do
2666not define the
2667.Ar term
2668(false positives).
2669When there is at least one
2670.Ic \&Tg
2671macro for a
2672.Ar term ,
2673no other places are automatically marked as definitions of that
2674.Ar term .
2675.It Ic \&Tn Ar word ...
2676Supported only for compatibility, do not use this in new manuals.
2677Even though the macro name
2678.Pq Dq tradename
2679suggests a semantic function, historic usage is inconsistent, mostly
2680using it as a presentation-level macro to request a small caps font.
2681.It Ic \&Ud
2682Supported only for compatibility, do not use this in new manuals.
2683Prints out
2684.Dq currently under development.
2685.It Ic \&Ux
2686Supported only for compatibility, do not use this in new manuals.
2687Prints out
2688.Dq Ux .
2689.Tg Va
2690.It Ic \&Va Oo Ar type Oc Ar identifier ...
2691A variable name.
2692.Pp
2693Examples:
2694.Dl \&.Va foo
2695.Dl \&.Va const char *bar ;
2696.Pp
2697For function arguments and parameters, use
2698.Ic \&Fa
2699instead.
2700For declarations of global variables in the
2701.Em SYNOPSIS
2702section, use
2703.Ic \&Vt .
2704.Tg Vt
2705.It Ic \&Vt Ar type Op Ar identifier
2706A variable type.
2707.Pp
2708This is also used for indicating global variables in the
2709.Em SYNOPSIS
2710section, in which case a variable name is also specified.
2711Note that it accepts
2712.Sx Block partial-implicit
2713syntax when invoked as the first macro on an input line in the
2714.Em SYNOPSIS
2715section, else it accepts ordinary
2716.Sx In-line
2717syntax.
2718In the former case, this macro starts a new output line,
2719and a blank line is inserted in front if there is a preceding
2720function definition or include directive.
2721.Pp
2722Examples:
2723.Dl \&.Vt unsigned char
2724.Dl \&.Vt extern const char * const sys_signame[] \&;
2725.Pp
2726For parameters in function prototypes, use
2727.Ic \&Fa
2728instead, for function return types
2729.Ic \&Ft ,
2730and for variable names outside the
2731.Em SYNOPSIS
2732section
2733.Ic \&Va ,
2734even when including a type with the name.
2735See also
2736.Sx MANUAL STRUCTURE .
2737.It Ic \&Xc
2738Close a scope opened by
2739.Ic \&Xo .
2740.It Ic \&Xo Ar block
2741Extend the header of an
2742.Ic \&It
2743macro or the body of a partial-implicit block macro
2744beyond the end of the input line.
2745This macro originally existed to work around the 9-argument limit
2746of historic
2747.Xr roff 7 .
2748.Tg Xr
2749.It Ic \&Xr Ar name section
2750Link to another manual
2751.Pq Qq cross-reference .
2752.Pp
2753Cross reference the
2754.Ar name
2755and
2756.Ar section
2757number of another man page.
2758.Pp
2759Examples:
2760.Dl \&.Xr mandoc 1
2761.Dl \&.Xr mandoc 1 \&;
2762.Dl \&.Xr mandoc 1 \&Ns s behaviour
2763.El
2764.Sh MACRO SYNTAX
2765The syntax of a macro depends on its classification.
2766In this section,
2767.Sq \-arg
2768refers to macro arguments, which may be followed by zero or more
2769.Sq parm
2770parameters;
2771.Sq \&Yo
2772opens the scope of a macro; and if specified,
2773.Sq \&Yc
2774closes it out.
2775.Pp
2776The
2777.Em Callable
2778column indicates that the macro may also be called by passing its name
2779as an argument to another macro.
2780For example,
2781.Sq \&.Op \&Fl O \&Ar file
2782produces
2783.Sq Op Fl O Ar file .
2784To prevent a macro call and render the macro name literally,
2785escape it by prepending a zero-width space,
2786.Sq \e& .
2787For example,
2788.Sq \&Op \e&Fl O
2789produces
2790.Sq Op \&Fl O .
2791If a macro is not callable but its name appears as an argument
2792to another macro, it is interpreted as opaque text.
2793For example,
2794.Sq \&.Fl \&Sh
2795produces
2796.Sq Fl \&Sh .
2797.Pp
2798The
2799.Em Parsed
2800column indicates whether the macro may call other macros by receiving
2801their names as arguments.
2802If a macro is not parsed but the name of another macro appears
2803as an argument, it is interpreted as opaque text.
2804.Pp
2805The
2806.Em Scope
2807column, if applicable, describes closure rules.
2808.Ss Block full-explicit
2809Multi-line scope closed by an explicit closing macro.
2810All macros contains bodies; only
2811.Ic \&Bf
2812and
2813.Pq optionally
2814.Ic \&Bl
2815contain a head.
2816.Bd -literal -offset indent
2817\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2818\(lBbody...\(rB
2819\&.Yc
2820.Ed
2821.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
2822.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2823.It Ic \&Bd  Ta    \&No     Ta    \&No     Ta    closed by Ic \&Ed
2824.It Ic \&Bf  Ta    \&No     Ta    \&No     Ta    closed by Ic \&Ef
2825.It Ic \&Bk  Ta    \&No     Ta    \&No     Ta    closed by Ic \&Ek
2826.It Ic \&Bl  Ta    \&No     Ta    \&No     Ta    closed by Ic \&El
2827.It Ic \&Ed  Ta    \&No     Ta    \&No     Ta    opened by Ic \&Bd
2828.It Ic \&Ef  Ta    \&No     Ta    \&No     Ta    opened by Ic \&Bf
2829.It Ic \&Ek  Ta    \&No     Ta    \&No     Ta    opened by Ic \&Bk
2830.It Ic \&El  Ta    \&No     Ta    \&No     Ta    opened by Ic \&Bl
2831.El
2832.Ss Block full-implicit
2833Multi-line scope closed by end-of-file or implicitly by another macro.
2834All macros have bodies; some
2835.Po
2836.Ic \&It Fl bullet ,
2837.Fl hyphen ,
2838.Fl dash ,
2839.Fl enum ,
2840.Fl item
2841.Pc
2842don't have heads; only one
2843.Po
2844.Ic \&It
2845in
2846.Ic \&Bl Fl column
2847.Pc
2848has multiple heads.
2849.Bd -literal -offset indent
2850\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
2851\(lBbody...\(rB
2852.Ed
2853.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
2854.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2855.It Ic \&It Ta \&No Ta Yes  Ta closed by Ic \&It , Ic \&El
2856.It Ic \&Nd Ta \&No Ta \&No Ta closed by Ic \&Sh
2857.It Ic \&Nm Ta \&No Ta Yes  Ta closed by Ic \&Nm , Ic \&Sh , Ic \&Ss
2858.It Ic \&Sh Ta \&No Ta Yes  Ta closed by Ic \&Sh
2859.It Ic \&Ss Ta \&No Ta Yes  Ta closed by Ic \&Sh , Ic \&Ss
2860.El
2861.Pp
2862Note that the
2863.Ic \&Nm
2864macro is a
2865.Sx Block full-implicit
2866macro only when invoked as the first macro
2867in a
2868.Em SYNOPSIS
2869section line, else it is
2870.Sx In-line .
2871.Ss Block partial-explicit
2872Like block full-explicit, but also with single-line scope.
2873Each has at least a body and, in limited circumstances, a head
2874.Po
2875.Ic \&Fo ,
2876.Ic \&Eo
2877.Pc
2878and/or tail
2879.Pq Ic \&Ec .
2880.Bd -literal -offset indent
2881\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
2882\(lBbody...\(rB
2883\&.Yc \(lBtail...\(rB
2884
2885\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
2886\(lBbody...\(rB \&Yc \(lBtail...\(rB
2887.Ed
2888.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
2889.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2890.It Ic \&Ac  Ta    Yes      Ta    Yes      Ta    opened by Ic \&Ao
2891.It Ic \&Ao  Ta    Yes      Ta    Yes      Ta    closed by Ic \&Ac
2892.It Ic \&Bc  Ta    Yes      Ta    Yes      Ta    closed by Ic \&Bo
2893.It Ic \&Bo  Ta    Yes      Ta    Yes      Ta    opened by Ic \&Bc
2894.It Ic \&Brc Ta    Yes      Ta    Yes      Ta    opened by Ic \&Bro
2895.It Ic \&Bro Ta    Yes      Ta    Yes      Ta    closed by Ic \&Brc
2896.It Ic \&Dc  Ta    Yes      Ta    Yes      Ta    opened by Ic \&Do
2897.It Ic \&Do  Ta    Yes      Ta    Yes      Ta    closed by Ic \&Dc
2898.It Ic \&Ec  Ta    Yes      Ta    Yes      Ta    opened by Ic \&Eo
2899.It Ic \&Eo  Ta    Yes      Ta    Yes      Ta    closed by Ic \&Ec
2900.It Ic \&Fc  Ta    Yes      Ta    Yes      Ta    opened by Ic \&Fo
2901.It Ic \&Fo  Ta    \&No     Ta    \&No     Ta    closed by Ic \&Fc
2902.It Ic \&Oc  Ta    Yes      Ta    Yes      Ta    closed by Ic \&Oo
2903.It Ic \&Oo  Ta    Yes      Ta    Yes      Ta    opened by Ic \&Oc
2904.It Ic \&Pc  Ta    Yes      Ta    Yes      Ta    closed by Ic \&Po
2905.It Ic \&Po  Ta    Yes      Ta    Yes      Ta    opened by Ic \&Pc
2906.It Ic \&Qc  Ta    Yes      Ta    Yes      Ta    opened by Ic \&Oo
2907.It Ic \&Qo  Ta    Yes      Ta    Yes      Ta    closed by Ic \&Oc
2908.It Ic \&Re  Ta    \&No     Ta    \&No     Ta    opened by Ic \&Rs
2909.It Ic \&Rs  Ta    \&No     Ta    \&No     Ta    closed by Ic \&Re
2910.It Ic \&Sc  Ta    Yes      Ta    Yes      Ta    opened by Ic \&So
2911.It Ic \&So  Ta    Yes      Ta    Yes      Ta    closed by Ic \&Sc
2912.It Ic \&Xc  Ta    Yes      Ta    Yes      Ta    opened by Ic \&Xo
2913.It Ic \&Xo  Ta    Yes      Ta    Yes      Ta    closed by Ic \&Xc
2914.El
2915.Ss Block partial-implicit
2916Like block full-implicit, but with single-line scope closed by the
2917end of the line.
2918.Bd -literal -offset indent
2919\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
2920.Ed
2921.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
2922.It Em Macro Ta Em Callable Ta Em Parsed
2923.It Ic \&Aq  Ta    Yes      Ta    Yes
2924.It Ic \&Bq  Ta    Yes      Ta    Yes
2925.It Ic \&Brq Ta    Yes      Ta    Yes
2926.It Ic \&D1  Ta    \&No     Ta    \&Yes
2927.It Ic \&Dl  Ta    \&No     Ta    Yes
2928.It Ic \&Dq  Ta    Yes      Ta    Yes
2929.It Ic \&En  Ta    Yes      Ta    Yes
2930.It Ic \&Op  Ta    Yes      Ta    Yes
2931.It Ic \&Pq  Ta    Yes      Ta    Yes
2932.It Ic \&Ql  Ta    Yes      Ta    Yes
2933.It Ic \&Qq  Ta    Yes      Ta    Yes
2934.It Ic \&Sq  Ta    Yes      Ta    Yes
2935.It Ic \&Vt  Ta    Yes      Ta    Yes
2936.El
2937.Pp
2938Note that the
2939.Ic \&Vt
2940macro is a
2941.Sx Block partial-implicit
2942only when invoked as the first macro
2943in a
2944.Em SYNOPSIS
2945section line, else it is
2946.Sx In-line .
2947.Ss Special block macro
2948The
2949.Ic \&Ta
2950macro can only be used below
2951.Ic \&It
2952in
2953.Ic \&Bl Fl column
2954lists.
2955It delimits blocks representing table cells;
2956these blocks have bodies, but no heads.
2957.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
2958.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
2959.It Ic \&Ta  Ta    Yes      Ta    Yes    Ta closed by Ic \&Ta , Ic \&It
2960.El
2961.Ss In-line
2962Closed by the end of the line, fixed argument lengths,
2963and/or subsequent macros.
2964In-line macros have only text children.
2965If a number (or inequality) of arguments is
2966.Pq n ,
2967then the macro accepts an arbitrary number of arguments.
2968.Bd -literal -offset indent
2969\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
2970
2971\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
2972
2973\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
2974.Ed
2975.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
2976.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
2977.It Ic \&%A  Ta    \&No     Ta    \&No     Ta    >0
2978.It Ic \&%B  Ta    \&No     Ta    \&No     Ta    >0
2979.It Ic \&%C  Ta    \&No     Ta    \&No     Ta    >0
2980.It Ic \&%D  Ta    \&No     Ta    \&No     Ta    >0
2981.It Ic \&%I  Ta    \&No     Ta    \&No     Ta    >0
2982.It Ic \&%J  Ta    \&No     Ta    \&No     Ta    >0
2983.It Ic \&%N  Ta    \&No     Ta    \&No     Ta    >0
2984.It Ic \&%O  Ta    \&No     Ta    \&No     Ta    >0
2985.It Ic \&%P  Ta    \&No     Ta    \&No     Ta    >0
2986.It Ic \&%Q  Ta    \&No     Ta    \&No     Ta    >0
2987.It Ic \&%R  Ta    \&No     Ta    \&No     Ta    >0
2988.It Ic \&%T  Ta    \&No     Ta    \&No     Ta    >0
2989.It Ic \&%U  Ta    \&No     Ta    \&No     Ta    >0
2990.It Ic \&%V  Ta    \&No     Ta    \&No     Ta    >0
2991.It Ic \&Ad  Ta    Yes      Ta    Yes      Ta    >0
2992.It Ic \&An  Ta    Yes      Ta    Yes      Ta    >0
2993.It Ic \&Ap  Ta    Yes      Ta    Yes      Ta    0
2994.It Ic \&Ar  Ta    Yes      Ta    Yes      Ta    n
2995.It Ic \&At  Ta    Yes      Ta    Yes      Ta    1
2996.It Ic \&Bsx Ta    Yes      Ta    Yes      Ta    n
2997.It Ic \&Bt  Ta    \&No     Ta    \&No     Ta    0
2998.It Ic \&Bx  Ta    Yes      Ta    Yes      Ta    n
2999.It Ic \&Cd  Ta    Yes      Ta    Yes      Ta    >0
3000.It Ic \&Cm  Ta    Yes      Ta    Yes      Ta    >0
3001.It Ic \&Db  Ta    \&No     Ta    \&No     Ta    1
3002.It Ic \&Dd  Ta    \&No     Ta    \&No     Ta    n
3003.It Ic \&Dt  Ta    \&No     Ta    \&No     Ta    n
3004.It Ic \&Dv  Ta    Yes      Ta    Yes      Ta    >0
3005.It Ic \&Dx  Ta    Yes      Ta    Yes      Ta    n
3006.It Ic \&Em  Ta    Yes      Ta    Yes      Ta    >0
3007.It Ic \&Er  Ta    Yes      Ta    Yes      Ta    >0
3008.It Ic \&Es  Ta    Yes      Ta    Yes      Ta    2
3009.It Ic \&Ev  Ta    Yes      Ta    Yes      Ta    >0
3010.It Ic \&Ex  Ta    \&No     Ta    \&No     Ta    n
3011.It Ic \&Fa  Ta    Yes      Ta    Yes      Ta    >0
3012.It Ic \&Fd  Ta    \&No     Ta    \&No     Ta    >0
3013.It Ic \&Fl  Ta    Yes      Ta    Yes      Ta    n
3014.It Ic \&Fn  Ta    Yes      Ta    Yes      Ta    >0
3015.It Ic \&Fr  Ta    Yes      Ta    Yes      Ta    >0
3016.It Ic \&Ft  Ta    Yes      Ta    Yes      Ta    >0
3017.It Ic \&Fx  Ta    Yes      Ta    Yes      Ta    n
3018.It Ic \&Hf  Ta    \&No     Ta    \&No     Ta    n
3019.It Ic \&Ic  Ta    Yes      Ta    Yes      Ta    >0
3020.It Ic \&In  Ta    Yes      Ta    Yes      Ta    1
3021.It Ic \&Lb  Ta    \&No     Ta    \&No     Ta    1
3022.It Ic \&Li  Ta    Yes      Ta    Yes      Ta    >0
3023.It Ic \&Lk  Ta    Yes      Ta    Yes      Ta    >0
3024.It Ic \&Lp  Ta    \&No     Ta    \&No     Ta    0
3025.It Ic \&Ms  Ta    Yes      Ta    Yes      Ta    >0
3026.It Ic \&Mt  Ta    Yes      Ta    Yes      Ta    >0
3027.It Ic \&Nm  Ta    Yes      Ta    Yes      Ta    n
3028.It Ic \&No  Ta    Yes      Ta    Yes      Ta    >0
3029.It Ic \&Ns  Ta    Yes      Ta    Yes      Ta    0
3030.It Ic \&Nx  Ta    Yes      Ta    Yes      Ta    n
3031.It Ic \&Os  Ta    \&No     Ta    \&No     Ta    n
3032.It Ic \&Ot  Ta    Yes      Ta    Yes      Ta    >0
3033.It Ic \&Ox  Ta    Yes      Ta    Yes      Ta    n
3034.It Ic \&Pa  Ta    Yes      Ta    Yes      Ta    n
3035.It Ic \&Pf  Ta    Yes      Ta    Yes      Ta    1
3036.It Ic \&Pp  Ta    \&No     Ta    \&No     Ta    0
3037.It Ic \&Rv  Ta    \&No     Ta    \&No     Ta    n
3038.It Ic \&Sm  Ta    \&No     Ta    \&No     Ta    <2
3039.It Ic \&St  Ta    \&No     Ta    Yes      Ta    1
3040.It Ic \&Sx  Ta    Yes      Ta    Yes      Ta    >0
3041.It Ic \&Sy  Ta    Yes      Ta    Yes      Ta    >0
3042.It Ic \&Tg  Ta    \&No     Ta    \&No     Ta    <2
3043.It Ic \&Tn  Ta    Yes      Ta    Yes      Ta    >0
3044.It Ic \&Ud  Ta    \&No     Ta    \&No     Ta    0
3045.It Ic \&Ux  Ta    Yes      Ta    Yes      Ta    n
3046.It Ic \&Va  Ta    Yes      Ta    Yes      Ta    n
3047.It Ic \&Vt  Ta    Yes      Ta    Yes      Ta    >0
3048.It Ic \&Xr  Ta    Yes      Ta    Yes      Ta    2
3049.El
3050.Ss Delimiters
3051When a macro argument consists of one single input character
3052considered as a delimiter, the argument gets special handling.
3053This does not apply when delimiters appear in arguments containing
3054more than one character.
3055Consequently, to prevent special handling and just handle it
3056like any other argument, a delimiter can be escaped by prepending
3057a zero-width space
3058.Pq Sq \e& .
3059In text lines, delimiters never need escaping, but may be used
3060as normal punctuation.
3061.Pp
3062For many macros, when the leading arguments are opening delimiters,
3063these delimiters are put before the macro scope,
3064and when the trailing arguments are closing delimiters,
3065these delimiters are put after the macro scope.
3066Spacing is suppressed after opening delimiters
3067and before closing delimiters.
3068For example,
3069.Pp
3070.D1 Pf \. \&Aq "( [ word ] ) ."
3071.Pp
3072renders as:
3073.Pp
3074.D1 Aq ( [ word ] ) .
3075.Pp
3076Opening delimiters are:
3077.Pp
3078.Bl -tag -width Ds -offset indent -compact
3079.It \&(
3080left parenthesis
3081.It \&[
3082left bracket
3083.El
3084.Pp
3085Closing delimiters are:
3086.Pp
3087.Bl -tag -width Ds -offset indent -compact
3088.It \&.
3089period
3090.It \&,
3091comma
3092.It \&:
3093colon
3094.It \&;
3095semicolon
3096.It \&)
3097right parenthesis
3098.It \&]
3099right bracket
3100.It \&?
3101question mark
3102.It \&!
3103exclamation mark
3104.El
3105.Pp
3106Note that even a period preceded by a backslash
3107.Pq Sq \e.\&
3108gets this special handling; use
3109.Sq \e&.\&
3110to prevent that.
3111.Pp
3112Many in-line macros interrupt their scope when they encounter
3113delimiters, and resume their scope when more arguments follow that
3114are not delimiters.
3115For example,
3116.Pp
3117.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e"
3118.Pp
3119renders as:
3120.Pp
3121.D1 Fl a ( b | c \*(Ba d ) e
3122.Pp
3123This applies to both opening and closing delimiters,
3124and also to the middle delimiter, which does not suppress spacing:
3125.Pp
3126.Bl -tag -width Ds -offset indent -compact
3127.It \&|
3128vertical bar
3129.El
3130.Pp
3131As a special case, the predefined string \e*(Ba is handled and rendered
3132in the same way as a plain
3133.Sq \&|
3134character.
3135Using this predefined string is not recommended in new manuals.
3136.Pp
3137Appending a zero-width space
3138.Pq Sq \e&
3139to the end of an input line is also useful to prevent the interpretation
3140of a trailing period, exclamation or question mark as the end of a
3141sentence, for example when an abbreviation happens to occur
3142at the end of a text or macro input line.
3143.Ss Font handling
3144In
3145.Nm
3146documents, usage of semantic markup is recommended in order to have
3147proper fonts automatically selected; only when no fitting semantic markup
3148is available, consider falling back to
3149.Sx Physical markup
3150macros.
3151Whenever any
3152.Nm
3153macro switches the
3154.Xr roff 7
3155font mode, it will automatically restore the previous font when exiting
3156its scope.
3157Manually switching the font using the
3158.Xr roff 7
3159.Ql \ef
3160font escape sequences is never required.
3161.Sh COMPATIBILITY
3162This section provides an incomplete list of compatibility issues
3163between mandoc and GNU troff
3164.Pq Qq groff .
3165.Pp
3166The following problematic behaviour is found in groff:
3167.Pp
3168.Bl -dash -compact
3169.It
3170.Ic \&Pa
3171does not format its arguments when used in the FILES section under
3172certain list types.
3173.It
3174.Ic \&Ta
3175can only be called by other macros, but not at the beginning of a line.
3176.It
3177.Sq \ef
3178.Pq font face
3179and
3180.Sq \eF
3181.Pq font family face
3182.Sx Text Decoration
3183escapes behave irregularly when specified within line-macro scopes.
3184.It
3185Negative scaling units return to prior lines.
3186Instead, mandoc truncates them to zero.
3187.El
3188.Pp
3189The following features are unimplemented in mandoc:
3190.Pp
3191.Bl -dash -compact
3192.It
3193.Ic \&Bd Fl file Ar file
3194is unsupported for security reasons.
3195.It
3196.Ic \&Bd
3197.Fl filled
3198does not adjust the right margin, but is an alias for
3199.Ic \&Bd
3200.Fl ragged .
3201.It
3202.Ic \&Bd
3203.Fl literal
3204does not use a literal font, but is an alias for
3205.Ic \&Bd
3206.Fl unfilled .
3207.It
3208.Ic \&Bd
3209.Fl offset Cm center
3210and
3211.Fl offset Cm right
3212don't work.
3213Groff does not implement centered and flush-right rendering either,
3214but produces large indentations.
3215.El
3216.Sh SEE ALSO
3217.Xr man 1 ,
3218.Xr mandoc 1 ,
3219.Xr eqn 7 ,
3220.Xr man 7 ,
3221.Xr mandoc_char 7 ,
3222.Xr roff 7 ,
3223.Xr tbl 7
3224.Pp
3225The web page
3226.Lk https://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language"
3227provides a few tutorial-style pages for beginners, an extensive style
3228guide for advanced authors, and an alphabetic index helping to choose
3229the best macros for various kinds of content.
3230.Pp
3231The manual page
3232.Lk https://man.voidlinux.org/groff_mdoc "groff_mdoc(7)"
3233contained in the
3234.Dq groff
3235package documents exactly the same language in a somewhat different style.
3236.Sh HISTORY
3237The
3238.Nm
3239language first appeared as a troff macro package in
3240.Bx 4.4 .
3241It was later significantly updated by Werner Lemberg and Ruslan Ermilov
3242in groff-1.17.
3243The standalone implementation that is part of the
3244.Xr mandoc 1
3245utility written by Kristaps Dzonsons appeared in
3246.Ox 4.6 .
3247.Sh AUTHORS
3248The
3249.Nm
3250reference was written by
3251.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
3252