diff options
| -rw-r--r-- | mdoc.7 | 184 |
1 files changed, 149 insertions, 35 deletions
@@ -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 , |