Shortened "its calling syntax" -> "its syntax".

Better documentation for `Fa' and some others.

Added `Ft', `Fo', and some COMPATIBILITY notes.

1 files changed, 151 insertions, 37 deletions

diff --git a/mdoc.7 b/mdoc.7
index 439383c3..0e3e533e 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.119 2010/06/04 22:16:27 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.120 2010/06/06 10:49:56 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,7 +14,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: June 4 2010 $
+.Dd $Mdocdate: June 6 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -1334,9 +1334,9 @@ and
 .Ss \&Db
 Start a debugging context.
 This macro is parsed, but generally ignored.
-Its calling syntax is as follows:
+Its syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&Db Cm on | off
+.D1 Pf \. Sx \&Db Cm on | off
 .Ss \&Dc
 Closes a
 .Sx \&Do
@@ -1346,9 +1346,9 @@ Document date.
 This is the mandatory first macro of any
 .Nm
 manual.
-Its calling syntax is as follows:
+Its syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&Dd Cm date
+.D1 Pf \. Sx \&Dd Cm date
 .Pp
 The
 .Cm date
@@ -1407,9 +1407,17 @@ Document title.
 This is the mandatory second macro of any
 .Nm
 file.
-Its calling syntax is as follows:
-.Pp
-.D1 \. Ns Sx \&Dt Op Cm title Op Cm section Op Cm volume | arch
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Dt
+.Oo
+.Cm title
+.Oo
+.Cm section
+.Op Cm volume | arch
+.Oc
+.Oc
+.Ed
 .Pp
 Its arguments are as follows:
 .Bl -tag -width Ds -offset Ds
@@ -1611,12 +1619,21 @@ is not provided, the document's name as stipulated in
 is provided.
 .Ss \&Fa
 Function argument.
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Fa
+.Op Cm argtype
+.Cm argname
+.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.
 Most often, the
 .Sx \&Fa
 macro is used in the
 .Em SYNOPSIS
+within
+.Sx \&Fo
 section when documenting multi-line function prototypes.
 If invoked with multiple arguments, the arguments are separated by a
 comma.
@@ -1628,6 +1645,9 @@ Examples:
 .D1 \&.Fa \(dqconst char *p\(dq
 .D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
 .D1 \&.Fa foo
+.Pp
+See also
+.Sx \&Fo .
 .Ss \&Fc
 .Ss \&Fd
 Historically used to document include files.
@@ -1657,13 +1677,14 @@ See also
 .Sx \&Cm .
 .Ss \&Fn
 A function name.
-Its calling syntax is as follows:
+Its syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Ns Sx \&Fn
 .Op Cm functype
 .Cm funcname
 .Op Oo Cm argtype Oc Cm argname
 .Ed
+.Pp
 If invoked in the
 .Em SYNOPSIS
 section, vertical space is asserted before and after the macro.
@@ -1673,9 +1694,12 @@ If no arguments are specified, blank parenthesis are output.
 .Pp
 Examples:
 .D1 \&.Fn "int funcname" "int arg0" "int arg1"
-.D1 \&.Fn funcname
 .D1 \&.Fn funcname "int arg0"
 .D1 \&.Fn funcname arg0
+.Bd -literal -offset indent -compact
+\&.Ft functype
+\&.Fn funcname
+.Ed
 .Pp
 See also
 .Sx \&Fa ,
@@ -1684,8 +1708,74 @@ See also
 and
 .Sx \&Ft .
 .Ss \&Fo
+Begin a function block.
+This is a multi-line version of
+.Sx \&Fn .
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Fo Cm funcname
+.Pp
+Invocations usually occur in the following context:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Ft Cm functype
+.br
+.Pf \. Sx \&Fo Cm funcname
+.br
+.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname
+.br
+\.\.\.
+.br
+.Pf \. Sx \&Fc
+.Ed
+.Pp
+In the
+.Em SYNOPSIS
+section, a
+.Sx \&Fo
+block is surrounded by vertical space unless
+.Sx \&Ft
+is the prior macro, in which case it is preceded by only a newline.
+.Pp
+A
+.Sx \&Fo
+scope is closed by
+.Pp
+See also
+.Sx \&Fa ,
+.Sx \&Fc ,
+and
+.Sx \&Fn .
+.Sx \&Fc .
 .Ss \&Fr
 .Ss \&Ft
+A function type.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Ft Cm functype
+.Pp
+If invoked before a
+.Sx \&Fo
+or
+.Sx \&Fn
+in the
+.Em SYNOPSIS
+section, a line-break will follow.
+Furthermore, if invoked in the
+.Em SYNOPSIS
+section, it will assert vertical space prior to its arguments.
+.Pp
+Examples:
+.D1 \&.Ft int
+.Bd -literal -offset indent -compact
+\&.Ft functype
+\&.Fn funcname
+.Ed
+.Pp
+See also
+.Sx \&Fo ,
+.Sx \&Fc ,
+and
+.Sx \&Fn .
 .Ss \&Fx
 Format the FreeBSD version provided as an argument, or a default value
 if no argument is provided.
@@ -1720,7 +1810,8 @@ In all other invocations, only angled braces will enclose the argument.
 Examples
 .D1 \&.In sys/types
 .Ss \&It
-A list item.  The syntax of this macro depends on the list type.
+A list item.
+The syntax of this macro depends on the list type.
 .Pp
 Lists
 of type
@@ -1729,9 +1820,9 @@ of type
 .Fl inset ,
 and
 .Fl diag
-have the following calling syntax:
+have the following syntax:
 .Pp
-.D1 \. Ns Sx \&It Cm args
+.D1 Pf \. Sx \&It Cm args
 .Pp
 Lists of type
 .Fl bullet ,
@@ -1740,9 +1831,9 @@ Lists of type
 .Fl hyphen
 and
 .Fl item
-have the following calling syntax:
+have the following syntax:
 .Pp
-.D1 \. Ns Sx \&It
+.D1 Pf \. Sx \&It
 .Pp
 with subsequent lines interpreted within the scope of the
 .Sx \&It
@@ -1753,11 +1844,11 @@ or another
 .Pp
 The
 .Fl tag
-list has syntax
+list has the following syntax:
 .Pp
-.D1 \. Ns Sx \&It Op Cm args
+.D1 Pf \. Sx \&It Op Cm args
 .Pp
-with subsequent lines interpreted as with
+Subsequent lines are interpreted as with
 .Fl bullet
 and family.
 The line arguments correspond to the list's left-hand side; body
@@ -1766,11 +1857,11 @@ arguments correspond to the list's contents.
 The
 .Fl column
 list is the most complicated.
-Its syntax is
+Its syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&It Op Cm args
+.D1 Pf \. Sx \&It Op Cm args
 .Pp
-where
+The
 .Cm args
 are phrases, a mix of macros and text corresponding to a line column,
 delimited by tabs or the special
@@ -1802,9 +1893,9 @@ See also
 .Sx \&Bl .
 .Ss \&Lb
 Specify a library.
-The calling syntax is as follows:
+The syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&Lb Cm library
+.D1 Pf \. Sx \&Lb Cm library
 .Pp
 The
 .Cm library
@@ -1826,9 +1917,9 @@ Examples:
 .Ss \&Li
 .Ss \&Lk
 Format a hyperlink.
-The calling syntax is as follows:
+Its syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&Lk Cm uri Op Cm name
+.D1 Pf \. Sx \&Lk Cm uri Op Cm name
 .Pp
 Examples:
 .D1 \&.Lk http://bsd.lv "The BSD.lv Project"
@@ -1842,9 +1933,9 @@ See also
 Format a
 .Qq mailto:
 hyperlink.
-The calling syntax is as follows:
+Its syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&Mt Cm address
+.D1 Pf \. Sx \&Mt Cm address
 .Pp
 Examples:
 .D1 \&.Mt discuss@manpages.bsd.lv
@@ -1877,9 +1968,10 @@ Document operating system version.
 This is the mandatory third macro of
 any
 .Nm
-file.  Its calling syntax is as follows:
+file.
+Its syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&Os Op Cm system
+.D1 Pf \. Sx \&Os Op Cm system
 .Pp
 The optional
 .Cm system
@@ -1951,6 +2043,7 @@ The block macro may only contain
 .Sx \&%Q ,
 .Sx \&%R ,
 .Sx \&%T ,
+.Sx \&%U ,
 and
 .Sx \&%V
 child macros (at least one must be specified).
@@ -2036,9 +2129,9 @@ since this limit has been lifted, the macro has been deprecated.
 .Ss \&Xr
 Link to another manual
 .Pq Qq cross-reference .
-Its calling syntax is
+Its syntax is as follows:
 .Pp
-.D1 \. Ns Sx \&Xr Cm name section
+.D1 Pf \. Sx \&Xr Cm name section
 .Pp
 The
 .Cm name
@@ -2075,6 +2168,32 @@ Heirloom troff, the other significant troff implementation accepting
 .Pp
 .Bl -dash -compact
 .It
+groff behaves inconsistently when encountering
+.Pf non- Sx \&Fa
+children of
+.Sx \&Fo
+regarding spacing between arguments.
+In mandoc, this is not the case: each argument is consistently followed
+by a single space and the trailing
+.Sq \&)
+suppresses prior spacing.
+.It
+groff behaves inconsistently when encountering
+.Sx \&Ft
+and
+.Sx \&Fn
+in the
+.Em SYNOPSIS :
+at times newline(s) are suppressed dependong on whether a prior
+.Sx \&Fn
+has been invoked.
+In mandoc, this is not the case.
+See
+.Sx \&Ft
+and
+.Sx \&Fn
+for the normalised behaviour.
+.It
 Historic groff does not break before an
 .Sx \&Fn
 when not invoked as the line macro in the
@@ -2164,11 +2283,6 @@ delimiter to render.
 This is not supported in mandoc.
 .It
 In groff, the
-.Sx \&Fo
-macro only produces the first parameter.
-This is not the case in mandoc.
-.It
-In groff, the
 .Sx \&Cd ,
 .Sx \&Er ,
 .Sx \&Ex ,