version 1.29, 2009/08/19 11:30:40 |
version 1.31, 2009/08/20 11:51:07 |
|
|
Each |
Each |
. Nm |
. Nm |
document must contain contains at least the |
document must contain contains at least the |
. Sq \&TH |
. Sq TH |
macro describing the document's section and title. It may occur |
macro describing the document's section and title. It may occur |
anywhere in the document, although conventionally, it appears as the |
anywhere in the document, although conventionally, it appears as the |
first macro. |
first macro. |
. Pp |
. Pp |
Beyond |
Beyond |
. Sq \&TH , |
. Sq TH , |
at least one macro or text node must appear in the document. Documents |
at least one macro or text node must appear in the document. Documents |
are generally structured as follows: |
are generally structured as follows: |
. Bd -literal -offset indent |
. Bd -literal -offset indent |
Line 163 control character , |
|
Line 163 control character , |
|
. Sq \&. , |
. Sq \&. , |
at the beginning of the line. An arbitrary amount of whitespace may |
at the beginning of the line. An arbitrary amount of whitespace may |
sit between the control character and the macro name. Thus, |
sit between the control character and the macro name. Thus, |
. Sq \&.PP |
. Sq .PP |
and |
and |
. Sq \&.\ \ \ \&PP |
. Sq \&.\ \ \ PP |
are equivalent. |
are equivalent. |
. Pp |
. Pp |
The |
The |
. Nm |
. Nm |
macros are classified by scope: line scope or block scope. Line-scoped |
macros are classified by scope: line scope or block scope. Line |
macros are only scoped to the current line (and, in some situations, |
macros are only scoped to the current line (and, in some situations, |
the subsequent line). Block macros are scoped to the current line and |
the subsequent line). Block macros are scoped to the current line and |
subsequent lines until closed by another block macro. |
subsequent lines until closed by another block macro. |
. |
. |
. |
. |
. Ss Line Macros |
. Ss Line Macros |
Line-macros are scoped to the current line, with the body consisting of |
Line macros are generally scoped to the current line, with the body |
zero or more arguments. If a macro is next-line scoped and the line |
consisting of zero or more arguments. If a macro is scoped to the next |
arguments are empty, the next line is used instead. Thus: |
line and the line arguments are empty, the next line is used instead, |
|
else the general syntax is used. Thus: |
. Bd -literal -offset indent |
. Bd -literal -offset indent |
\&.RI |
\&.I |
foo |
foo |
. Ed |
. Ed |
. Pp |
. Pp |
is equivalent to |
is equivalent to |
. Sq \&.RI foo . |
. Sq \&.I foo . |
.\" PARAGRAPH |
.\" PARAGRAPH |
Consecutive next-line invocations are disallowed. |
Consecutive next-line scope invocations are disallowed. |
. Bd -literal -offset indent |
. Bd -literal -offset indent |
\&.YO \(lBbody...\(rB |
\&.YO \(lBbody...\(rB |
\(lBbody...\(rB |
\(lBbody...\(rB |
. Ed |
. Ed |
. Pp |
. Pp |
|
It is considered an error when next-line scope is open at the end of |
|
file. |
|
. Pp |
. Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" |
. Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" |
. It Em Macro Ta Em Arguments Ta Em Scope |
. It Em Macro Ta Em Arguments Ta Em Scope |
. It \&B Ta n Ta next-line |
. It B Ta n Ta next-line |
. It \&BI Ta n Ta current |
. It BI Ta n Ta current |
. It \&BR Ta n Ta current |
. It BR Ta n Ta current |
. It \&I Ta n Ta next-line |
. It DT Ta 0 Ta current |
. It \&IB Ta n Ta current |
. It I Ta n Ta next-line |
. It \&IR Ta n Ta current |
. It IB Ta n Ta current |
. It \&R Ta n Ta next-line |
. It IR Ta n Ta current |
. It \&RB Ta n Ta current |
. It R Ta n Ta next-line |
. It \&RI Ta n Ta current |
. It RB Ta n Ta current |
. It \&SB Ta n Ta next-line |
. It RI Ta n Ta current |
. It \&SM Ta n Ta next-line |
. It SB Ta n Ta next-line |
. It \&TH Ta >1, <6 Ta current |
. It SM Ta n Ta next-line |
. It \&br Ta 0 Ta current |
. It TH Ta >1, <6 Ta current |
. It \&fi Ta 0 Ta current |
. It br Ta 0 Ta current |
. It \&i Ta n Ta current |
. It fi Ta 0 Ta current |
. It \&na Ta 0 Ta current |
. It i Ta n Ta current |
. It \&nf Ta 0 Ta current |
. It na Ta 0 Ta current |
. It \&r Ta 0 Ta current |
. It nf Ta 0 Ta current |
. It \&sp Ta 1 Ta current |
. It r Ta 0 Ta current |
|
. It sp Ta 1 Ta current |
. El |
. El |
. Pp |
. Pp |
The lower-case |
The |
. Sq \&br , |
. Sq RS , |
. Sq \&fi , |
. Sq RE , |
. Sq \&i , |
. Sq br , |
. Sq \&na , |
. Sq fi , |
. Sq \&nf , |
. Sq i , |
. Sq \&r , |
. Sq na , |
|
. Sq nf , |
|
. Sq r , |
and |
and |
. Sq \&sp |
. Sq sp |
macros aren't historically part of |
macros aren't historically part of |
. Nm |
. Nm |
and should not be used. They're included for compatibility. |
and should not be used. They're included for compatibility. |
. |
. |
. |
. |
. Ss Block Macros |
. Ss Block Macros |
Block macros are comprised of a head and body. The head is scoped to |
Block macros are comprised of a head and body. Like for in-line macros, |
the current line and, in one circumstance, the next line; the body is |
the head is scoped to the current line and, in one circumstance, the |
scoped to subsequent lines and is closed out by a subsequent block macro |
next line; the body is scoped to subsequent lines and is closed out by a |
invocation. |
subsequent block macro invocation. |
. Bd -literal -offset indent |
. Bd -literal -offset indent |
\&.YO \(lBhead...\(rB |
\&.YO \(lBhead...\(rB |
\(lBhead...\(rB |
\(lBhead...\(rB |
\(lBbody...\(rB |
\(lBbody...\(rB |
. Ed |
. Ed |
. Pp |
. Pp |
|
The closure of body scope may be to the section, where a macro is closed |
|
by |
|
. Sq SH ; |
|
sub-section, closed by a section or |
|
. Sq SS ; |
|
part, closed by a section, sub-section, or |
|
. Sq RE ; |
|
or paragraph, closed by a section, sub-section, part, |
|
. Sq HP , |
|
. Sq IP , |
|
. Sq LP , |
|
. Sq P , |
|
. Sq PP , |
|
or |
|
. Sq TP . |
|
No closure refers to an explicit block closing macro. |
|
. Pp |
|
It is considered an error when part or next-line scope is open at the |
|
end of file. |
|
. Pp |
|
. Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" -compact -offset indent |
|
. It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope |
|
. It HP Ta <2 Ta current Ta paragraph |
|
. It IP Ta <3 Ta current Ta paragraph |
|
. It LP Ta 0 Ta current Ta paragraph |
|
. It P Ta 0 Ta current Ta paragraph |
|
. It PP Ta 0 Ta current Ta paragraph |
|
. It RE Ta 0 Ta current Ta none |
|
. It RS Ta 1 Ta current Ta part |
|
. It SH Ta >0 Ta current Ta section |
|
. It SS Ta >0 Ta current Ta sub-section |
|
. It TP Ta n Ta next-line Ta paragraph |
|
. El |
|
. Pp |
If a block macro is next-line scoped, it may only be followed by in-line |
If a block macro is next-line scoped, it may only be followed by in-line |
macros (excluding |
macros (excluding |
|
. Sq DT , |
|
. Sq TH , |
. Sq br , |
. Sq br , |
. Sq na , |
. Sq na , |
. Sq sp , |
. Sq sp , |
. Sq nf , |
. Sq nf , |
. Sq fi , |
|
and |
and |
. Sq TH ) . |
. Sq fi ) . |
. Pp |
|
. Bl -column "MacroX" "Arguments" "ScopeXXXX" -compact -offset indent |
|
. It Em Macro Ta Em Arguments Ta Em Scope |
|
. It \&HP Ta <2 Ta current |
|
. It \&IP Ta <3 Ta current |
|
. It \&LP Ta 0 Ta current |
|
. It \&P Ta 0 Ta current |
|
. It \&PP Ta 0 Ta current |
|
. It \&SH Ta >0 Ta current |
|
. It \&SS Ta >0 Ta current |
|
. It \&TP Ta n Ta next-line |
|
. El |
|
. |
. |
. |
. |
.Sh REFERENCE |
.Sh REFERENCE |
Line 271 alphabetically. For the scoping of individual macros, |
|
Line 301 alphabetically. For the scoping of individual macros, |
|
. Sx MACRO SYNTAX . |
. Sx MACRO SYNTAX . |
. |
. |
. |
. |
. Ss Terms |
. Ss Definitions |
In this reference, a numerical width may be either a standalone natural |
In this reference, a numerical width may be either a standalone natural |
number (such as 3, 4, 10, etc.) or a natural number followed by a width |
number (such as 3, 4, 10, etc.) or a natural number followed by a width |
multiplier |
multiplier |
|
|
. |
. |
. Ss Macro Reference |
. Ss Macro Reference |
. Bl -tag -width Ds |
. Bl -tag -width Ds |
. It \&B |
. It B |
Text is rendered in bold face. |
Text is rendered in bold face. |
. It \&BI |
. It BI |
Text is rendered alternately in bold face and italic. Thus, |
Text is rendered alternately in bold face and italic. Thus, |
. Sq \&.BI this word and that |
. Sq .BI this word and that |
causes |
causes |
. Sq this |
. Sq this |
and |
and |
Line 306 to render in bold face, while |
|
Line 336 to render in bold face, while |
|
and |
and |
. Sq that |
. Sq that |
render in italics. Whitespace between arguments is omitted in output. |
render in italics. Whitespace between arguments is omitted in output. |
. It \&BR |
. It BR |
Text is rendered alternately in bold face and roman (the default font). |
Text is rendered alternately in bold face and roman (the default font). |
Whitespace between arguments is omitted in output. |
Whitespace between arguments is omitted in output. |
. It \&HP |
. It DT |
|
Re-set the tab spacing to 0.5 inches. |
|
. It HP |
Begin a paragraph whose initial output line is left-justified, but |
Begin a paragraph whose initial output line is left-justified, but |
subsequent output lines are indented, with the following syntax: |
subsequent output lines are indented, with the following syntax: |
. Bd -literal -offset indent |
. Bd -literal -offset indent |
|
|
. Va width |
. Va width |
is specified, it's saved for later paragraph left-margins; if |
is specified, it's saved for later paragraph left-margins; if |
unspecified, the saved or default width is used. |
unspecified, the saved or default width is used. |
. It \&I |
. It I |
Text is rendered in italics. |
Text is rendered in italics. |
. It \&IB |
. It IB |
Text is rendered alternately in italics and bold face. Whitespace |
Text is rendered alternately in italics and bold face. Whitespace |
between arguments is omitted in output. |
between arguments is omitted in output. |
. It \&IP |
. It IP |
Begin a paragraph with the following syntax: |
Begin a paragraph with the following syntax: |
. Bd -literal -offset indent |
. Bd -literal -offset indent |
\&.IP [head [width]] |
\&.IP [head [width]] |
. Ed |
. Ed |
. Pp |
. Pp |
This follows the behaviour of the |
This follows the behaviour of the |
. Sq \&TP |
. Sq TP |
except for the macro syntax (all arguments on the line, instead of |
except for the macro syntax (all arguments on the line, instead of |
having next-line scope). If |
having next-line scope). If |
. Va width |
. Va width |
is specified, it's saved for later paragraph left-margins; if |
is specified, it's saved for later paragraph left-margins; if |
unspecified, the saved or default width is used. |
unspecified, the saved or default width is used. |
. It \&IR |
. It IR |
Text is rendered alternately in italics and roman (the default font). |
Text is rendered alternately in italics and roman (the default font). |
Whitespace between arguments is omitted in output. |
Whitespace between arguments is omitted in output. |
. It \&LP, \&P, \&PP |
. It LP, P, PP |
Begin an undecorated paragraph. The scope of a paragraph is closed by a |
Begin an undecorated paragraph. The scope of a paragraph is closed by a |
subsequent paragraph, sub-section, section, or end of file. The saved |
subsequent paragraph, sub-section, section, or end of file. The saved |
paragraph left-margin width is re-set to the default. |
paragraph left-margin width is re-set to the default. |
. It \&R |
. It R |
Text is rendered in roman (the default font). |
Text is rendered in roman (the default font). |
. It \&RB |
. It RB |
Text is rendered alternately in roman (the default font) and bold face. |
Text is rendered alternately in roman (the default font) and bold face. |
Whitespace between arguments is omitted in output. |
Whitespace between arguments is omitted in output. |
. It \&RI |
. It RE |
|
Explicitly close out the scope of a prior |
|
. Sq RS . |
|
. It RI |
Text is rendered alternately in roman (the default font) and italics. |
Text is rendered alternately in roman (the default font) and italics. |
Whitespace between arguments is omitted in output. |
Whitespace between arguments is omitted in output. |
. It \&SB |
. It RS |
|
Begin a part setting the left margin. The left margin controls the |
|
offset, following an initial indentation, to un-indented text such as |
|
that of |
|
. Sq PP . |
|
The width may be specified as following: |
|
. Bd -literal -offset indent |
|
\&.RS [width] |
|
. Ed |
|
. Pp |
|
If |
|
. Va width |
|
is not specified, the saved or default width is used. |
|
. It SB |
Text is rendered in small size (one point smaller than the default font) |
Text is rendered in small size (one point smaller than the default font) |
bold face. |
bold face. |
. It \&SH |
. It SH |
Begin a section. The scope of a section is only closed by another |
Begin a section. The scope of a section is only closed by another |
section or the end of file. The paragraph left-margin width is re-set |
section or the end of file. The paragraph left-margin width is re-set |
to the default. |
to the default. |
. It \&SM |
. It SM |
Text is rendered in small size (one point smaller than the default |
Text is rendered in small size (one point smaller than the default |
font). |
font). |
. It \&SS |
. It SS |
Begin a sub-section. The scope of a sub-section is closed by a |
Begin a sub-section. The scope of a sub-section is closed by a |
subsequent sub-section, section, or end of file. The paragraph |
subsequent sub-section, section, or end of file. The paragraph |
left-margin width is re-set to the default. |
left-margin width is re-set to the default. |
. It \&TH |
. It TH |
Sets the title of the manual page with the following syntax: |
Sets the title of the manual page with the following syntax: |
. Bd -literal -offset indent |
. Bd -literal -offset indent |
\&.TH title section date source volume |
\&.TH title section [date [source [volume]]] |
. Ed |
. Ed |
. Pp |
. Pp |
At least the |
At least the |
|
|
string specifies the organisation providing the utility. The |
string specifies the organisation providing the utility. The |
. Va volume |
. Va volume |
replaces the default rendered volume as dictated by the manual section. |
replaces the default rendered volume as dictated by the manual section. |
. It \&TP |
. It TP |
Begin a paragraph where the head, if exceeding the indentation width, is |
Begin a paragraph where the head, if exceeding the indentation width, is |
followed by a newline; if not, the body follows on the same line after a |
followed by a newline; if not, the body follows on the same line after a |
buffer to the indentation width. Subsequent output lines are indented. |
buffer to the indentation width. Subsequent output lines are indented. |
Line 404 must be a properly-formed numeric width. If |
|
Line 452 must be a properly-formed numeric width. If |
|
. Va width |
. Va width |
is specified, it's saved for later paragraph left-margins; if |
is specified, it's saved for later paragraph left-margins; if |
unspecified, the saved or default width is used. |
unspecified, the saved or default width is used. |
. It \&br |
. It br |
Breaks the current line. Consecutive invocations have no further effect. |
Breaks the current line. Consecutive invocations have no further effect. |
. It \&fi |
. It fi |
End literal mode begun by |
End literal mode begun by |
. Sq \&nf . |
. Sq nf . |
. It \&i |
. It i |
Italicise arguments. If no arguments are specified, all subsequent text |
Italicise arguments. If no arguments are specified, all subsequent text |
is italicised. |
is italicised. |
. It \&na |
. It na |
No alignment to the right margin. |
Don't alignment the right margin. |
. It \&nf |
. It nf |
Begin literal mode: all subsequent free-form lines have their end of |
Begin literal mode: all subsequent free-form lines have their end of |
line boundaries preserved. May be ended by |
line boundaries preserved. May be ended by |
. Sq \&fi . |
. Sq fi . |
. It \&r |
. It r |
Fonts and styles (bold face, italics) reset to roman (default font). |
Fonts and styles (bold face, italics) reset to roman (default font). |
. It \&sp |
. It sp |
Insert n spaces, where n is the macro's positive numeric argument. If |
Insert n spaces, where n is the macro's positive numeric argument. If |
0, this is equivalent to the |
0, this is equivalent to the |
. Sq br |
. Sq br |
Line 439 standalone double-quote in formatted output. This idi |
|
Line 487 standalone double-quote in formatted output. This idi |
|
behaviour is no longer applicable. |
behaviour is no longer applicable. |
. It |
. It |
The |
The |
. Sq \&sp |
. Sq sp |
macro does not accept negative numbers. |
macro does not accept negative numbers. |
. It |
. It |
Blocks of whitespace are stripped from both macro and free-form text |
Blocks of whitespace are stripped from both macro and free-form text |