===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.223
retrieving revision 1.230
diff -u -p -r1.223 -r1.230
--- mandoc/mdoc.7	2013/12/25 14:09:32	1.223
+++ mandoc/mdoc.7	2014/06/24 21:43:08	1.230
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.223 2013/12/25 14:09:32 schwarze Exp $
+.\"	$Id: mdoc.7,v 1.230 2014/06/24 21:43:08 schwarze Exp $
 .\"
 .\" 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.
 .\"
-.Dd $Mdocdate: December 25 2013 $
+.Dd $Mdocdate: June 24 2014 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -125,7 +125,7 @@ file for a utility
 \&.Nm progname
 \&.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.
 \&.\e\(dq Not used in OpenBSD.
 \&.Sh SYNOPSIS
 \&.Nm progname
@@ -135,20 +135,22 @@ file for a utility
 The
 \&.Nm
 utility processes files ...
+\&.\e\(dq .Sh CONTEXT
+\&.\e\(dq For section 9 functions only.
 \&.\e\(dq .Sh IMPLEMENTATION NOTES
 \&.\e\(dq Not used in OpenBSD.
 \&.\e\(dq .Sh RETURN VALUES
-\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq For sections 2, 3, and 9 function return values only.
 \&.\e\(dq .Sh ENVIRONMENT
-\&.\e\(dq For sections 1, 6, 7, & 8 only.
+\&.\e\(dq For sections 1, 6, 7, and 8 only.
 \&.\e\(dq .Sh FILES
 \&.\e\(dq .Sh EXIT STATUS
-\&.\e\(dq For sections 1, 6, & 8 only.
+\&.\e\(dq For sections 1, 6, and 8 only.
 \&.\e\(dq .Sh EXAMPLES
 \&.\e\(dq .Sh DIAGNOSTICS
-\&.\e\(dq For sections 1, 4, 6, 7, & 8 only.
+\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
 \&.\e\(dq .Sh ERRORS
-\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
 \&.\e\(dq .Sh SEE ALSO
 \&.\e\(dq .Xr foobar 1
 \&.\e\(dq .Sh STANDARDS
@@ -318,6 +320,9 @@ macro followed by a non-standard section name, and eac
 several subsections, like in the present
 .Nm
 manual.
+.It Em CONTEXT
+This section lists the contexts in which functions can be called in section 9.
+The contexts are autoconf, process, or interrupt.
 .It Em IMPLEMENTATION NOTES
 Implementation-specific notes should be kept here.
 This is useful when implementing standard functions that may have side
@@ -358,8 +363,12 @@ Example usages.
 This often contains snippets of well-formed, well-tested invocations.
 Make sure that examples work properly!
 .It Em DIAGNOSTICS
-Documents error conditions.
-This is most useful in section 4 manuals.
+Documents error messages.
+In section 4 and 9 manuals, these are usually messages printed by the
+kernel to the console and to the kernel log.
+In section 1, 6, 7, and 8, these are usually messages printed by
+userland programs to the standard error output.
+.Pp
 Historically, this section was used in place of
 .Em EXIT STATUS
 for manuals in sections 1, 6, and 8; however, this practise is
@@ -369,7 +378,9 @@ See
 .Sx \&Bl
 .Fl diag .
 .It Em ERRORS
-Documents error handling in sections 2, 3, and 9.
+Documents
+.Xr errno 2
+settings in sections 2, 3, 4, and 9.
 .Pp
 See
 .Sx \&Er .
@@ -502,7 +513,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
@@ -530,7 +540,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
@@ -741,9 +750,8 @@ See also
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,
-.Sx \&Ox ,
 and
-.Sx \&Ux .
+.Sx \&Ox .
 .Ss \&Bc
 Close a
 .Sx \&Bo
@@ -1107,10 +1115,10 @@ 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
@@ -1130,9 +1138,8 @@ See also
 .Sx \&Dx ,
 .Sx \&Fx ,
 .Sx \&Nx ,
-.Sx \&Ox ,
 and
-.Sx \&Ux .
+.Sx \&Ox .
 .Ss \&Cd
 Kernel configuration declaration.
 This denotes strings accepted by
@@ -1305,70 +1312,70 @@ It should be capitalised.
 .It Ar section
 The manual section.
 This may be one of
-.Ar 1
+.Cm 1
 .Pq utilities ,
-.Ar 2
+.Cm 2
 .Pq system calls ,
-.Ar 3
+.Cm 3
 .Pq libraries ,
-.Ar 3p
+.Cm 3p
 .Pq Perl libraries ,
-.Ar 4
+.Cm 4
 .Pq devices ,
-.Ar 5
+.Cm 5
 .Pq file formats ,
-.Ar 6
+.Cm 6
 .Pq games ,
-.Ar 7
+.Cm 7
 .Pq miscellaneous ,
-.Ar 8
+.Cm 8
 .Pq system utilities ,
-.Ar 9
+.Cm 9
 .Pq kernel functions ,
-.Ar X11
+.Cm X11
 .Pq X Window System ,
-.Ar X11R6
+.Cm X11R6
 .Pq X Window System ,
-.Ar unass
+.Cm unass
 .Pq unassociated ,
-.Ar local
+.Cm local
 .Pq local system ,
-.Ar draft
+.Cm draft
 .Pq draft manual ,
 or
-.Ar paper
+.Cm paper
 .Pq paper .
 It should correspond to the manual's filename suffix and defaults to
-.Dq 1
+.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
-.Ar USD
+.Cm USD
 .Pq users' supplementary documents ,
-.Ar PS1
+.Cm PS1
 .Pq programmers' supplementary documents ,
-.Ar AMD
+.Cm AMD
 .Pq administrators' supplementary documents ,
-.Ar SMM
+.Cm SMM
 .Pq system managers' manuals ,
-.Ar URM
+.Cm URM
 .Pq users' reference manuals ,
-.Ar PRM
+.Cm PRM
 .Pq programmers' reference manuals ,
-.Ar KM
+.Cm KM
 .Pq kernel manuals ,
-.Ar IND
+.Cm IND
 .Pq master index ,
-.Ar MMI
+.Cm MMI
 .Pq master index ,
-.Ar LOCAL
+.Cm LOCAL
 .Pq local manuals ,
-.Ar LOC
+.Cm LOC
 .Pq local manuals ,
 or
-.Ar CON
+.Cm CON
 .Pq contributed manuals .
 .It Ar arch
 This specifies the machine architecture a manual page applies to,
@@ -1430,9 +1437,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 .
@@ -1481,7 +1487,7 @@ See also
 and
 .Sx \&Sy .
 .Ss \&En
-This macro is obsolete and not implemented in
+This macro is obsolete and ignored by
 .Xr mandoc 1 .
 .Ss \&Eo
 An arbitrary enclosure.
@@ -1508,7 +1514,8 @@ See also
 .Sx \&Dv
 for general constants.
 .Ss \&Es
-This macro is obsolete and not implemented.
+This macro is obsolete and ignored by
+.Xr mandoc 1 .
 .Ss \&Ev
 Environmental variables such as those specified in
 .Xr environ 7 .
@@ -1688,7 +1695,7 @@ See also
 and
 .Sx \&Ft .
 .Ss \&Fr
-This macro is obsolete and not implemented in
+This macro is obsolete and ignored by
 .Xr mandoc 1 .
 .Pp
 It was used to show function return values.
@@ -1733,9 +1740,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 .
@@ -2053,9 +2059,8 @@ See also
 .Sx \&Bx ,
 .Sx \&Dx ,
 .Sx \&Fx ,
-.Sx \&Ox ,
 and
-.Sx \&Ux .
+.Sx \&Ox .
 .Ss \&Oc
 Close multi-line
 .Sx \&Oo
@@ -2109,7 +2114,7 @@ See also
 and
 .Sx \&Dt .
 .Ss \&Ot
-This macro is obsolete and not implemented in
+This macro is obsolete and ignored by
 .Xr mandoc 1 .
 .Pp
 Historical
@@ -2132,9 +2137,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
@@ -2354,114 +2358,244 @@ and
 .Sx \&Sx .
 .Ss \&St
 Replace an abbreviation for a standard with the full form.
-The following standards are recognised:
+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-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.1d-99
-.St -p1003.1d-99
-.It \-p1003.1g-2000
-.St -p1003.1g-2000
-.It \-p1003.1i-95
-.St -p1003.1i-95
-.It \-p1003.1j-2000
-.St -p1003.1j-2000
-.It \-p1003.1q-2000
-.St -p1003.1q-2000
-.It \-p1003.2
-.St -p1003.2
-.It \-p1003.2-92
-.St -p1003.2-92
-.It \-p1003.2a-92
-.St -p1003.2a-92
-.It \-p1387.2
-.St -p1387.2
-.It \-p1387.2-95
-.St -p1387.2-95
+.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
+.It \-ansiC-99
+.St -ansiC-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 \-xpg4.2
 .St -xpg4.2
+.br
+This standard was published in 1994 and is also called SUSv1.
+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 \-xpg4.3
 .St -xpg4.3
+.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
-.It \-xsh4.2
-.St -xsh4.2
+.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
+.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
+.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].
+.Pp
+.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
+.br
+This standard is also called SUSv4 and
+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.
 The referenced section or subsection name must be identical to the
@@ -2492,36 +2626,19 @@ 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
-.Ux
-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
@@ -2998,8 +3115,9 @@ Manually switching the font using the
 .Ql \ef
 font escape sequences is never required.
 .Sh COMPATIBILITY
-This section documents compatibility between mandoc and other
-troff implementations, at this time limited to GNU troff
+This section provides an incomplete list of compatibility issues
+between mandoc and other troff implementations, at this time limited
+to GNU troff
 .Pq Qq groff .
 The term
 .Qq historic groff
@@ -3108,7 +3226,7 @@ certain list types.
 can only be called by other macros, but not at the beginning of a line.
 .It
 .Sx \&%C
-is not implemented.
+is not implemented (up to and including groff-1.22.2).
 .It
 Historic groff only allows up to eight or nine arguments per macro input
 line, depending on the exact situation.
@@ -3126,7 +3244,7 @@ in new groff and mandoc.
 .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.
@@ -3143,41 +3261,11 @@ The following features are unimplemented in mandoc:
 .Fl file Ar file .
 .It
 .Sx \&Bd
-.Fl offset Ar center
+.Fl offset Cm center
 and
-.Fl offset Ar right .
+.Fl offset Cm 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.
-.It
-The
-.Sq \ef
-scaling unit is accepted by mandoc, but rendered as the default unit.
-.It
-In quoted literals, groff allows pairwise double-quotes to produce a
-standalone double-quote in formatted output.
-This is not supported by mandoc.
 .El
 .Sh SEE ALSO
 .Xr man 1 ,