summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--mdoc.7184
1 files changed, 149 insertions, 35 deletions
diff --git a/mdoc.7 b/mdoc.7
index 441e871a..452342a8 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -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 ,