summaryrefslogtreecommitdiff
path: root/usr/src/man/man5/mdoc.5
diff options
context:
space:
mode:
Diffstat (limited to 'usr/src/man/man5/mdoc.5')
-rw-r--r--usr/src/man/man5/mdoc.5870
1 files changed, 483 insertions, 387 deletions
diff --git a/usr/src/man/man5/mdoc.5 b/usr/src/man/man5/mdoc.5
index 901a2848cd..a981edd5ff 100644
--- a/usr/src/man/man5/mdoc.5
+++ b/usr/src/man/man5/mdoc.5
@@ -1,3 +1,7 @@
+.\" $Id: mdoc.7,v 1.252 2015/02/23 13:31:04 schwarze Exp $
+.\"
+.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
@@ -12,12 +16,10 @@
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\"
-.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
-.\" Copyright 2012 Nexenta Systems, Inc. All rights reserved.
.\" Copyright 2014 Garrett D'Amore <garrett@dmaore.org>
+.\" Copyright 2015 Nexenta Systems, Inc. All rights reserved.
.\"
-.Dd Jul 19, 2014
+.Dd Oct 18, 2015
.Dt MDOC 5
.Os
.Sh NAME
@@ -73,17 +75,17 @@ Text lines are interpreted within the current state.
Many aspects of the basic syntax of the
.Nm
language are based on the
-.Xr roff 5
+.Xr mandoc_roff 5
language; see the
.Em LANGUAGE SYNTAX
and
.Em MACRO SYNTAX
sections in the
-.Xr roff 5
+.Xr mandoc_roff 5
manual for details, in particular regarding
comments, escape sequences, whitespace, and quoting.
However, using
-.Xr roff 5
+.Xr mandoc_roff 5
requests in
.Nm
documents is discouraged;
@@ -125,9 +127,9 @@ file for a utility
\&.Os
\&.Sh NAME
\&.Nm progname
-\&.Nd one line description
+\&.Nd one line about what it does
\&.\e\(dq .Sh LIBRARY
-\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq For sections 2, 3, and 9 only.
\&.Sh SYNOPSIS
\&.Nm progname
\&.Op Fl options
@@ -138,7 +140,9 @@ The
utility processes files ...
\&.\e\(dq .Sh IMPLEMENTATION NOTES
\&.\e\(dq .Sh RETURN VALUES
-\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq For sections 2, 3, and 9 only.
+\&.\e\(dq .Sh CONTEXT
+\&.\e\(dq For section 9 functions only.
\&.\e\(dq .Sh ENVIRONMENT
\&.\e\(dq For sections 1, 1M, and 5.
\&.\e\(dq .Sh FILES
@@ -147,13 +151,13 @@ utility processes files ...
\&.\e\(dq .Sh EXAMPLES
\&.\e\(dq .Sh DIAGNOSTICS
\&.\e\(dq .Sh ERRORS
-\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq For sections 2, 3, and 9 only.
\&.\e\(dq .Sh ARCHITECTURE
\&.\e\(dq .Sh CODE SET INDEPENDENCE
-\&.\e\(dq For sections 1, 1M, & 3 only.
+\&.\e\(dq For sections 1, 1M, and 3 only.
\&.\e\(dq .Sh INTERFACE STABILITY
\&.\e\(dq .Sh MT-LEVEL
-\&.\e\(dq For sections 2 & 3 only.
+\&.\e\(dq For sections 2 and 3 only.
\&.\e\(dq .Sh SECURITY
\&.\e\(dq .Sh SEE ALSO
\&.\e\(dq .Xr foobar 1
@@ -331,6 +335,9 @@ return values of functions in sections 2, 3, and 9.
.Pp
See
.Sx \&Rv .
+.It Em CONTEXT
+This section lists the contexts in which functions can be called in section 9.
+The contexts are user, kernel, or interrupt.
.It Em ENVIRONMENT
Lists the environment variables used by the utility,
and explains the syntax and semantics of their values.
@@ -495,7 +502,7 @@ Documents any security precautions that operators should consider.
References other manuals with related topics.
This section should exist for most manuals.
Cross-references should conventionally be ordered first by section, then
-alphabetically.
+alphabetically (ignoring case).
.Pp
References to other documentation concerning the topic of the manual page,
for example authoritative books or journal articles, may also be
@@ -538,7 +545,7 @@ in the alphabetical
.Ss Document preamble and NAME section macros
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Dd Ta document date: Ar month day , year
-.It Sx \&Dt Ta document title: Ar TITLE SECTION Op Ar volume | arch
+.It Sx \&Dt Ta document title: Ar TITLE SECTION Op Ar arch
.It Sx \&Os Ta operating system version: Op Ar system Op Ar version
.It Sx \&Nm Ta document name (one argument)
.It Sx \&Nd Ta document description (one line)
@@ -559,6 +566,7 @@ in the alphabetical
.Op Fl compact
.It Sx \&D1 Ta indented display (one line)
.It Sx \&Dl Ta indented literal display (one line)
+.It Sx \&Ql Ta in-line literal display: Ql text
.It Sx \&Bl , \&El Ta list block:
.Fl Ar type
.Op Fl width Ar val
@@ -573,7 +581,7 @@ in the alphabetical
.It Sx \&Pf Ta prefix, no following horizontal space (one argument)
.It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
.It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
-.It Sx \&Sm Ta switch horizontal spacing mode: Cm on | off
+.It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off
.It Sx \&Bk , \&Ek Ta keep block: Fl words
.It Sx \&br Ta force output line break in text mode (no arguments)
.It Sx \&sp Ta force vertical space: Op Ar height
@@ -593,6 +601,7 @@ in the alphabetical
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Lb Ta function library (one argument)
.It Sx \&In Ta include file (one argument)
+.It Sx \&Fd Ta other preprocessor directive (>0 arguments)
.It Sx \&Ft Ta function type (>0 arguments)
.It Sx \&Fo , \&Fc Ta function block: Ar funcname
.It Sx \&Fn Ta function name:
@@ -617,7 +626,6 @@ in the alphabetical
.It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
.It Sx \&Ad Ta memory address (>0 arguments)
.It Sx \&Ms Ta mathematical symbol (>0 arguments)
-.It Sx \&Tn Ta tradename (>0 arguments)
.El
.Ss Physical markup
.Bl -column "Brq, Bro, Brc" description
@@ -633,7 +641,6 @@ in the alphabetical
.It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text
.It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text
.It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text
-.It Sx \&Ql Ta single-quoted literal text: Ql text
.It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text
.It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text
.It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text
@@ -645,7 +652,6 @@ in the alphabetical
.It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
.It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
.It Sx \&St Ta reference to a standards document (one argument)
-.It Sx \&Ux Ta Ux
.It Sx \&At Ta At
.It Sx \&Bx Ta Bx
.It Sx \&Bsx Ta Bsx
@@ -773,7 +779,7 @@ for all other author listings.
.Pp
Examples:
.Dl \&.An -nosplit
-.Dl \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv
+.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
.Ss \&Ao
Begin a block enclosed by angle brackets.
Does not have any head arguments.
@@ -827,7 +833,9 @@ for fixed strings to be passed verbatim as arguments, use
or
.Sx \&Cm .
.Ss \&At
-Formats an AT&T version.
+Formats an
+.At
+version.
Accepts one optional argument:
.Pp
.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
@@ -854,9 +862,8 @@ See also
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Bc
Close a
.Sx \&Bo
@@ -882,7 +889,7 @@ The
must be one of the following:
.Bl -tag -width 13n -offset indent
.It Fl centered
-Produce one output line from each input line, and centre-justify each line.
+Produce one output line from each input line, and center-justify each line.
Using this display type is not recommended; many
.Nm
implementations render it poorly.
@@ -927,7 +934,7 @@ which has no effect;
.Cm right ,
which justifies to the right margin; or
.Cm center ,
-which aligns around an imagined centre axis.
+which aligns around an imagined center axis.
.It
A macro invocation, which selects a predefined width
associated with that macro.
@@ -936,8 +943,8 @@ The most popular is the imaginary macro
which resolves to
.Sy 6n .
.It
-A width using the syntax described in
-.Sx Scaling Widths .
+A scaling width as described in
+.Xr mandoc_roff 5 .
.It
An arbitrary string, which indents by the length of this string.
.El
@@ -1042,8 +1049,11 @@ The
.Fl width
and
.Fl offset
-arguments accept
-.Sx Scaling Widths
+arguments accept macro names as described for
+.Sx \&Bd
+.Fl offset ,
+scaling widths as described in
+.Xr mandoc_roff 5 ,
or use the length of the given string.
The
.Fl offset
@@ -1072,9 +1082,9 @@ A columnated list.
The
.Fl width
argument has no effect; instead, each argument specifies the width
-of one column, using either the
-.Sx Scaling Widths
-syntax or the string length of the argument.
+of one column, using either the scaling width syntax described in
+.Xr mandoc_roff 5
+or the string length of the argument.
If the first line of the body of a
.Fl column
list is not an
@@ -1205,7 +1215,9 @@ Examples:
See also
.Sx \&Bro .
.Ss \&Bsx
-Format the BSD/OS version provided as an argument, or a default value if
+Format the
+.Bsx
+version provided as an argument, or a default value if
no argument is provided.
.Pp
Examples:
@@ -1218,14 +1230,16 @@ See also
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Bt
+Supported only for compatibility, do not use this in new manuals.
Prints
.Dq is currently in beta test.
.Ss \&Bx
-Format the BSD version provided as an argument, or a default value if no
+Format the
+.Bx
+version provided as an argument, or a default value if no
argument is provided.
.Pp
Examples:
@@ -1239,9 +1253,8 @@ See also
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Cd
Kernel configuration declaration. It is found in pages for
.Bx
@@ -1283,20 +1296,19 @@ See also
and
.Sx \&Dl .
.Ss \&Db
-Switch debugging mode.
-Its syntax is as follows:
-.Pp
-.D1 Pf \. Sx \&Db Cm on | off
-.Pp
-This macro is ignored by
-.Xr mandoc 1 .
+This macro is obsolete.
+No replacement is needed.
+It is ignored by
+.Xr mandoc 1
+and groff including its arguments.
+It was formerly used to toggle a debugging mode.
.Ss \&Dc
Close a
.Sx \&Do
block.
Does not have any tail arguments.
.Ss \&Dd
-Document date.
+Document date for display in the page footer.
This is the mandatory first macro of any
.Nm
manual.
@@ -1325,8 +1337,11 @@ the special string
.Dq $\&Mdocdate$
can be given as an argument.
.It
-A few alternative date formats are accepted as well
-and converted to the standard form.
+The traditional, purely numeric
+.Xr man 5
+format
+.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day
+is accepted, too.
.It
If a date string cannot be parsed, it is used verbatim.
.It
@@ -1343,7 +1358,7 @@ See also
and
.Sx \&Os .
.Ss \&Dl
-One-line intended display.
+One-line indented display.
This is formatted as literal text and is useful for commands and
invocations.
It is followed by a newline.
@@ -1352,7 +1367,9 @@ Examples:
.Dl \&.Dl % mandoc mdoc.5 \e(ba less
.Pp
See also
+.Sx \&Ql ,
.Sx \&Bd
+.Fl literal ,
and
.Sx \&D1 .
.Ss \&Do
@@ -1386,39 +1403,33 @@ See also
and
.Sx \&Do .
.Ss \&Dt
-Document title.
+Document title for display in the page header.
This is the mandatory second macro of any
.Nm
file.
Its syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Sx \&Dt
-.Oo
-.Ar title
-.Oo
+.Ar TITLE
.Ar section
-.Op Ar volume
.Op Ar arch
-.Oc
-.Oc
.Ed
.Pp
Its arguments are as follows:
-.Bl -tag -width Ds -offset Ds
-.It Ar title
+.Bl -tag -width section -offset 2n
+.It Ar TITLE
The document's title (name), defaulting to
-.Dq UNKNOWN
-if unspecified.
-It should be capitalised.
-.It Ar section
-The manual section. It should correspond to the manual's filename suffix
-and defaults to
-.Dq 1
+.Dq UNTITLED
if unspecified.
-.It Ar volume
-This overrides the volume inferred from
-.Ar section .
+To achieve a uniform appearance of page header lines,
+it should by convention be all caps.
+.It Ar SECTION
+The manual section.
+It should correspond to the manual's filename suffix and defaults to
+the empty string if unspecified.
This field is optional.
+To achieve a uniform appearance of page header lines,
+it should by convention be all caps.
.It Ar arch
This specifies the machine architecture a manual page applies to,
where relevant.
@@ -1436,11 +1447,16 @@ See also
.Sx \&Er
and
.Sx \&Ev
-for special-purpose constants and
+for special-purpose constants,
.Sx \&Va
-for variable symbols.
+for variable symbols, and
+.Sx \&Fd
+for listing preprocessor variable definitions in the
+.Em SYNOPSIS .
.Ss \&Dx
-Format the DragonFly BSD version provided as an argument, or a default
+Format the
+.Dx
+version provided as an argument, or a default
value if no argument is provided.
.Pp
Examples:
@@ -1453,9 +1469,8 @@ See also
.Sx \&Bx ,
.Sx \&Fx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Ec
Close a scope started by
.Sx \&Eo .
@@ -1486,16 +1501,29 @@ See also
and
.Sx \&It .
.Ss \&Em
-Denotes text that should be
-.Em emphasised .
-Note that this is a presentation term and should not be used for
-stylistically decorating technical terms.
-Depending on the output device, this is usually represented
-using an italic font or underlined characters.
+Request an italic font.
+If the output device does not provide that, underline.
+.Pp
+This is most often used for stress emphasis (not to be confused with
+importance, see
+.Sx \&Sy ) .
+In the rare cases where none of the semantic markup macros fit,
+it can also be used for technical terms and placeholders, except
+that for syntax elements,
+.Sx \&Sy
+and
+.Sx \&Ar
+are preferred, respectively.
.Pp
Examples:
-.Dl \&.Em Warnings!
-.Dl \&.Em Remarks :
+.Bd -literal -compact -offset indent
+Selected lines are those
+\&.Em not
+matching any of the specified patterns.
+Some of the functions use a
+\&.Em hold space
+to save the pattern space for subsequent retrieval.
+.Ed
.Pp
See also
.Sx \&Bf ,
@@ -1504,8 +1532,14 @@ See also
and
.Sx \&Sy .
.Ss \&En
-This macro is obsolete and not implemented in
-.Xr mandoc 1 .
+This macro is obsolete.
+Use
+.Sx \&Eo
+or any of the other enclosure macros.
+.Pp
+It encloses its argument in the delimiters specified by the last
+.Sx \&Es
+macro.
.Ss \&Eo
An arbitrary enclosure.
Its syntax is as follows:
@@ -1531,7 +1565,14 @@ See also
.Sx \&Dv
for general constants.
.Ss \&Es
-This macro is obsolete and not implemented.
+This macro is obsolete.
+Use
+.Sx \&Eo
+or any of the other enclosure macros.
+.Pp
+It takes two arguments, defining the delimiters to be used by subsequent
+.Sx \&En
+macros.
.Ss \&Ev
Environmental variables such as those specified in
.Xr environ 5 .
@@ -1563,23 +1604,35 @@ arguments are treated as separate utilities.
See also
.Sx \&Rv .
.Ss \&Fa
-Function argument.
+Function argument or parameter.
Its syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Sx \&Fa
-.Op Cm argtype
-.Cm argname
+.Qo
+.Op Ar argtype
+.Op Ar argname
+.Qc Ar \&...
.Ed
.Pp
-This may be invoked for names with or without the corresponding type.
-It is also used to specify the field name of a structure.
+Each argument may be a name and a type (recommended for the
+.Em SYNOPSIS
+section), a name alone (for function invocations),
+or a type alone (for function prototypes).
+If both a type and a name are given or if the type consists of multiple
+words, all words belonging to the same function argument have to be
+given in a single argument to the
+.Sx \&Fa
+macro.
+.Pp
+This macro is also used to specify the field name of a structure.
+.Pp
Most often, the
.Sx \&Fa
macro is used in the
.Em SYNOPSIS
within
.Sx \&Fo
-section when documenting multi-line function prototypes.
+blocks when documenting multi-line function prototypes.
If invoked with multiple arguments, the arguments are separated by a
comma.
Furthermore, if the following macro is another
@@ -1589,7 +1642,7 @@ the last argument will also have a trailing comma.
Examples:
.Dl \&.Fa \(dqconst char *p\(dq
.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
-.Dl \&.Fa foo
+.Dl \&.Fa \(dqchar *\(dq size_t
.Pp
See also
.Sx \&Fo .
@@ -1597,15 +1650,32 @@ See also
End a function context started by
.Sx \&Fo .
.Ss \&Fd
-Historically used to document include files.
-This usage has been deprecated in favour of
+Preprocessor directive, in particular for listing it in the
+.Em SYNOPSIS .
+Historically, it was also used to document include files.
+The latter usage has been deprecated in favour of
.Sx \&In .
-Do not use this macro.
+.Pp
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Fd
+.Li # Ns Ar directive
+.Op Ar argument ...
+.Ed
+.Pp
+Examples:
+.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler
+.Dl \&.Fd #define SIO_MAXNFDS
+.Dl \&.Fd #ifdef FS_DEBUG
+.Dl \&.Ft void
+.Dl \&.Fn dbg_open \(dqconst char *\(dq
+.Dl \&.Fd #endif
.Pp
See also
-.Sx MANUAL STRUCTURE
+.Sx MANUAL STRUCTURE ,
+.Sx \&In ,
and
-.Sx \&In .
+.Sx \&Dv .
.Ss \&Fl
Command-line flag or option.
Used when listing arguments to command-line utilities.
@@ -1675,7 +1745,7 @@ Invocations usually occur in the following context:
.br
.Pf \. Sx \&Fo Ar funcname
.br
-.Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname
+.Pf \. Sx \&Fa Qq Ar argtype Ar argname
.br
\&.\.\.
.br
@@ -1694,13 +1764,10 @@ See also
and
.Sx \&Ft .
.Ss \&Fr
-This macro is obsolete and not implemented in
-.Xr mandoc 1 .
-.Pp
-It was used to show function return values.
-The syntax was:
+This macro is obsolete.
+No replacement markup is needed.
.Pp
-.Dl Pf . Sx \&Fr Ar value
+It was used to show numerical function return values in an italic font.
.Ss \&Ft
A function type.
Its syntax is as follows:
@@ -1739,9 +1806,8 @@ See also
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Hf
This macro is not implemented in
.Xr mandoc 1 .
@@ -1769,17 +1835,18 @@ is preferred for displaying code; the
.Sx \&Ic
macro is used when referring to specific instructions.
.Ss \&In
-An
-.Dq include
-file.
+The name of an include file.
+This macro is most often used in section 2, 3, and 9 manual pages.
+.Pp
When invoked as the first macro on an input line in the
.Em SYNOPSIS
section, the argument is displayed in angle brackets
and preceded by
-.Dq #include ,
+.Qq #include ,
and a blank line is inserted in front if there is a preceding
function declaration.
-This is most often used in section 2, 3, and 9 manual pages.
+In other sections, it only encloses its argument in angle brackets
+and causes no line break.
.Pp
Examples:
.Dl \&.In sys/types.h
@@ -1937,13 +2004,12 @@ Its syntax is as follows:
.Pp
Examples:
.Dl \&.Mt discuss@manpages.bsd.lv
+.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv
.Ss \&Nd
A one line description of the manual's content.
-This may only be invoked in the
-.Em SYNOPSIS
-section subsequent the
-.Sx \&Nm
-macro.
+This is the mandatory last macro of the
+.Em NAME
+section and not appropriate for other sections.
.Pp
Examples:
.Dl Pf . Sx \&Nd mdoc language reference
@@ -1963,7 +2029,7 @@ See also
.Sx \&Nm .
.Ss \&Nm
The name of the manual page, or \(em in particular in section 1
-and 1M pages \(em of an additional command or feature documented in
+pages \(em of an additional command or feature documented in
the manual page.
When first invoked, the
.Sx \&Nm
@@ -2058,9 +2124,8 @@ See also
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Oc
Close multi-line
.Sx \&Oo
@@ -2089,7 +2154,7 @@ Examples:
See also
.Sx \&Oo .
.Ss \&Os
-Document operating system version.
+Operating system version for display in the page footer.
This is the mandatory third macro of
any
.Nm
@@ -2101,8 +2166,16 @@ Its syntax is as follows:
The optional
.Ar system
parameter specifies the relevant operating system or environment.
-Left unspecified, it defaults to the local operating system version.
-This is the suggested form.
+It is suggested to leave it unspecified, in which case
+.Xr mandoc 1
+uses its
+.Fl Ios
+argument, or, if that isn't specified either,
+.Fa sysname
+and
+.Fa release
+as returned by
+.Xr uname 3 .
.Pp
Examples:
.Dl \&.Os
@@ -2114,11 +2187,15 @@ See also
and
.Sx \&Dt .
.Ss \&Ot
-This macro is obsolete and not implemented in
-.Xr mandoc 1 .
+This macro is obsolete.
+Use
+.Sx \&Ft
+instead; with
+.Xr mandoc 1 ,
+both have the same effect.
.Pp
Historical
-.Xr mdoc 5
+.Nm
packages described it as
.Dq "old function type (FORTRAN)" .
.Ss \&Ox
@@ -2137,9 +2214,8 @@ See also
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
-.Sx \&Nx ,
and
-.Sx \&Ux .
+.Sx \&Nx .
.Ss \&Pa
An absolute or relative file system path, or a file or directory name.
If an argument is not provided, the character
@@ -2203,11 +2279,21 @@ See also
Close quoted context opened by
.Sx \&Qo .
.Ss \&Ql
-Format a single-quoted literal.
+In-line literal display.
+This can for example be used for complete command invocations and
+for multi-word code fragments when more specific markup is not
+appropriate and an indented display is not desired.
+While
+.Xr mandoc 1
+always encloses the arguments in single quotes, other formatters
+usually omit the quotes on non-terminal output devices when the
+arguments have three or more characters.
+.Pp
See also
-.Sx \&Qq
+.Sx \&Dl
and
-.Sx \&Sq .
+.Sx \&Bd
+.Fl literal .
.Ss \&Qo
Multi-line version of
.Sx \&Qq .
@@ -2313,7 +2399,7 @@ and
Switches the spacing mode for output generated from macros.
Its syntax is as follows:
.Pp
-.D1 Pf \. Sx \&Sm Cm on | off
+.D1 Pf \. Sx \&Sm Op Cm on | off
.Pp
By default, spacing is
.Cm on .
@@ -2322,6 +2408,11 @@ When switched
no white space is inserted between macro arguments and between the
output generated from adjacent macros, but text lines
still get normal spacing between words and sentences.
+.Pp
+When called without an argument, the
+.Sx \&Sm
+macro toggles the spacing mode.
+Using this is not recommended because it makes the code harder to read.
.Ss \&So
Multi-line version of
.Sx \&Sq .
@@ -2359,105 +2450,218 @@ and
.Sx \&Sx .
.Ss \&St
Replace an abbreviation for a standard with the full form.
-The following standards are recognised:
-.Pp
-.Bl -tag -width "-p1003.1g-2000X" -compact
-.It \-p1003.1-88
-.St -p1003.1-88
-.It \-p1003.1-90
-.St -p1003.1-90
-.It \-p1003.1-96
-.St -p1003.1-96
-.It \-p1003.1-2001
-.St -p1003.1-2001
-.It \-p1003.1-2004
-.St -p1003.1-2004
-.It \-p1003.1-2008
-.St -p1003.1-2008
-.It \-p1003.1
-.St -p1003.1
-.It \-p1003.1b
-.St -p1003.1b
-.It \-p1003.1b-93
-.St -p1003.1b-93
-.It \-p1003.1c-95
-.St -p1003.1c-95
-.It \-p1003.1g-2000
-.St -p1003.1g-2000
-.It \-p1003.1i-95
-.St -p1003.1i-95
-.It \-p1003.2-92
-.St -p1003.2-92
-.It \-p1003.2a-92
-.St -p1003.2a-92
-.It \-p1387.2-95
-.St -p1387.2-95
-.It \-p1003.2
-.St -p1003.2
-.It \-p1387.2
-.St -p1387.2
+The following standards are recognised.
+Where multiple lines are given without a blank line in between,
+they all refer to the same standard, and using the first form
+is recommended.
+.Bl -tag -width 1n
+.It C language standards
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
+.It \-ansiC
+.St -ansiC
+.It \-ansiC-89
+.St -ansiC-89
.It \-isoC
.St -isoC
.It \-isoC-90
.St -isoC-90
+.br
+The original C standard.
+.Pp
.It \-isoC-amd1
.St -isoC-amd1
+.Pp
.It \-isoC-tcor1
.St -isoC-tcor1
+.Pp
.It \-isoC-tcor2
.St -isoC-tcor2
+.Pp
.It \-isoC-99
.St -isoC-99
+.br
+The second major version of the C language standard.
+.Pp
.It \-isoC-2011
.St -isoC-2011
+.br
+The third major version of the C language standard.
+.El
+.It POSIX.1 before the Single UNIX Specification
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
+.It \-p1003.1-88
+.St -p1003.1-88
+.It \-p1003.1
+.St -p1003.1
+.br
+The original POSIX standard, based on ANSI C.
+.Pp
+.It \-p1003.1-90
+.St -p1003.1-90
.It \-iso9945-1-90
.St -iso9945-1-90
+.br
+The first update of POSIX.1.
+.Pp
+.It \-p1003.1b-93
+.St -p1003.1b-93
+.It \-p1003.1b
+.St -p1003.1b
+.br
+Real-time extensions.
+.Pp
+.It \-p1003.1c-95
+.St -p1003.1c-95
+.br
+POSIX thread interfaces.
+.Pp
+.It \-p1003.1i-95
+.St -p1003.1i-95
+.br
+Technical Corrigendum.
+.Pp
+.It \-p1003.1-96
+.St -p1003.1-96
.It \-iso9945-1-96
.St -iso9945-1-96
-.It \-iso9945-2-93
-.St -iso9945-2-93
-.It \-ansiC
-.St -ansiC
-.It \-ansiC-89
-.St -ansiC-89
-.It \-ansiC-99
-.St -ansiC-99
-.It \-ieee754
-.St -ieee754
-.It \-iso8802-3
-.St -iso8802-3
-.It \-iso8601
-.St -iso8601
-.It \-ieee1275-94
-.St -ieee1275-94
+.br
+Includes POSIX.1-1990, 1b, 1c, and 1i.
+.El
+.It X/Open Portability Guide version 4 and related standards
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
.It \-xpg3
.St -xpg3
+.br
+An XPG4 precursor, published in 1989.
+.Pp
+.It \-p1003.2
+.St -p1003.2
+.It \-p1003.2-92
+.St -p1003.2-92
+.It \-iso9945-2-93
+.St -iso9945-2-93
+.br
+An XCU4 precursor.
+.Pp
+.It \-p1003.2a-92
+.St -p1003.2a-92
+.br
+Updates to POSIX.2.
+.Pp
.It \-xpg4
.St -xpg4
+.br
+Based on POSIX.1 and POSIX.2, published in 1992.
+.El
+.It Single UNIX Specification version 1 and related standards
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
+.It \-susv1
+.St -susv1
.It \-xpg4.2
.St -xpg4.2
-.It \-xpg4.3
-.St -xpg4.3
+.br
+This standard was published in 1994.
+It was used as the basis for UNIX 95 certification.
+The following three refer to parts of it.
+.Pp
+.It \-xsh4.2
+.St -xsh4.2
+.Pp
+.It \-xcurses4.2
+.St -xcurses4.2
+.Pp
+.It \-p1003.1g-2000
+.St -p1003.1g-2000
+.br
+Networking APIs, including sockets.
+.Pp
+.It \-svid4
+.St -svid4 ,
+.br
+Published in 1995.
+.El
+.It Single UNIX Specification version 2 and related standards
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
+.It \-susv2
+.St -susv2
+This Standard was published in 1997
+and is also called X/Open Portability Guide version 5.
+It was used as the basis for UNIX 98 certification.
+The following refer to parts of it.
+.Pp
.It \-xbd5
.St -xbd5
-.It \-xcu5
-.St -xcu5
+.Pp
.It \-xsh5
.St -xsh5
+.Pp
+.It \-xcu5
+.St -xcu5
+.Pp
.It \-xns5
.St -xns5
.It \-xns5.2
.St -xns5.2
-.It \-xns5.2d2.0
-.St -xns5.2d2.0
-.It \-xcurses4.2
-.St -xcurses4.2
-.It \-susv2
-.St -susv2
+.El
+.It Single UNIX Specification version 3
+.Pp
+.Bl -tag -width "-p1003.1-2001" -compact
+.It \-p1003.1-2001
+.St -p1003.1-2001
.It \-susv3
.St -susv3
-.It \-svid4
-.St -svid4
+.br
+This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j.
+It is also called X/Open Portability Guide version 6.
+It is used as the basis for UNIX 03 certification.
+.Pp
+.It \-p1003.1-2004
+.St -p1003.1-2004
+.br
+The second and last Technical Corrigendum.
+.El
+.It Single UNIX Specification version 4
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
+.It \-p1003.1-2008
+.St -p1003.1-2008
+.It \-susv4
+.St -susv4
+.br
+This standard is also called
+X/Open Portability Guide version 7.
+.Pp
+.It \-p1003.1-2013
+.St -p1003.1-2013
+.br
+This is the first Technical Corrigendum.
+.El
+.It Other standards
+.Pp
+.Bl -tag -width "-p1003.1g-2000" -compact
+.It \-ieee754
+.St -ieee754
+.br
+Floating-point arithmetic.
+.Pp
+.It \-iso8601
+.St -iso8601
+.br
+Representation of dates and times, published in 1988.
+.Pp
+.It \-iso8802-3
+.St -iso8802-3
+.br
+Ethernet local area networks.
+.Pp
+.It \-ieee1275-94
+.St -ieee1275-94
+.El
.El
.Ss \&Sx
Reference a section or subsection in the same manual page.
@@ -2472,10 +2676,24 @@ See also
and
.Sx \&Ss .
.Ss \&Sy
-Format enclosed arguments in symbolic
-.Pq Dq boldface .
-Note that this is a presentation term and should not be used for
-stylistically decorating technical terms.
+Request a boldface font.
+.Pp
+This is most often used to indicate importance or seriousness (not to be
+confused with stress emphasis, see
+.Sx \&Em ) .
+When none of the semantic macros fit, it is also adequate for syntax
+elements that have to be given or that appear verbatim.
+.Pp
+Examples:
+.Bd -literal -compact -offset indent
+\&.Sy Warning :
+If
+\&.Sy s
+appears in the owner permissions, set-user-ID mode is set.
+This utility replaces the former
+\&.Sy dumpdir
+program.
+.Ed
.Pp
See also
.Sx \&Bf ,
@@ -2489,42 +2707,36 @@ Table cell separator in
lists; can only be used below
.Sx \&It .
.Ss \&Tn
-Format a tradename.
-.Pp
-Since this macro is often implemented to use a small caps font,
-it has historically been used for acronyms (like ASCII) as well.
-Such usage is not recommended because it would use the same macro
-sometimes for semantical annotation, sometimes for physical formatting.
-.Pp
-Examples:
-.Dl \&.Tn IBM
+Supported only for compatibility, do not use this in new manuals.
+Even though the macro name
+.Pq Dq tradename
+suggests a semantic function, historic usage is inconsistent, mostly
+using it as a presentation-level macro to request a small caps font.
.Ss \&Ud
+Supported only for compatibility, do not use this in new manuals.
Prints out
.Dq currently under development.
.Ss \&Ux
-Format the UNIX name.
-Accepts no argument.
-.Pp
-Examples:
-.Dl \&.Ux
-.Pp
-See also
-.Sx \&At ,
-.Sx \&Bsx ,
-.Sx \&Bx ,
-.Sx \&Dx ,
-.Sx \&Fx ,
-.Sx \&Nx ,
-and
-.Sx \&Ox .
+Supported only for compatibility, do not use this in new manuals.
+Prints out
+.Dq Ux .
.Ss \&Va
A variable name.
.Pp
Examples:
.Dl \&.Va foo
.Dl \&.Va const char *bar ;
+.Pp
+For function arguments and parameters, use
+.Sx \&Fa
+instead.
+For declarations of global variables in the
+.Em SYNOPSIS
+section, use
+.Sx \&Vt .
.Ss \&Vt
A variable type.
+.Pp
This is also used for indicating global variables in the
.Em SYNOPSIS
section, in which case a variable name is also specified.
@@ -2539,18 +2751,21 @@ In the former case, this macro starts a new output line,
and a blank line is inserted in front if there is a preceding
function definition or include directive.
.Pp
-Note that this should not be confused with
-.Sx \&Ft ,
-which is used for function return types.
-.Pp
Examples:
.Dl \&.Vt unsigned char
.Dl \&.Vt extern const char * const sys_signame[] \&;
.Pp
+For parameters in function prototypes, use
+.Sx \&Fa
+instead, for function return types
+.Sx \&Ft ,
+and for variable names outside the
+.Em SYNOPSIS
+section
+.Sx \&Va ,
+even when including a type with the name.
See also
-.Sx MANUAL STRUCTURE
-and
-.Sx \&Va .
+.Sx MANUAL STRUCTURE .
.Ss \&Xc
Close a scope opened by
.Sx \&Xo .
@@ -2561,26 +2776,20 @@ macro or the body of a partial-implicit block macro
beyond the end of the input line.
This macro originally existed to work around the 9-argument limit
of historic
-.Xr roff 5 .
+.Xr mandoc_roff 5 .
.Ss \&Xr
Link to another manual
.Pq Qq cross-reference .
Its syntax is as follows:
.Pp
-.D1 Pf \. Sx \&Xr Ar name section
+.D1 Pf \. Sx \&Xr Ar name Op section
.Pp
-The
+Cross reference the
.Ar name
and
.Ar section
-are the name and section of the linked manual.
-If
-.Ar section
-is followed by non-punctuation, an
-.Sx \&Ns
-is inserted into the token stream.
-This behaviour is for compatibility with
-GNU troff.
+number of another man page;
+omitting the section number is rarely useful.
.Pp
Examples:
.Dl \&.Xr mandoc 1
@@ -2604,8 +2813,8 @@ Its syntax is as follows:
.Pp
The
.Ar height
-argument must be formatted as described in
-.Sx Scaling Widths .
+argument is a scaling width as described in
+.Xr mandoc_roff 5 .
If unspecified,
.Sx \&sp
asserts a single vertical space.
@@ -2774,6 +2983,7 @@ end of the line.
.It Sx \&D1 Ta \&No Ta \&Yes
.It Sx \&Dl Ta \&No Ta Yes
.It Sx \&Dq Ta Yes Ta Yes
+.It Sx \&En Ta Yes Ta Yes
.It Sx \&Op Ta Yes Ta Yes
.It Sx \&Pq Ta Yes Ta Yes
.It Sx \&Ql Ta Yes Ta Yes
@@ -2851,16 +3061,15 @@ then the macro accepts an arbitrary number of arguments.
.It Sx \&Dv Ta Yes Ta Yes Ta >0
.It Sx \&Dx Ta Yes Ta Yes Ta n
.It Sx \&Em Ta Yes Ta Yes Ta >0
-.It Sx \&En Ta \&No Ta \&No Ta 0
.It Sx \&Er Ta Yes Ta Yes Ta >0
-.It Sx \&Es Ta \&No Ta \&No Ta 0
+.It Sx \&Es Ta Yes Ta Yes Ta 2
.It Sx \&Ev Ta Yes Ta Yes Ta >0
.It Sx \&Ex Ta \&No Ta \&No Ta n
.It Sx \&Fa Ta Yes Ta Yes Ta >0
.It Sx \&Fd Ta \&No Ta \&No Ta >0
.It Sx \&Fl Ta Yes Ta Yes Ta n
.It Sx \&Fn Ta Yes Ta Yes Ta >0
-.It Sx \&Fr Ta \&No Ta \&No Ta n
+.It Sx \&Fr Ta Yes Ta Yes Ta >0
.It Sx \&Ft Ta Yes Ta Yes Ta >0
.It Sx \&Fx Ta Yes Ta Yes Ta n
.It Sx \&Hf Ta \&No Ta \&No Ta n
@@ -2877,13 +3086,13 @@ then the macro accepts an arbitrary number of arguments.
.It Sx \&Ns Ta Yes Ta Yes Ta 0
.It Sx \&Nx Ta Yes Ta Yes Ta n
.It Sx \&Os Ta \&No Ta \&No Ta n
-.It Sx \&Ot Ta \&No Ta \&No Ta n
+.It Sx \&Ot Ta Yes Ta Yes Ta >0
.It Sx \&Ox Ta Yes Ta Yes Ta n
.It Sx \&Pa Ta Yes Ta Yes Ta n
.It Sx \&Pf Ta Yes Ta Yes Ta 1
.It Sx \&Pp Ta \&No Ta \&No Ta 0
.It Sx \&Rv Ta \&No Ta \&No Ta n
-.It Sx \&Sm Ta \&No Ta \&No Ta 1
+.It Sx \&Sm Ta \&No Ta \&No Ta <2
.It Sx \&St Ta \&No Ta Yes Ta 1
.It Sx \&Sx Ta Yes Ta Yes Ta >0
.It Sx \&Sy Ta Yes Ta Yes Ta >0
@@ -2991,58 +3200,22 @@ macros.
Whenever any
.Nm
macro switches the
-.Xr roff 5
+.Xr mandoc_roff 5
font mode, it will automatically restore the previous font when exiting
its scope.
Manually switching the font using the
-.Xr roff 5
+.Xr mandoc_roff 5
.Ql \ef
font escape sequences is never required.
.Sh COMPATIBILITY
-This section documents compatibility between mandoc and other other
-troff implementations, at this time limited to GNU troff
+This section provides an incomplete list of compatibility issues
+between mandoc and GNU troff
.Pq Qq groff .
-The term
-.Qq historic groff
-refers to groff versions before 1.17,
-which featured a significant update of the
-.Pa doc.tmac
-file.
-.Pp
-Heirloom troff, the other significant troff implementation accepting
-\-mdoc, is similar to historic groff.
.Pp
The following problematic behaviour is found in groff:
-.ds hist (Historic groff only.)
.Pp
.Bl -dash -compact
.It
-Display macros
-.Po
-.Sx \&Bd ,
-.Sx \&Dl ,
-and
-.Sx \&D1
-.Pc
-may not be nested.
-\*[hist]
-.It
-.Sx \&At
-with unknown arguments produces no output at all.
-\*[hist]
-Newer groff and mandoc print
-.Qq AT&T UNIX
-and the arguments.
-.It
-.Sx \&Bl Fl column
-does not recognise trailing punctuation characters when they immediately
-precede tabulator characters, but treats them as normal text and
-outputs a space before them.
-.It
-.Sx \&Bd Fl ragged compact
-does not start a new line.
-\*[hist]
-.It
.Sx \&Dd
with non-standard arguments behaves very strangely.
When there are three arguments, they are printed verbatim.
@@ -3051,53 +3224,6 @@ but without any arguments the string
.Dq Epoch
is printed.
.It
-.Sx \&Fl
-does not print a dash for an empty argument.
-\*[hist]
-.It
-.Sx \&Fn
-does not start a new line unless invoked as the line macro in the
-.Em SYNOPSIS
-section.
-\*[hist]
-.It
-.Sx \&Fo
-with
-.Pf non- Sx \&Fa
-children causes inconsistent spacing between arguments.
-In mandoc, a single space is always inserted between arguments.
-.It
-.Sx \&Ft
-in the
-.Em SYNOPSIS
-causes inconsistent vertical spacing, depending on whether a prior
-.Sx \&Fn
-has been invoked.
-See
-.Sx \&Ft
-and
-.Sx \&Fn
-for the normalised behaviour in mandoc.
-.It
-.Sx \&In
-ignores additional arguments and is not treated specially in the
-.Em SYNOPSIS .
-\*[hist]
-.It
-.Sx \&It
-sometimes requires a
-.Fl nested
-flag.
-\*[hist]
-In new groff and mandoc, any list may be nested by default and
-.Fl enum
-lists will restart the sequence only for the sub-list.
-.It
-.Sx \&Li
-followed by a delimiter is incorrectly used in some manuals
-instead of properly quoting that character, which sometimes works with
-historic groff.
-.It
.Sx \&Lk
only accepts a single link-name argument; the remainder is misformatted.
.It
@@ -3109,25 +3235,12 @@ certain list types.
can only be called by other macros, but not at the beginning of a line.
.It
.Sx \&%C
-is not implemented.
-.It
-Historic groff only allows up to eight or nine arguments per macro input
-line, depending on the exact situation.
-Providing more arguments causes garbled output.
-The number of arguments on one input line is not limited with mandoc.
-.It
-Historic groff has many un-callable macros.
-Most of these (excluding some block-level macros) are callable
-in new groff and mandoc.
-.It
-.Sq \(ba
-(vertical bar) is not fully supported as a delimiter.
-\*[hist]
+is not implemented (up to and including groff-1.22.2).
.It
.Sq \ef
.Pq font face
and
-.Sq \ef
+.Sq \eF
.Pq font family face
.Sx Text Decoration
escapes behave irregularly when specified within line-macro scopes.
@@ -3141,44 +3254,28 @@ The following features are unimplemented in mandoc:
.Bl -dash -compact
.It
.Sx \&Bd
-.Fl file Ar file .
+.Fl file Ar file
+is unsupported for security reasons.
.It
.Sx \&Bd
-.Fl offset Ar center
-and
-.Fl offset Ar right .
-Groff does not implement centred and flush-right rendering either,
-but produces large indentations.
-.It
-The
-.Sq \eh
-.Pq horizontal position ,
-.Sq \ev
-.Pq vertical position ,
-.Sq \em
-.Pq text colour ,
-.Sq \eM
-.Pq text filling colour ,
-.Sq \ez
-.Pq zero-length character ,
-.Sq \ew
-.Pq string length ,
-.Sq \ek
-.Pq horizontal position marker ,
-.Sq \eo
-.Pq text overstrike ,
-and
-.Sq \es
-.Pq text size
-escape sequences are all discarded in mandoc.
+.Fl filled
+does not adjust the right margin, but is an alias for
+.Sx \&Bd
+.Fl ragged .
.It
-The
-.Sq \ef
-scaling unit is accepted by mandoc, but rendered as the default unit.
+.Sx \&Bd
+.Fl literal
+does not use a literal font, but is an alias for
+.Sx \&Bd
+.Fl unfilled .
.It
-In quoted literals, groff allows pairwise double-quotes to produce a
-standalone double-quote in formatted output.
-This is not supported by mandoc.
+.Sx \&Bd
+.Fl offset Cm center
+and
+.Fl offset Cm right
+don't work.
+Groff does not implement centered and flush-right rendering either,
+but produces large indentations.
.El
.Sh SEE ALSO
.Xr man 1 ,
@@ -3186,7 +3283,7 @@ This is not supported by mandoc.
.Xr eqn 5 ,
.Xr man 5 ,
.Xr mandoc_char 5 ,
-.Xr roff 5 ,
+.Xr mandoc_roff 5 ,
.Xr tbl 5
.Sh HISTORY
The
@@ -3203,5 +3300,4 @@ utility written by Kristaps Dzonsons appeared in
The
.Nm
reference was written by
-.An Kristaps Dzonsons ,
-.Mt kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
generated by cgit v1.2.3 (git 2.39.1) at 2025-06-01 17:23:12 +0000