-.\" $Id: mdoc.7,v 1.114 2010/06/03 14:29:52 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 3 2010 $
+.Dd $Mdocdate: June 6 2010 $
.Dt MDOC 7
.Os
.Sh NAME
.Pp
An
.Nm
-document follows simple rules: lines beginning with the control
+document follows simple rules: lines beginning with the control
character
.Sq \.
are parsed for macros. Other lines are interpreted within the scope of
A numerical representation 3, 2, or 1 (bold, italic, and Roman,
respectively) may be used instead.
A text decoration is valid within
-the current font scope only: if a macro opens a font scope alongside
+the current font scope only: if a macro opens a font scope alongside
its own scope, such as
.Sx \&Bf
.Cm \&Sy ,
and
.Sx \&Dl .
.Ss \&Db
+Start a debugging context.
+This macro is parsed, but generally ignored.
+Its syntax is as follows:
+.Pp
+.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
.Ss \&Ef
.Ss \&Ek
.Ss \&El
+Ends a list context started by
+.Sx \&Bl .
+.Pp
+See also
+.Sx \&Bl
+and
+.Sx \&It .
.Ss \&Em
Denotes text that should be emphasised.
Note that this is a presentation term and should not be used for
.Sx \&Nm
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.
+Furthermore, if the following macro is another
+.Sx \&Fa ,
+the last argument will also have a trailing comma.
+.Pp
+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.
+This usage has been deprecated in favour of
+.Sx \&In .
+Do not use this macro.
+.Pp
+See also
+.Sx \&In .
.Ss \&Fl
Command-line flag.
Used when listing arguments to command-line utilities.
See also
.Sx \&Cm .
.Ss \&Fn
+A function name.
+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.
+In all cases, the function arguments are surrounded in parenthesis and
+are delimited by commas.
+If no arguments are specified, blank parenthesis are output.
+.Pp
+Examples:
+.D1 \&.Fn "int funcname" "int arg0" "int arg1"
+.D1 \&.Fn funcname "int arg0"
+.D1 \&.Fn funcname arg0
+.Bd -literal -offset indent -compact
+\&.Ft functype
+\&.Fn funcname
+.Ed
+.Pp
+See also
+.Sx \&Fa ,
+.Sx \&Fo ,
+.Sx \&Fc ,
+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.
.Ss \&Hf
.Ss \&Ic
.Ss \&In
+An
+.Qq include
+file.
+In the
+.Em SYNOPSIS
+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.
+.Pp
+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"
.Ss \&Lp
.Ss \&Ms
.Ss \&Mt
+Format a
+.Qq mailto:
+hyperlink.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Mt Cm address
+.Pp
+Examples:
+.D1 \&.Mt discuss@manpages.bsd.lv
.Ss \&Nd
.Ss \&Nm
.Ss \&No
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
+.Em SYNOPSIS
+section.
+.It
+Historic groff formats the
+.Sx \&In
+badly: trailing arguments are trashed and
+.Em SYNOPSIS
+is not specially treated.
+.It
+groff does not accept the
+.Sq \&Ta
+pseudo-macro as a line macro.
+mandoc does.
+.It
The comment syntax
.Sq \e."
is no longer accepted.
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