version 1.178, 2011/02/02 21:40:45 |
version 1.190, 2011/07/15 20:40:32 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
|
|
.Nm |
.Nm |
document follows simple rules: lines beginning with the control |
document follows simple rules: lines beginning with the control |
character |
character |
.Sq \. |
.Sq \&. |
are parsed for macros. |
are parsed for macros. |
Other lines are interpreted within the scope of |
Text lines, those not beginning with the control character, are |
prior macros: |
interpreted within the scope of prior macros: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Sh Macro lines change control state. |
\&.Sh Macro lines change control state. |
Other lines are interpreted within the current state. |
Text lines are interpreted within the current state. |
.Ed |
.Ed |
.Sh LANGUAGE SYNTAX |
.Sh LANGUAGE SYNTAX |
.Nm |
.Nm |
documents may contain only graphable 7-bit ASCII characters, the space |
documents may contain only graphable 7-bit ASCII characters, the space |
character, and, in certain circumstances, the tab character. |
character, and, in certain circumstances, the tab character. |
.Pp |
.Pp |
If the first character of a line is a space, that line is printed |
If the first character of a text line is a space, that line is printed |
with a leading newline. |
with a leading newline. |
.Ss Comments |
.Ss Comments |
Text following a |
Text following a |
.Sq \e\*q , |
.Sq \e\*q , |
whether in a macro or free-form text line, is ignored to the end of |
whether in a macro or text line, is ignored to the end of |
line. |
line. |
A macro line with only a control character and comment escape, |
A macro line with only a control character and comment escape, |
.Sq \&.\e\*q , |
.Sq \&.\e\*q , |
is also ignored. |
is also ignored. |
Macro lines with only a control character and optional whitespace are |
Macro lines with only a control character and optional whitespace are |
stripped from input. |
stripped from input. |
.Ss Reserved Characters |
.Ss Reserved Terms |
Within a macro line, the following characters are reserved: |
Within a macro line, the following terms are reserved: |
.Pp |
.Pp |
.Bl -tag -width Ds -offset indent -compact |
.Bl -tag -width Ds -offset indent -compact |
.It \&. |
.It \&. |
.Pq period |
.Pq period |
|
.It \e. |
|
.Pq escaped period |
.It \&, |
.It \&, |
.Pq comma |
.Pq comma |
.It \&: |
.It \&: |
Line 91 Within a macro line, the following characters are rese |
|
Line 93 Within a macro line, the following characters are rese |
|
.Pq exclamation |
.Pq exclamation |
.It \&| |
.It \&| |
.Pq vertical bar |
.Pq vertical bar |
|
.It \e*(Ba |
|
.Pq reserved-word vertical bar |
.El |
.El |
.Pp |
.Pp |
Use of reserved characters is described in |
For general use in macro lines, these can be escaped with a non-breaking |
.Sx MACRO SYNTAX . |
space |
For general use in macro lines, these characters can either be escaped |
.Pq Sq \e& . |
with a non-breaking space |
In text lines, these may be used as normal punctuation. |
.Pq Sq \e& |
|
or, if applicable, an appropriate escape sequence can be used. |
|
.Ss Special Characters |
.Ss Special Characters |
Special characters may occur in both macro and free-form lines. |
Special characters may occur in both macro and text lines. |
Sequences begin with the escape character |
Sequences begin with the escape character |
.Sq \e |
.Sq \e |
followed by either an open-parenthesis |
followed by either an open-parenthesis |
Line 129 escape followed by an indicator: B (bold), I (italic), |
|
Line 131 escape followed by an indicator: B (bold), I (italic), |
|
.Pp |
.Pp |
A numerical representation 3, 2, or 1 (bold, italic, and Roman, |
A numerical representation 3, 2, or 1 (bold, italic, and Roman, |
respectively) may be used instead. |
respectively) may be used instead. |
A text decoration is valid within |
If a macro opens a font scope after calling |
the current font scope only: if a macro opens a font scope alongside |
.Sq \ef , |
its own scope, such as |
such as with |
.Sx \&Bf |
.Sx \&Bf , |
.Cm \&Sy , |
the |
in-scope invocations of |
|
.Sq \ef |
.Sq \ef |
are only valid within the font scope of the macro. |
mode will be restored upon exiting the |
If |
.Sx \&Bf |
.Sq \ef |
scope. |
is specified outside of any font scope, such as in unenclosed, free-form |
|
text, it will affect the remainder of the document. |
|
.Pp |
.Pp |
Note this form is |
Note this form is |
.Em not |
.Em not |
|
|
.Pq vertical bar . |
.Pq vertical bar . |
.Ss Whitespace |
.Ss Whitespace |
Whitespace consists of the space character. |
Whitespace consists of the space character. |
In free-form lines, whitespace is preserved within a line; unescaped |
In text lines, whitespace is preserved within a line; unescaped |
trailing spaces are stripped from input (unless in a literal context). |
trailing spaces are stripped from input (unless in a literal context). |
Blank free-form lines, which may include whitespace, are only permitted |
Blank text lines, which may include whitespace, are only permitted |
within literal contexts. |
within literal contexts. |
.Pp |
.Pp |
In macro lines, whitespace delimits arguments and is discarded. |
In macro lines, whitespace delimits arguments and is discarded. |
Line 196 Thus, the following produces |
|
Line 195 Thus, the following produces |
|
\&.Op "Fl a" |
\&.Op "Fl a" |
.Ed |
.Ed |
.Pp |
.Pp |
In free-form mode, quotes are regarded as opaque text. |
In text lines, quotes are regarded as opaque text. |
.Ss Dates |
|
There are several macros in |
|
.Nm |
|
that require a date argument. |
|
The canonical form for dates is the American format: |
|
.Pp |
|
.D1 Cm Month Day , Year |
|
.Pp |
|
The |
|
.Cm Day |
|
value is an optionally zero-padded numeral. |
|
The |
|
.Cm Month |
|
value is the full month name. |
|
The |
|
.Cm Year |
|
value is the full four-digit year. |
|
.Pp |
|
Reduced form dates are broken-down canonical form dates: |
|
.Pp |
|
.D1 Cm Month , Year |
|
.D1 Cm Year |
|
.Pp |
|
Some examples of valid dates follow: |
|
.Pp |
|
.D1 "May, 2009" Pq reduced form |
|
.D1 "2009" Pq reduced form |
|
.D1 "May 20, 2009" Pq canonical form |
|
.Ss Scaling Widths |
.Ss Scaling Widths |
Many macros support scaled widths for their arguments, such as |
Many macros support scaled widths for their arguments, such as |
stipulating a two-inch list indentation with the following: |
stipulating a two-inch list indentation with the following: |
|
|
By doing so, front-ends will be able to apply the proper amount of |
By doing so, front-ends will be able to apply the proper amount of |
spacing after the end of sentence (unescaped) period, exclamation mark, |
spacing after the end of sentence (unescaped) period, exclamation mark, |
or question mark followed by zero or more non-sentence closing |
or question mark followed by zero or more non-sentence closing |
delimiters ( |
delimiters |
.Ns Sq \&) , |
.Po |
|
.Sq \&) , |
.Sq \&] , |
.Sq \&] , |
.Sq \&' , |
.Sq \&' , |
.Sq \&" ) . |
.Sq \&" |
|
.Pc . |
.Pp |
.Pp |
The proper spacing is also intelligently preserved if a sentence ends at |
The proper spacing is also intelligently preserved if a sentence ends at |
the boundary of a macro line. |
the boundary of a macro line. |
For example: |
For example: |
.Pp |
.Pp |
.Dl \&Xr mandoc 1 \. |
.Dl \&.Xr mandoc 1 \&. |
.Dl \&Fl T \&Ns \&Cm ascii \. |
.Dl \&.Fl T \&Ns \&Cm ascii \&. |
.Sh MANUAL STRUCTURE |
.Sh MANUAL STRUCTURE |
A well-formed |
A well-formed |
.Nm |
.Nm |
Line 323 sections, although this varies between manual sections |
|
Line 296 sections, although this varies between manual sections |
|
.Pp |
.Pp |
The following is a well-formed skeleton |
The following is a well-formed skeleton |
.Nm |
.Nm |
file: |
file for a utility |
|
.Qq progname : |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Dd $\&Mdocdate$ |
\&.Dd $\&Mdocdate$ |
\&.Dt mdoc 7 |
\&.Dt PROGNAME section |
\&.Os |
\&.Os |
\&.Sh NAME |
\&.Sh NAME |
\&.Nm foo |
\&.Nm progname |
\&.Nd a description goes here |
\&.Nd a description goes here |
\&.\e\*q .Sh LIBRARY |
\&.\e\*q .Sh LIBRARY |
\&.\e\*q For sections 2, 3, & 9 only. |
\&.\e\*q For sections 2, 3, & 9 only. |
\&.\e\*q Not used in OpenBSD. |
\&.\e\*q Not used in OpenBSD. |
\&.Sh SYNOPSIS |
\&.Sh SYNOPSIS |
\&.Nm foo |
\&.Nm progname |
\&.Op Fl options |
\&.Op Fl options |
\&.Ar |
\&.Ar |
\&.Sh DESCRIPTION |
\&.Sh DESCRIPTION |
Line 382 The syntax for this as follows: |
|
Line 356 The syntax for this as follows: |
|
\&.Nd a one line description |
\&.Nd a one line description |
.Ed |
.Ed |
.Pp |
.Pp |
|
Multiple |
|
.Sq \&Nm |
|
names should be separated by commas. |
|
.Pp |
The |
The |
.Sx \&Nm |
.Sx \&Nm |
macro(s) must precede the |
macro(s) must precede the |
|
|
For the first, utilities (sections 1, 6, and 8), this is |
For the first, utilities (sections 1, 6, and 8), this is |
generally structured as follows: |
generally structured as follows: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Nm foo |
\&.Nm bar |
\&.Op Fl v |
\&.Op Fl v |
\&.Op Fl o Ar file |
\&.Op Fl o Ar file |
\&.Op Ar |
\&.Op Ar |
\&.Nm bar |
\&.Nm foo |
\&.Op Fl v |
\&.Op Fl v |
\&.Op Fl o Ar file |
\&.Op Fl o Ar file |
\&.Op Ar |
\&.Op Ar |
.Ed |
.Ed |
.Pp |
.Pp |
|
Commands should be ordered alphabetically. |
|
.Pp |
For the second, function calls (sections 2, 3, 9): |
For the second, function calls (sections 2, 3, 9): |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.In header.h |
\&.In header.h |
Line 429 For the second, function calls (sections 2, 3, 9): |
|
Line 409 For the second, function calls (sections 2, 3, 9): |
|
\&.Fn bar "const char *src" |
\&.Fn bar "const char *src" |
.Ed |
.Ed |
.Pp |
.Pp |
|
Ordering of |
|
.Sx \&In , |
|
.Sx \&Vt , |
|
.Sx \&Fn , |
|
and |
|
.Sx \&Fo |
|
macros should follow C header-file conventions. |
|
.Pp |
And for the third, configurations (section 4): |
And for the third, configurations (section 4): |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Cd \*qit* at isa? port 0x2e\*q |
\&.Cd \*qit* at isa? port 0x2e\*q |
|
|
.Sx \&Ss |
.Sx \&Ss |
macro or the end of an enclosing block, whichever comes first. |
macro or the end of an enclosing block, whichever comes first. |
.It Em DESCRIPTION |
.It Em DESCRIPTION |
This expands upon the brief, one line description in |
This begins with an expansion of the brief, one line description in |
.Em NAME . |
.Em NAME : |
It usually contains a breakdown of the options (if documenting a |
.Bd -literal -offset indent |
|
The |
|
\&.Nm |
|
utility does this, that, and the other. |
|
.Ed |
|
.Pp |
|
It usually follows with a breakdown of the options (if documenting a |
command), such as: |
command), such as: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
The arguments are as follows: |
The arguments are as follows: |
Line 627 column, if applicable, describes closure rules. |
|
Line 621 column, if applicable, describes closure rules. |
|
Multi-line scope closed by an explicit closing macro. |
Multi-line scope closed by an explicit closing macro. |
All macros contains bodies; only |
All macros contains bodies; only |
.Sx \&Bf |
.Sx \&Bf |
contains a head. |
and |
|
.Pq optionally |
|
.Sx \&Bl |
|
contain a head. |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB |
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB |
\(lBbody...\(rB |
\(lBbody...\(rB |
|
|
.El |
.El |
.Ss Block partial-implicit |
.Ss Block partial-implicit |
Like block full-implicit, but with single-line scope closed by |
Like block full-implicit, but with single-line scope closed by |
.Sx Reserved Characters |
.Sx Reserved Terms |
or end of line. |
or end of line. |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB |
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB |
|
|
.Em SYNOPSIS |
.Em SYNOPSIS |
section line, else it is |
section line, else it is |
.Sx In-line . |
.Sx In-line . |
|
.Ss Special block macro |
|
The |
|
.Sx \&Ta |
|
macro can only be used below |
|
.Sx \&It |
|
in |
|
.Sx \&Bl Fl column |
|
lists. |
|
It delimits blocks representing table cells; |
|
these blocks have bodies, but no heads. |
|
.Pp |
|
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent |
|
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
|
.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It |
|
.El |
.Ss In-line |
.Ss In-line |
Closed by |
Closed by |
.Sx Reserved Characters , |
.Sx Reserved Terms , |
end of line, fixed argument lengths, and/or subsequent macros. |
end of line, fixed argument lengths, and/or subsequent macros. |
In-line macros have only text children. |
In-line macros have only text children. |
If a number (or inequality) of arguments is |
If a number (or inequality) of arguments is |
Line 825 then the macro accepts an arbitrary number of argument |
|
Line 837 then the macro accepts an arbitrary number of argument |
|
.It Sx \&Fx Ta Yes Ta Yes Ta n |
.It Sx \&Fx Ta Yes Ta Yes Ta n |
.It Sx \&Hf Ta \&No Ta \&No Ta n |
.It Sx \&Hf Ta \&No Ta \&No Ta n |
.It Sx \&Ic Ta Yes Ta Yes Ta >0 |
.It Sx \&Ic Ta Yes Ta Yes Ta >0 |
.It Sx \&In Ta \&No Ta \&No Ta n |
.It Sx \&In Ta \&No Ta \&No Ta 1 |
.It Sx \&Lb Ta \&No Ta \&No Ta 1 |
.It Sx \&Lb Ta \&No Ta \&No Ta 1 |
.It Sx \&Li Ta Yes Ta Yes Ta >0 |
.It Sx \&Li Ta Yes Ta Yes Ta >0 |
.It Sx \&Lk Ta Yes Ta Yes Ta >0 |
.It Sx \&Lk Ta Yes Ta Yes Ta >0 |
|
|
Publication date of an |
Publication date of an |
.Sx \&Rs |
.Sx \&Rs |
block. |
block. |
This should follow the reduced or canonical form syntax described in |
Recommended formats of arguments are |
.Sx Dates . |
.Ar month day , year |
|
or just |
|
.Ar year . |
.Ss \&%I |
.Ss \&%I |
Publisher or issuer name of an |
Publisher or issuer name of an |
.Sx \&Rs |
.Sx \&Rs |
Line 1061 Its syntax is as follows: |
|
Line 1075 Its syntax is as follows: |
|
.Pp |
.Pp |
Display blocks are used to select a different indentation and |
Display blocks are used to select a different indentation and |
justification than the one used by the surrounding text. |
justification than the one used by the surrounding text. |
They may contain both macro lines and free-form text lines. |
They may contain both macro lines and text lines. |
By default, a display block is preceded by a vertical space. |
By default, a display block is preceded by a vertical space. |
.Pp |
.Pp |
The |
The |
|
|
and |
and |
.Sx \&Sy . |
.Sx \&Sy . |
.Ss \&Bk |
.Ss \&Bk |
Keep the output generated from each macro input line together |
For each macro, keep its output together on the same output line, |
on one single output line. |
until the end of the macro or the end of the input line is reached, |
Line breaks in free-form text lines are unaffected. |
whichever comes first. |
|
Line breaks in text lines are unaffected. |
The syntax is as follows: |
The syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Bk Fl words |
.D1 Pf \. Sx \&Bk Fl words |
Line 1467 This is the mandatory first macro of any |
|
Line 1482 This is the mandatory first macro of any |
|
manual. |
manual. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Dd Op Ar date |
.D1 Pf \. Sx \&Dd Ar month day , year |
.Pp |
.Pp |
The |
The |
.Ar date |
.Ar month |
may be either |
is the full English month name, the |
.Ar $\&Mdocdate$ , |
.Ar day |
which signifies the current manual revision date dictated by |
is an optionally zero-padded numeral, and the |
|
.Ar year |
|
is the full four-digit year. |
|
.Pp |
|
Other arguments are not portable; the |
|
.Xr mandoc 1 |
|
utility handles them as follows: |
|
.Bl -dash -offset 3n -compact |
|
.It |
|
To have the date automatically filled in by the |
|
.Ox |
|
version of |
.Xr cvs 1 , |
.Xr cvs 1 , |
or instead a valid canonical date as specified by |
the special string |
.Sx Dates . |
.Dq $\&Mdocdate$ |
If a date does not conform or is empty, the current date is used. |
can be given as an argument. |
|
.It |
|
A few alternative date formats are accepted as well |
|
and converted to the standard form. |
|
.It |
|
If a date string cannot be parsed, it is used verbatim. |
|
.It |
|
If no date string is given, the current date is used. |
|
.El |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Dd $\&Mdocdate$ |
.Dl \&.Dd $\&Mdocdate$ |
|
|
and |
and |
.Sx \&Os . |
.Sx \&Os . |
.Ss \&Dv |
.Ss \&Dv |
Defined variables such as preprocessor constants. |
Defined variables such as preprocessor constants, constant symbols, |
|
enumeration values, and so on. |
.Pp |
.Pp |
Examples: |
Examples: |
|
.Dl \&.Dv NULL |
.Dl \&.Dv BUFSIZ |
.Dl \&.Dv BUFSIZ |
.Dl \&.Dv STDOUT_FILENO |
.Dl \&.Dv STDOUT_FILENO |
.Pp |
.Pp |
See also |
See also |
.Sx \&Er . |
.Sx \&Er |
|
and |
|
.Sx \&Ev |
|
for special-purpose constants and |
|
.Sx \&Va |
|
for variable symbols. |
.Ss \&Dx |
.Ss \&Dx |
Format the DragonFly BSD version provided as an argument, or a default |
Format the DragonFly BSD version provided as an argument, or a default |
value if no argument is provided. |
value if no argument is provided. |
Line 1755 argument is used as the enclosure head, for example, s |
|
Line 1796 argument is used as the enclosure head, for example, s |
|
will emulate |
will emulate |
.Sx \&Do . |
.Sx \&Do . |
.Ss \&Er |
.Ss \&Er |
Display error constants. |
Error constants for definitions of the |
|
.Va errno |
|
libc global variable. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Er EPERM |
.Dl \&.Er EPERM |
.Dl \&.Er ENOENT |
.Dl \&.Er ENOENT |
.Pp |
.Pp |
See also |
See also |
.Sx \&Dv . |
.Sx \&Dv |
|
for general constants. |
.Ss \&Es |
.Ss \&Es |
This macro is obsolete and not implemented. |
This macro is obsolete and not implemented. |
.Ss \&Ev |
.Ss \&Ev |
Line 1772 Environmental variables such as those specified in |
|
Line 1816 Environmental variables such as those specified in |
|
Examples: |
Examples: |
.Dl \&.Ev DISPLAY |
.Dl \&.Ev DISPLAY |
.Dl \&.Ev PATH |
.Dl \&.Ev PATH |
|
.Pp |
|
See also |
|
.Sx \&Dv |
|
for general constants. |
.Ss \&Ex |
.Ss \&Ex |
Insert a standard sentence regarding exit values. |
Insert a standard sentence regarding exit values. |
Its syntax is as follows: |
Its syntax is as follows: |
Line 1853 A function name. |
|
Line 1901 A function name. |
|
Its syntax is as follows: |
Its syntax is as follows: |
.Bd -ragged -offset indent |
.Bd -ragged -offset indent |
.Pf \. Ns Sx \&Fn |
.Pf \. Ns Sx \&Fn |
.Op Cm functype |
.Op Ar functype |
.Cm funcname |
.Ar funcname |
.Op Oo Cm argtype Oc Cm argname |
.Op Oo Ar argtype Oc Ar argname |
.Ed |
.Ed |
.Pp |
.Pp |
Function arguments are surrounded in parenthesis and |
Function arguments are surrounded in parenthesis and |
Line 1863 are delimited by commas. |
|
Line 1911 are delimited by commas. |
|
If no arguments are specified, blank parenthesis are output. |
If no arguments are specified, blank parenthesis are output. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Fn "int funcname" "int arg0" "int arg1" |
.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q |
.Dl \&.Fn funcname "int arg0" |
.Dl \&.Fn funcname \*qint arg0\*q |
.Dl \&.Fn funcname arg0 |
.Dl \&.Fn funcname arg0 |
.Bd -literal -offset indent -compact |
.Bd -literal -offset indent -compact |
\&.Ft functype |
\&.Ft functype |
Line 1884 This is a multi-line version of |
|
Line 1932 This is a multi-line version of |
|
.Sx \&Fn . |
.Sx \&Fn . |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Fo Cm funcname |
.D1 Pf \. Sx \&Fo Ar funcname |
.Pp |
.Pp |
Invocations usually occur in the following context: |
Invocations usually occur in the following context: |
.Bd -ragged -offset indent |
.Bd -ragged -offset indent |
.Pf \. Sx \&Ft Cm functype |
.Pf \. Sx \&Ft Ar functype |
.br |
.br |
.Pf \. Sx \&Fo Cm funcname |
.Pf \. Sx \&Fo Ar funcname |
.br |
.br |
.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname |
.Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname |
.br |
.br |
\.\.\. |
\&.\.\. |
.br |
.br |
.Pf \. Sx \&Fc |
.Pf \. Sx \&Fc |
.Ed |
.Ed |
|
|
.Sx \&Fc , |
.Sx \&Fc , |
and |
and |
.Sx \&Ft . |
.Sx \&Ft . |
|
.Ss \&Fr |
|
This macro is obsolete and not implemented. |
.Ss \&Ft |
.Ss \&Ft |
A function type. |
A function type. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Ft Cm functype |
.D1 Pf \. Sx \&Ft Ar functype |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Ft int |
.Dl \&.Ft int |
|
|
.Fl diag |
.Fl diag |
have the following syntax: |
have the following syntax: |
.Pp |
.Pp |
.D1 Pf \. Sx \&It Cm args |
.D1 Pf \. Sx \&It Ar args |
.Pp |
.Pp |
Lists of type |
Lists of type |
.Fl bullet , |
.Fl bullet , |
|
|
list is the most complicated. |
list is the most complicated. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&It Op Cm args |
.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ... |
|
.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ... |
.Pp |
.Pp |
The |
The arguments consist of one or more lines of text and macros |
.Cm args |
representing a complete table line. |
are phrases, a mix of macros and text corresponding to a line column, |
Cells within the line are delimited by tabs or by the special |
delimited by tabs or the special |
.Sx \&Ta |
.Sq \&Ta |
block macro. |
pseudo-macro. |
The tab cell delimiter may only be used within the |
Lines subsequent the |
|
.Sx \&It |
.Sx \&It |
are interpreted within the scope of the last phrase. |
line itself; on following lines, only the |
Calling the pseudo-macro |
.Sx \&Ta |
.Sq \&Ta |
macro can be used to delimit cells, and |
will open a new phrase scope (this must occur on a macro line to be |
.Sx \&Ta |
interpreted as a macro). |
is only recognized as a macro when called by other macros, |
Note that the tab phrase delimiter may only be used within the |
not as the first macro on a line. |
|
.Pp |
|
Note that quoted strings may span tab-delimited cells on an |
.Sx \&It |
.Sx \&It |
line itself. |
line. |
Subsequent this, only the |
For example, |
.Sq \&Ta |
|
pseudo-macro may be used to delimit phrases. |
|
Furthermore, note that quoted sections propagate over tab-delimited |
|
phrases on an |
|
.Sx \&It , |
|
for example, |
|
.Pp |
.Pp |
.Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&; |
.Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&; |
.Pp |
.Pp |
|
|
Specify a library. |
Specify a library. |
The syntax is as follows: |
The syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Lb Cm library |
.D1 Pf \. Sx \&Lb Ar library |
.Pp |
.Pp |
The |
The |
.Cm library |
.Ar library |
parameter may be a system library, such as |
parameter may be a system library, such as |
.Cm libz |
.Ar libz |
or |
or |
.Cm libpam , |
.Ar libpam , |
in which case a small library description is printed next to the linker |
in which case a small library description is printed next to the linker |
invocation; or a custom library, in which case the library name is |
invocation; or a custom library, in which case the library name is |
printed in quotes. |
printed in quotes. |
|
|
Format a hyperlink. |
Format a hyperlink. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Lk Cm uri Op Cm name |
.D1 Pf \. Sx \&Lk Ar uri Op Ar name |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q |
.Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q |
|
|
Display a mathematical symbol. |
Display a mathematical symbol. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Ms Cm symbol |
.D1 Pf \. Sx \&Ms Ar symbol |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Ms sigma |
.Dl \&.Ms sigma |
|
|
hyperlink. |
hyperlink. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Mt Cm address |
.D1 Pf \. Sx \&Mt Ar address |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Mt discuss@manpages.bsd.lv |
.Dl \&.Mt discuss@manpages.bsd.lv |
|
|
file. |
file. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Os Op Cm system Op Cm version |
.D1 Pf \. Sx \&Os Op Ar system Op Ar version |
.Pp |
.Pp |
The optional |
The optional |
.Cm system |
.Ar system |
parameter specifies the relevant operating system or environment. |
parameter specifies the relevant operating system or environment. |
Left unspecified, it defaults to the local operating system version. |
Left unspecified, it defaults to the local operating system version. |
This is the suggested form. |
This is the suggested form. |
Line 2326 Removes the space |
|
Line 2372 Removes the space |
|
between its arguments. |
between its arguments. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. \&Pf Cm prefix suffix |
.D1 Pf \. \&Pf Ar prefix suffix |
.Pp |
.Pp |
The |
The |
.Cm suffix |
.Ar suffix |
argument may be a macro. |
argument may be a macro. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix |
.Dl \&.Pf \e. \&Sx \&Pf \&Ar prefix suffix |
.Ss \&Po |
.Ss \&Po |
Multi-line version of |
Multi-line version of |
.Sx \&Pq . |
.Sx \&Pq . |
Line 2454 Its syntax is as follows: |
|
Line 2500 Its syntax is as follows: |
|
.D1 Pf \. Sx \&Sm Cm on | off |
.D1 Pf \. Sx \&Sm Cm on | off |
.Pp |
.Pp |
By default, spacing is |
By default, spacing is |
.Cm on . |
.Ar on . |
When switched |
When switched |
.Cm off , |
.Ar off , |
no white space is inserted between macro arguments and between the |
no white space is inserted between macro arguments and between the |
output generated from adjacent macros, but free-form text lines |
output generated from adjacent macros, but text lines |
still get normal spacing between words and sentences. |
still get normal spacing between words and sentences. |
.Ss \&So |
.Ss \&So |
Multi-line version of |
Multi-line version of |
|
|
.Sx \&Li , |
.Sx \&Li , |
and |
and |
.Sx \&Em . |
.Sx \&Em . |
|
.Ss \&Ta |
|
Table cell separator in |
|
.Sx \&Bl Fl column |
|
lists; can only be used below |
|
.Sx \&It . |
.Ss \&Tn |
.Ss \&Tn |
Format a tradename. |
Format a tradename. |
.Pp |
.Pp |
Line 2681 Link to another manual |
|
Line 2732 Link to another manual |
|
.Pq Qq cross-reference . |
.Pq Qq cross-reference . |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Xr Cm name section |
.D1 Pf \. Sx \&Xr Ar name section |
.Pp |
.Pp |
The |
The |
.Cm name |
.Ar name |
and |
and |
.Cm section |
.Ar section |
are the name and section of the linked manual. |
are the name and section of the linked manual. |
If |
If |
.Cm section |
.Ar section |
is followed by non-punctuation, an |
is followed by non-punctuation, an |
.Sx \&Ns |
.Sx \&Ns |
is inserted into the token stream. |
is inserted into the token stream. |
Line 2714 This macro should not be used; it is implemented for c |
|
Line 2765 This macro should not be used; it is implemented for c |
|
historical manuals. |
historical manuals. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&sp Op Cm height |
.D1 Pf \. Sx \&sp Op Ar height |
.Pp |
.Pp |
The |
The |
.Cm height |
.Ar height |
argument must be formatted as described in |
argument must be formatted as described in |
.Sx Scaling Widths . |
.Sx Scaling Widths . |
If unspecified, |
If unspecified, |
Line 2759 Newer groff and mandoc print |
|
Line 2810 Newer groff and mandoc print |
|
.Qq AT&T UNIX |
.Qq AT&T UNIX |
and the arguments. |
and the arguments. |
.It |
.It |
.Sx \&Bd Fl column |
.Sx \&Bl Fl column |
does not recognize trailing punctuation characters when they immediately |
does not recognize trailing punctuation characters when they immediately |
precede tabulator characters, but treats them as normal text and |
precede tabulator characters, but treats them as normal text and |
outputs a space before them. |
outputs a space before them. |
Line 2769 does not start a new line. |
|
Line 2820 does not start a new line. |
|
\*[hist] |
\*[hist] |
.It |
.It |
.Sx \&Dd |
.Sx \&Dd |
without an argument prints |
with non-standard arguments behaves very strangely. |
.Dq Epoch . |
When there are three arguments, they are printed verbatim. |
In mandoc, it resolves to the current date. |
Any other number of arguments is replaced by the current date, |
|
but without any arguments the string |
|
.Dq Epoch |
|
is printed. |
.It |
.It |
.Sx \&Fl |
.Sx \&Fl |
does not print a dash for an empty argument. |
does not print a dash for an empty argument. |
Line 2905 This is not supported by mandoc. |
|
Line 2959 This is not supported by mandoc. |
|
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr man 1 , |
.Xr man 1 , |
.Xr mandoc 1 , |
.Xr mandoc 1 , |
|
.Xr eqn 7 , |
.Xr man 7 , |
.Xr man 7 , |
.Xr mandoc_char 7 |
.Xr mandoc_char 7 |
.Xr roff 7 , |
.Xr roff 7 , |