-.\" $Id: mdoc.7,v 1.119 2010/06/04 22:16:27 kristaps Exp $
+.\" $Id: mdoc.7,v 1.121 2010/06/06 22:25:56 kristaps Exp $
.\"
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" 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 4 2010 $
+.Dd $Mdocdate: June 6 2010 $
.Dt MDOC 7
.Os
.Sh NAME
.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
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
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
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.
.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.
.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.
.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 ,
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.
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
.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 ,
.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
.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
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
.Sx \&It ,
for example,
.Pp
-.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;
+.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
.Pp
will preserve the semicolon whitespace except for the last.
.Pp
.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
.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"
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
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
.Sx \&%Q ,
.Sx \&%R ,
.Sx \&%T ,
+.Sx \&%U ,
and
.Sx \&%V
child macros (at least one must be specified).
.Pp
Examples:
.D1 \&.Vt unsigned char
-.D1 \&.Vt extern const char * const sys_signame[] ;
+.D1 \&.Vt extern const char * const sys_signame[] \&;
.Pp
See also
.Sx \&Ft
.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
.Pp
Examples:
.D1 \&.Xr mandoc 1
-.D1 \&.Xr mandoc 1 ;
+.D1 \&.Xr mandoc 1 \&;
.D1 \&.Xr mandoc 1 \&Ns s behaviour
.Ss \&br
.Ss \&sp
.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
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 ,
git.ckatri.com / mandoc.git / blobdiff