version 1.183, 2011/04/01 19:47:33 |
version 1.187, 2011/05/21 15:55:42 |
|
|
.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 , |
Line 97 Within a macro line, the following terms are reserved: |
|
Line 97 Within a macro line, the following terms are reserved: |
|
.Pq reserved-word vertical bar |
.Pq reserved-word vertical bar |
.El |
.El |
.Pp |
.Pp |
Use of reserved terms is described in |
|
.Sx MACRO SYNTAX . |
|
For general use in macro lines, these can be escaped with a non-breaking |
For general use in macro lines, these can be escaped with a non-breaking |
space |
space |
.Pq Sq \e& . |
.Pq Sq \e& . |
|
In text lines, these may be used as normal punctuation. |
.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 132 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 199 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 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: |
Line 270 The proper spacing is also intelligently preserved if |
|
Line 266 The proper spacing is also intelligently preserved if |
|
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 359 The syntax for this as follows: |
|
Line 355 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 406 For the second, function calls (sections 2, 3, 9): |
|
Line 408 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 604 column, if applicable, describes closure rules. |
|
Line 620 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 |
Line 802 then the macro accepts an arbitrary number of argument |
|
Line 821 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 |
Line 1040 Its syntax is as follows: |
|
Line 1059 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 1851 A function name. |
|
Line 1871 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 1882 This is a multi-line version of |
|
Line 1902 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 |
|
|
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 , |
|
|
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 2324 Removes the space |
|
Line 2344 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 2452 Its syntax is as follows: |
|
Line 2472 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 |
Line 2679 Link to another manual |
|
Line 2699 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 2712 This macro should not be used; it is implemented for c |
|
Line 2732 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, |