Normalise SYNOPSIS behaviour after I gave up on following groff's

inconsistent behaviour.  In short:

       Some macros are displayed differently in the SYNOPSIS
       section, particularly Nm, Cd, Fd, Fn, Fo, In, Vt, and Ft.
       All of these macros are output on their own line.  If two
       such dissimilar macros are pair-wise invoked (except for Ft
       before Fo or Fn), they are separated by a vertical space,
       unless in the case of Fo, Fn, and Ft, which are always
       separated by vertical space.

Behaviour ok Jason McIntyre, ingo@.  Fallout will be treated
case-by-case.

I had to clear out some regressions that were testing against groff's
stranger behaviours: these will now break, as we don't care about such
invocations.

Also removed the newline for `Cd' invocation in a non-SYNOPSIS context.

1 files changed, 46 insertions, 45 deletions

diff --git a/mdoc.7 b/mdoc.7
index 9ac577d5..51a12df0 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -333,8 +333,11 @@ must be the NAME section, consisting of at least one
 followed by
 .Sx \&Nd .
 .Pp
-Following that, convention dictates specifying at least the SYNOPSIS and
-DESCRIPTION sections, although this varies between manual sections.
+Following that, convention dictates specifying at least the
+.Em SYNOPSIS
+and
+.Em DESCRIPTION
+sections, although this varies between manual sections.
 .Pp
 The following is a well-formed skeleton
 .Nm
@@ -450,13 +453,31 @@ And for the third, configurations (section 4):
 Manuals not in these sections generally don't need a
 .Em SYNOPSIS .
 .Pp
-See
-.Sx \&Op ,
+Some macros are displayed differently in the
+.Em SYNOPSIS
+section, particularly
+.Sx \&Nm ,
 .Sx \&Cd ,
+.Sx \&Fd ,
 .Sx \&Fn ,
-.Sx \&Ft ,
+.Sx \&Fo ,
+.Sx \&In ,
+.Sx \&Vt ,
 and
-.Sx \&Vt .
+.Sx \&Ft .
+All of these macros are output on their own line.  If two such
+dissimilar macros are pair-wise invoked (except for
+.Sx \&Ft
+before
+.Sx \&Fo
+or
+.Sx \&Fn ) , 
+they are separated by a vertical space, unless in the case of
+.Sx \&Fo ,
+.Sx \&Fn ,
+and
+.Sx \&Ft ,
+which are always separated by vertical space.
 .It Em DESCRIPTION
 This expands upon the brief, one-line description in
 .Em NAME .
@@ -1656,6 +1677,8 @@ This usage has been deprecated in favour of
 Do not use this macro.
 .Pp
 See also
+.Sx MANUAL STRUCTURE
+and
 .Sx \&In .
 .Ss \&Fl
 Command-line flag.
@@ -1685,10 +1708,7 @@ Its syntax is as follows:
 .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.
-In all cases, the function arguments are surrounded in parenthesis and
+Function arguments are surrounded in parenthesis and
 are delimited by commas.
 If no arguments are specified, blank parenthesis are output.
 .Pp
@@ -1702,9 +1722,7 @@ Examples:
 .Ed
 .Pp
 See also
-.Sx \&Fa ,
-.Sx \&Fo ,
-.Sx \&Fc ,
+.Sx MANUAL STRUCTURE
 and
 .Sx \&Ft .
 .Ss \&Fo
@@ -1728,42 +1746,21 @@ Invocations usually occur in the following context:
 .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 MANUAL STRUCTURE ,
 .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
@@ -1772,10 +1769,10 @@ Examples:
 .Ed
 .Pp
 See also
-.Sx \&Fo ,
-.Sx \&Fc ,
+.Sx MANUAL STRUCTURE ,
+.Sx \&Fn ,
 and
-.Sx \&Fn .
+.Sx \&Fo .
 .Ss \&Fx
 Format the FreeBSD version provided as an argument, or a default value
 if no argument is provided.
@@ -1804,11 +1801,13 @@ In the
 section (only if invoked as the line macro), the first argument is
 preceded by
 .Qq #include ,
-the arguments is enclosed in angled braces, and a newline is asserted.
-In all other invocations, only angled braces will enclose the argument.
+the arguments is enclosed in angled braces.
 .Pp
-Examples
+Examples:
 .D1 \&.In sys/types
+.Pp
+See also
+.Sx MANUAL STRUCTURE .
 .Ss \&It
 A list item.
 The syntax of this macro depends on the list type.
@@ -2098,12 +2097,14 @@ and
 .Ss \&Va
 .Ss \&Vt
 A variable type.
-This is also used for indicating global variables in the SYNOPSIS
+This is also used for indicating global variables in the
+.Em SYNOPSIS
 section, in which case a variable name is also specified.
 Note that it accepts
 .Sx Block partial-implicit
-syntax when invoked as the first macro in the SYNOPSIS section, else it
-accepts ordinary
+syntax when invoked as the first macro in the 
+.Em SYNOPSIS
+section, else it accepts ordinary
 .Sx In-line
 syntax.
 .Pp
@@ -2116,7 +2117,7 @@ Examples:
 .D1 \&.Vt extern const char * const sys_signame[] \&;
 .Pp
 See also
-.Sx \&Ft
+.Sx MANUAL STRUCTURE
 and
 .Sx \&Va .
 .Ss \&Xc