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