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