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