summaryrefslogtreecommitdiffstats
path: root/mdoc.7
diff options
context:
space:
mode:
Diffstat (limited to 'mdoc.7')
-rw-r--r--mdoc.791
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