From 2f5984e155e589b74309a8eaf5a13860cda36489 Mon Sep 17 00:00:00 2001
From: Ingo Schwarze <schwarze@openbsd.org>
Date: Mon, 20 Oct 2014 17:59:20 +0000
Subject: improve documentation of .Fa, .Va, and .Vt; inspired by a discussion
 with matthew@

---
 mdoc.7 | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/mdoc.7 b/mdoc.7
index 0557dbbe..cdc4c41c 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.238 2014/10/13 12:46:28 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: October 13 2014 $
+.Dd $Mdocdate: October 20 2014 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -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
@@ -2704,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.
@@ -2720,18 +2729,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 .
-- 
cgit v1.2.3