I really should run -Tlint on my own manuals before committing them.

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index b6c2b35b90953ff57e6b22c969ec9f8da99ad9ed..304f9d773af7c5ce13a4e0f95fc43b7c357cddac 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.121 2010/06/06 22:25:56 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.123 2010/06/07 11:14:13 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 6 2010 $
+.Dd $Mdocdate: June 7 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -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