diff options
| author |   Ingo Schwarze <schwarze@openbsd.org> | 2014-07-13 10:24:40 +0000 |
|---|---|---|
| committer | Ingo Schwarze <schwarze@openbsd.org> | 2014-07-13 10:24:40 +0000 |
| commit | fc6948f15fbb03bcfe694465d2b63e8d8193bff2 (patch) | |
| tree | 67d25a97668eeb7168f6e9a51818e0a0c4788ae3 /mdoc.7 | |
| parent | 76c11ac76bacd43c9f5088017ce45c83f50520b6 (diff) | |
| download | mandoc-fc6948f15fbb03bcfe694465d2b63e8d8193bff2.tar.gz mandoc-fc6948f15fbb03bcfe694465d2b63e8d8193bff2.tar.zst mandoc-fc6948f15fbb03bcfe694465d2b63e8d8193bff2.zip | |
Unconfuse .Fa documentation:
You can use .Fa with just a type, without a name,
but when you give both, which is the usual case,
they need to go into one single .Fa argument.
Observed by bentley@; ok jmc@ bentley@.
Diffstat (limited to 'mdoc.7')
| -rw-r--r-- | mdoc.7 | 30 |
1 files changed, 21 insertions, 9 deletions
@@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.231 2014/07/02 03:48:07 schwarze Exp $ +.\" $Id: mdoc.7,v 1.232 2014/07/13 10:24:40 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: July 2 2014 $ +.Dd $Mdocdate: July 13 2014 $ .Dt MDOC 7 .Os .Sh NAME @@ -1563,19 +1563,31 @@ Function argument. 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 -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 -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 @@ -1585,7 +1597,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 -.Dl \&.Fa foo +.Dl \&.Fa \(dqchar *\(dq size_t .Pp See also .Sx \&Fo . @@ -1688,7 +1700,7 @@ Invocations usually occur in the following context: .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 |