===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.235
retrieving revision 1.239
diff -u -p -r1.235 -r1.239
--- mandoc/mdoc.7	2014/08/14 20:57:19	1.235
+++ mandoc/mdoc.7	2014/10/20 17:59:20	1.239
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.235 2014/08/14 20:57:19 schwarze Exp $
+.\"	$Id: mdoc.7,v 1.239 2014/10/20 17:59:20 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: August 14 2014 $
+.Dd $Mdocdate: October 20 2014 $
 .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
-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
@@ -1245,7 +1245,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.
@@ -1570,7 +1570,7 @@ 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
@@ -2510,10 +2510,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 \-susv1
+.St -susv1
 .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
@@ -2606,8 +2608,10 @@ The second and last Technical Corrigendum.
 .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 SUSv4 and
+This standard is also called
 X/Open Portability Guide version 7.
 .Pp
 .It \-p1003.1-2013
@@ -2700,8 +2704,17 @@ A variable name.
 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.
@@ -2716,18 +2729,21 @@ In the former case, this macro starts a new output lin
 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 .