diff options
| author |   Ingo Schwarze <schwarze@openbsd.org> | 2014-10-20 17:59:20 +0000 |
|---|---|---|
| committer | Ingo Schwarze <schwarze@openbsd.org> | 2014-10-20 17:59:20 +0000 |
| commit | 2f5984e155e589b74309a8eaf5a13860cda36489 (patch) | |
| tree | 21c15ebae9a01896dcdf16251702527738e5a557 /mdoc.7 | |
| parent | 6e74e86e44514ebe15ac91e3d2d8aa05b8fdf34b (diff) | |
| download | mandoc-2f5984e155e589b74309a8eaf5a13860cda36489.tar.gz mandoc-2f5984e155e589b74309a8eaf5a13860cda36489.tar.zst mandoc-2f5984e155e589b74309a8eaf5a13860cda36489.zip | |
improve documentation of .Fa, .Va, and .Vt;
inspired by a discussion with matthew@
Diffstat (limited to 'mdoc.7')
| -rw-r--r-- | mdoc.7 | 32 |
1 files changed, 22 insertions, 10 deletions
@@ -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 . |