Bugfix: When the invocation of a user-defined macro follows a roff

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 0706a19b7b01506fd3efa56cee7f160e94491b89..13b53be5431c011b0dd48b9f77c04e6d1015db18 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.230 2014/06/24 21:43:08 schwarze Exp $
+.\"    $Id: mdoc.7,v 1.248 2015/01/03 00:59:13 schwarze Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: June 24 2014 $
+.Dd $Mdocdate: January 3 2015 $

 .Dt MDOC 7
 .Os
 .Sh NAME
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -388,7 +388,7 @@ See
 References other manuals with related topics.
 This section should exist for most manuals.
 Cross-references should conventionally be ordered first by section, then
 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
 .Pp
 References to other documentation concerning the topic of the manual page,
 for example authoritative books or journal articles, may also be


@@ -433,7 +433,7 @@ in the alphabetical
 .Ss Document preamble and NAME section macros
 .Bl -column "Brq, Bro, Brc" description
 .It Sx \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year
 .Ss Document preamble and NAME section macros
 .Bl -column "Brq, Bro, Brc" description
 .It Sx \&Dd Ta document date: Cm $\&Mdocdate$ | 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)
 .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)


@@ -454,6 +454,7 @@ in the alphabetical
 .Op Fl compact
 .It Sx \&D1 Ta indented display (one line)
 .It Sx \&Dl Ta indented literal display (one line)
 .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
 .It Sx \&Bl , \&El Ta list block:
 .Fl Ar type
 .Op Fl width Ar val


@@ -468,7 +469,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 \&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
 .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


@@ -528,7 +529,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 \&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
 .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


@@ -937,8 +937,11 @@ The
 .Fl width
 and
 .Fl offset
 .Fl width
 and
 .Fl offset

-arguments accept scaling widths as described in
-.Xr roff 7
+arguments accept macro names as described for
+.Sx \&Bd
+.Fl offset ,
+scaling widths as described in
+.Xr roff 7 ,

 or use the length of the given string.
 The
 .Fl offset
 or use the length of the given string.
 The
 .Fl offset


@@ -1182,20 +1185,19 @@ See also
 and
 .Sx \&Dl .
 .Ss \&Db
 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
 .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.
 This is the mandatory first macro of any
 .Nm
 manual.


@@ -1224,8 +1226,11 @@ the special string
 .Dq $\&Mdocdate$
 can be given as an argument.
 .It
 .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 7
+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
 .It
 If a date string cannot be parsed, it is used verbatim.
 .It


@@ -1242,7 +1247,7 @@ See also
 and
 .Sx \&Os .
 .Ss \&Dl
 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.
 This is formatted as literal text and is useful for commands and
 invocations.
 It is followed by a newline.


@@ -1251,7 +1256,9 @@ Examples:
 .Dl \&.Dl % mandoc mdoc.7 \e(ba less
 .Pp
 See also
 .Dl \&.Dl % mandoc mdoc.7 \e(ba less
 .Pp
 See also

+.Sx \&Ql ,

 .Sx \&Bd
 .Sx \&Bd

+.Fl literal ,

 and
 .Sx \&D1 .
 .Ss \&Do
 and
 .Sx \&D1 .
 .Ss \&Do


@@ -1285,98 +1292,52 @@ See also
 and
 .Sx \&Do .
 .Ss \&Dt
 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
 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
 .Ar section

-.Op Ar volume

 .Op Ar arch
 .Op Ar arch

-.Oc
-.Oc

 .Ed
 .Pp
 Its arguments are as follows:
 .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
 The document's title (name), defaulting to

-.Dq UNKNOWN
+.Dq UNTITLED

 if unspecified.
 if unspecified.

-It should be capitalised.
+To achieve a uniform appearance of page header lines,
+it should by convention be all caps.

 .It Ar section
 The manual section.
 This may be one of
 .Cm 1
 .It Ar section
 The manual section.
 This may be one of
 .Cm 1

-.Pq utilities ,
+.Pq General Commands ,

 .Cm 2
 .Cm 2

-.Pq system calls ,
+.Pq System Calls ,

 .Cm 3
 .Cm 3

-.Pq libraries ,
+.Pq Library Functions ,

 .Cm 3p
 .Cm 3p

-.Pq Perl libraries ,
+.Pq Perl Library ,

 .Cm 4
 .Cm 4

-.Pq devices ,
+.Pq Device Drivers ,

 .Cm 5
 .Cm 5

-.Pq file formats ,
+.Pq File Formats ,

 .Cm 6
 .Cm 6

-.Pq games ,
+.Pq Games ,

 .Cm 7
 .Cm 7

-.Pq miscellaneous ,
+.Pq Miscellaneous Information ,

 .Cm 8
 .Cm 8

-.Pq system utilities ,
-.Cm 9
-.Pq kernel functions ,
-.Cm X11
-.Pq X Window System ,
-.Cm X11R6
-.Pq X Window System ,
-.Cm unass
-.Pq unassociated ,
-.Cm local
-.Pq local system ,
-.Cm draft
-.Pq draft manual ,
+.Pq System Manager's Manual ,

 or
 or

-.Cm paper
-.Pq paper .
+.Cm 9
+.Pq Kernel Developer's Manual .

 It should correspond to the manual's filename suffix and defaults to
 It should correspond to the manual's filename suffix and defaults to

-.Cm 1
-if unspecified.
-.It Ar volume
-This overrides the volume inferred from
-.Ar section .
-This field is optional, and if specified, must be one of
-.Cm USD
-.Pq users' supplementary documents ,
-.Cm PS1
-.Pq programmers' supplementary documents ,
-.Cm AMD
-.Pq administrators' supplementary documents ,
-.Cm SMM
-.Pq system managers' manuals ,
-.Cm URM
-.Pq users' reference manuals ,
-.Cm PRM
-.Pq programmers' reference manuals ,
-.Cm KM
-.Pq kernel manuals ,
-.Cm IND
-.Pq master index ,
-.Cm MMI
-.Pq master index ,
-.Cm LOCAL
-.Pq local manuals ,
-.Cm LOC
-.Pq local manuals ,
-or
-.Cm CON
-.Pq contributed manuals .
+the empty string if unspecified.

 .It Ar arch
 This specifies the machine architecture a manual page applies to,
 where relevant, for example
 .It Ar arch
 This specifies the machine architecture a manual page applies to,
 where relevant, for example


@@ -1385,17 +1346,11 @@ where relevant, for example
 .Cm i386 ,
 or
 .Cm sparc64 .
 .Cm i386 ,
 or
 .Cm sparc64 .

-The list of supported architectures varies by operating system.
-For the full list of all architectures recognized by
-.Xr mandoc 1 ,
-see the file
-.Pa arch.in
-in the source distribution.
+The list of valid architectures varies by operating system.

 .El
 .Pp
 Examples:
 .Dl \&.Dt FOO 1
 .El
 .Pp
 Examples:
 .Dl \&.Dt FOO 1

-.Dl \&.Dt FOO 4 KM

 .Dl \&.Dt FOO 9 i386
 .Pp
 See also
 .Dl \&.Dt FOO 9 i386
 .Pp
 See also


@@ -1469,16 +1424,29 @@ See also
 and
 .Sx \&It .
 .Ss \&Em
 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:
 .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 ,
 .Pp
 See also
 .Sx \&Bf ,


@@ -1487,8 +1455,14 @@ See also
 and
 .Sx \&Sy .
 .Ss \&En
 and
 .Sx \&Sy .
 .Ss \&En

-This macro is obsolete and ignored by
-.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:
 .Ss \&Eo
 An arbitrary enclosure.
 Its syntax is as follows:


@@ -1514,8 +1488,14 @@ See also
 .Sx \&Dv
 for general constants.
 .Ss \&Es
 .Sx \&Dv
 for general constants.
 .Ss \&Es

-This macro is obsolete and ignored by
-.Xr mandoc 1 .
+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 7 .
 .Ss \&Ev
 Environmental variables such as those specified in
 .Xr environ 7 .


@@ -1547,23 +1527,35 @@ arguments are treated as separate utilities.
 See also
 .Sx \&Rv .
 .Ss \&Fa
 See also
 .Sx \&Rv .
 .Ss \&Fa

-Function argument.
+Function argument or parameter.

 Its syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Sx \&Fa
 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
 .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
 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
 If invoked with multiple arguments, the arguments are separated by a
 comma.
 Furthermore, if the following macro is another


@@ -1573,7 +1565,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
 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 .
 .Pp
 See also
 .Sx \&Fo .


@@ -1676,7 +1668,7 @@ Invocations usually occur in the following context:
 .br
 .Pf \. Sx \&Fo Ar funcname
 .br
 .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
 .br
 \&.\.\.
 .br


@@ -1695,13 +1687,10 @@ See also
 and
 .Sx \&Ft .
 .Ss \&Fr
 and
 .Sx \&Ft .
 .Ss \&Fr

-This macro is obsolete and ignored by
-.Xr mandoc 1 .
+This macro is obsolete.
+No replacement markup is needed.

 .Pp
 .Pp

-It was used to show function return values.
-The syntax was:
-.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:
 .Ss \&Ft
 A function type.
 Its syntax is as follows:


@@ -2089,7 +2078,7 @@ Examples:
 See also
 .Sx \&Oo .
 .Ss \&Os
 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
 This is the mandatory third macro of
 any
 .Nm


@@ -2101,8 +2090,16 @@ Its syntax is as follows:
 The optional
 .Ar system
 parameter specifies the relevant operating system or environment.
 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
 .Pp
 Examples:
 .Dl \&.Os


@@ -2114,8 +2111,12 @@ See also
 and
 .Sx \&Dt .
 .Ss \&Ot
 and
 .Sx \&Dt .
 .Ss \&Ot

-This macro is obsolete and ignored by
-.Xr mandoc 1 .
+This macro is obsolete.
+Use
+.Sx \&Ft
+instead; with
+.Xr mandoc 1 ,
+both have the same effect.

 .Pp
 Historical
 .Nm
 .Pp
 Historical
 .Nm


@@ -2202,11 +2203,21 @@ See also
 Close quoted context opened by
 .Sx \&Qo .
 .Ss \&Ql
 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
 See also

-.Sx \&Qq
+.Sx \&Dl

 and
 and

-.Sx \&Sq .
+.Sx \&Bd
+.Fl literal .

 .Ss \&Qo
 Multi-line version of
 .Sx \&Qq .
 .Ss \&Qo
 Multi-line version of
 .Sx \&Qq .


@@ -2312,7 +2323,7 @@ and
 Switches the spacing mode for output generated from macros.
 Its syntax is as follows:
 .Pp
 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 .
 .Pp
 By default, spacing is
 .Cm on .


@@ -2321,6 +2332,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.
 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 .
 .Ss \&So
 Multi-line version of
 .Sx \&Sq .


@@ -2388,8 +2404,6 @@ The original C standard.
 .Pp
 .It \-isoC-99
 .St -isoC-99
 .Pp
 .It \-isoC-99
 .St -isoC-99

-.It \-ansiC-99
-.St -ansiC-99

 .br
 The second major version of the C language standard.
 .Pp
 .br
 The second major version of the C language standard.
 .Pp


@@ -2469,10 +2483,12 @@ Based on POSIX.1 and POSIX.2, published in 1992.
 .It Single UNIX Specification version 1 and related standards
 .Pp
 .Bl -tag -width "-p1003.1g-2000" -compact
 .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
 .br
 .It \-xpg4.2
 .St -xpg4.2
 .br

-This standard was published in 1994 and is also called SUSv1.
+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 was used as the basis for UNIX 95 certification.
 The following three refer to parts of it.
 .Pp


@@ -2487,9 +2503,6 @@ The following three refer to parts of it.
 .br
 Networking APIs, including sockets.
 .Pp
 .br
 Networking APIs, including sockets.
 .Pp

-.It \-xpg4.3
-.St -xpg4.3
-.Pp

 .It \-svid4
 .St -svid4 ,
 .br
 .It \-svid4
 .St -svid4 ,
 .br


@@ -2516,36 +2529,12 @@ The following refer to parts of it.
 .Pp
 .It \-xns5
 .St -xns5
 .Pp
 .It \-xns5
 .St -xns5

-.It \-xns5.2d2.0
-.St -xns5.2d2.0

 .It \-xns5.2
 .St -xns5.2
 .It \-xns5.2
 .St -xns5.2

-.Pp
-.It \-p1387.2
-.St -p1387.2
-.It \-p1387.2-95
-.St -p1387.2-95
-.br
-POSIX software administration.

 .El
 .El

-.It Single UNIX Specification version 3 and related standards
-.Pp
-.Bl -tag -width "-p1003.1g-2000X" -compact
-.It \-p1003.1d-99
-.St -p1003.1d-99
-.br
-Additional real-time extensions.
-.Pp
-.It \-p1003.1j-2000
-.St -p1003.1j-2000
-.br
-Advanced real-time extensions.
-.Pp
-.It \-p1003.1q-2000
-.St -p1003.1q-2000
-.br
-Amendment 7: Tracing [C Language].
+.It Single UNIX Specification version 3

 .Pp
 .Pp

+.Bl -tag -width "-p1003.1-2001" -compact

 .It \-p1003.1-2001
 .St -p1003.1-2001
 .It \-susv3
 .It \-p1003.1-2001
 .St -p1003.1-2001
 .It \-susv3


@@ -2565,8 +2554,10 @@ The second and last Technical Corrigendum.
 .Bl -tag -width "-p1003.1g-2000" -compact
 .It \-p1003.1-2008
 .St -p1003.1-2008
 .Bl -tag -width "-p1003.1g-2000" -compact
 .It \-p1003.1-2008
 .St -p1003.1-2008

+.It \-susv4
+.St -susv4

 .br
 .br

-This standard is also called SUSv4 and
+This standard is also called

 X/Open Portability Guide version 7.
 .Pp
 .It \-p1003.1-2013
 X/Open Portability Guide version 7.
 .Pp
 .It \-p1003.1-2013


@@ -2609,10 +2600,24 @@ See also
 and
 .Sx \&Ss .
 .Ss \&Sy
 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 ,
 .Pp
 See also
 .Sx \&Bf ,


@@ -2645,8 +2650,17 @@ A variable name.
 Examples:
 .Dl \&.Va foo
 .Dl \&.Va const char *bar ;
 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.
 .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.
 This is also used for indicating global variables in the
 .Em SYNOPSIS
 section, in which case a variable name is also specified.


@@ -2661,18 +2675,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
 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
 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
 See also

-.Sx MANUAL STRUCTURE
-and
-.Sx \&Va .
+.Sx MANUAL STRUCTURE .

 .Ss \&Xc
 Close a scope opened by
 .Sx \&Xo .
 .Ss \&Xc
 Close a scope opened by
 .Sx \&Xo .


@@ -2890,6 +2907,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 \&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
 .It Sx \&Op  Ta    Yes      Ta    Yes
 .It Sx \&Pq  Ta    Yes      Ta    Yes
 .It Sx \&Ql  Ta    Yes      Ta    Yes


@@ -2967,16 +2985,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 \&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 \&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 \&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
 .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


@@ -2993,13 +3010,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 \&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 \&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
 .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