version 1.84, 2010/08/24 13:07:01 |
version 1.100, 2011/05/26 09:26:16 |
Line 53 Other lines are interpreted within the current state. |
|
Line 53 Other lines are interpreted within the current state. |
|
.Nm |
.Nm |
documents may contain only graphable 7-bit ASCII characters, the |
documents may contain only graphable 7-bit ASCII characters, the |
space character, and the tab character. |
space character, and the tab character. |
All manuals must have |
|
.Ux |
|
line termination. |
|
.Pp |
.Pp |
Blank lines are acceptable; where found, the output will assert a |
Blank lines are acceptable; where found, the output will assert a |
vertical space. |
vertical space. |
|
.Pp |
|
If the first character of a line is a space, that line is printed |
|
with a leading newline. |
.Ss Comments |
.Ss Comments |
Text following a |
Text following a |
.Sq \e\*q , |
.Sq \e\*q , |
Line 118 rendered as an empty line. |
|
Line 118 rendered as an empty line. |
|
.Pp |
.Pp |
In macro lines, whitespace delimits arguments and is discarded. |
In macro lines, whitespace delimits arguments and is discarded. |
If arguments are quoted, whitespace within the quotes is retained. |
If arguments are quoted, whitespace within the quotes is retained. |
.Ss Dates |
|
The |
|
.Sx \&TH |
|
macro is the only |
|
.Nm |
|
macro that requires a date. |
|
The form for this date is the ISO-8601 |
|
standard |
|
.Cm YYYY-MM-DD . |
|
.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 paragraph indentation with the following: |
stipulating a two-inch paragraph indentation with the following: |
Line 214 appears as the first macro. |
|
Line 205 appears as the first macro. |
|
Beyond |
Beyond |
.Sx \&TH , |
.Sx \&TH , |
at least one macro or text node must appear in the document. |
at least one macro or text node must appear in the document. |
Documents are generally structured as follows: |
.Pp |
|
The following is a well-formed skeleton |
|
.Nm |
|
file for a utility |
|
.Qq progname : |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.TH FOO 1 2009-10-10 |
\&.TH PROGNAME 1 2009-10-10 |
\&.SH NAME |
\&.SH NAME |
\efBfoo\efR \e(en a description goes here |
\efBprogname\efR \e(en a description goes here |
\&.\e\*q The next is for sections 2 & 3 only. |
|
\&.\e\*q .SH LIBRARY |
\&.\e\*q .SH LIBRARY |
|
\&.\e\*q For sections 2 & 3 only. |
|
\&.\e\*q Not used in OpenBSD. |
\&.SH SYNOPSIS |
\&.SH SYNOPSIS |
\efBfoo\efR [\efB\e-options\efR] arguments... |
\efBprogname\efR [\efB\e-options\efR] arguments... |
\&.SH DESCRIPTION |
\&.SH DESCRIPTION |
The \efBfoo\efR utility processes files... |
The \efBfoo\efR utility processes files... |
\&.\e\*q .SH IMPLEMENTATION NOTES |
\&.\e\*q .SH IMPLEMENTATION NOTES |
\&.\e\*q The next is for sections 2, 3, & 9 only. |
\&.\e\*q Not used in OpenBSD. |
\&.\e\*q .SH RETURN VALUES |
\&.\e\*q .SH RETURN VALUES |
\&.\e\*q The next is for sections 1, 6, 7, & 8 only. |
\&.\e\*q For sections 2, 3, & 9 only. |
\&.\e\*q .SH ENVIRONMENT |
\&.\e\*q .SH ENVIRONMENT |
|
\&.\e\*q For sections 1, 6, 7, & 8 only. |
\&.\e\*q .SH FILES |
\&.\e\*q .SH FILES |
\&.\e\*q The next is for sections 1 & 8 only. |
|
\&.\e\*q .SH EXIT STATUS |
\&.\e\*q .SH EXIT STATUS |
|
\&.\e\*q For sections 1, 6, & 8 only. |
\&.\e\*q .SH EXAMPLES |
\&.\e\*q .SH EXAMPLES |
\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only. |
|
\&.\e\*q .SH DIAGNOSTICS |
\&.\e\*q .SH DIAGNOSTICS |
\&.\e\*q The next is for sections 2, 3, & 9 only. |
\&.\e\*q For sections 1, 4, 6, 7, & 8 only. |
\&.\e\*q .SH ERRORS |
\&.\e\*q .SH ERRORS |
|
\&.\e\*q For sections 2, 3, & 9 only. |
\&.\e\*q .SH SEE ALSO |
\&.\e\*q .SH SEE ALSO |
\&.\e\*q .BR foo ( 1 ) |
\&.\e\*q .BR foo ( 1 ) |
\&.\e\*q .SH STANDARDS |
\&.\e\*q .SH STANDARDS |
Line 246 The \efBfoo\efR utility processes files... |
|
Line 243 The \efBfoo\efR utility processes files... |
|
\&.\e\*q .SH CAVEATS |
\&.\e\*q .SH CAVEATS |
\&.\e\*q .SH BUGS |
\&.\e\*q .SH BUGS |
\&.\e\*q .SH SECURITY CONSIDERATIONS |
\&.\e\*q .SH SECURITY CONSIDERATIONS |
|
\&.\e\*q Not used in OpenBSD. |
.Ed |
.Ed |
.Pp |
.Pp |
The sections in a |
The sections in a |
Line 367 Thus, the following are equivalent: |
|
Line 365 Thus, the following are equivalent: |
|
\&.\ \ \ PP |
\&.\ \ \ PP |
.Ed |
.Ed |
.Pp |
.Pp |
|
To include space characters in macro arguments, arguments may be quoted; |
|
see the |
|
.Sq MACRO SYNTAX |
|
section in the |
|
.Xr roff 7 |
|
manual for details. |
|
.Pp |
The |
The |
.Nm |
.Nm |
macros are classified by scope: line scope or block scope. |
macros are classified by scope: line scope or block scope. |
Line 411 The syntax is as follows: |
|
Line 416 The syntax is as follows: |
|
.It Sx \&I Ta n Ta next-line Ta \& |
.It Sx \&I Ta n Ta next-line Ta \& |
.It Sx \&IB Ta n Ta current Ta \& |
.It Sx \&IB Ta n Ta current Ta \& |
.It Sx \&IR Ta n Ta current Ta \& |
.It Sx \&IR Ta n Ta current Ta \& |
.\" .It Sx \&PD Ta n Ta current Ta compat |
|
.It Sx \&R Ta n Ta next-line Ta \& |
.It Sx \&R Ta n Ta next-line Ta \& |
.It Sx \&RB Ta n Ta current Ta \& |
.It Sx \&RB Ta n Ta current Ta \& |
.It Sx \&RI Ta n Ta current Ta \& |
.It Sx \&RI Ta n Ta current Ta \& |
Line 421 The syntax is as follows: |
|
Line 425 The syntax is as follows: |
|
.It Sx \&UC Ta <=1 Ta current Ta \& |
.It Sx \&UC Ta <=1 Ta current Ta \& |
.It Sx \&br Ta 0 Ta current Ta compat |
.It Sx \&br Ta 0 Ta current Ta compat |
.It Sx \&fi Ta 0 Ta current Ta compat |
.It Sx \&fi Ta 0 Ta current Ta compat |
.It Sx \&i Ta n Ta current Ta compat |
.It Sx \&ft Ta 1 Ta current Ta compat |
.It Sx \&in Ta 1 Ta current Ta compat |
.It Sx \&in Ta 1 Ta current Ta compat |
.It Sx \&na Ta 0 Ta current Ta compat |
.It Sx \&na Ta 0 Ta current Ta compat |
.It Sx \&nf Ta 0 Ta current Ta compat |
.It Sx \&nf Ta 0 Ta current Ta compat |
.It Sx \&r Ta 0 Ta current Ta compat |
|
.It Sx \&sp Ta 1 Ta current Ta compat |
.It Sx \&sp Ta 1 Ta current Ta compat |
.\" .It Sx \&Sp Ta <1 Ta current Ta compat |
|
.\" .It Sx \&Vb Ta <1 Ta current Ta compat |
|
.\" .It Sx \&Ve Ta 0 Ta current Ta compat |
|
.El |
.El |
.Pp |
.Pp |
Macros marked as |
Macros marked as |
Line 509 The optional arguments specify which release it is fro |
|
Line 509 The optional arguments specify which release it is fro |
|
Text is rendered in bold face. |
Text is rendered in bold face. |
.Pp |
.Pp |
See also |
See also |
.Sx \&I , |
.Sx \&I |
.Sx \&R , |
|
.Sx \&b , |
|
.Sx \&i , |
|
and |
and |
.Sx \&r . |
.Sx \&R . |
.Ss \&BI |
.Ss \&BI |
Text is rendered alternately in bold face and italic. |
Text is rendered alternately in bold face and italic. |
Thus, |
Thus, |
Line 532 Whitespace between arguments is omitted in output. |
|
Line 529 Whitespace between arguments is omitted in output. |
|
.Pp |
.Pp |
Examples: |
Examples: |
.Pp |
.Pp |
.D1 \&.BI bold italic bold italic |
.Dl \&.BI bold italic bold italic |
.Pp |
.Pp |
The output of this example will be emboldened |
The output of this example will be emboldened |
.Dq bold |
.Dq bold |
|
|
Text is rendered in italics. |
Text is rendered in italics. |
.Pp |
.Pp |
See also |
See also |
.Sx \&B , |
.Sx \&B |
.Sx \&R , |
|
.Sx \&b , |
|
.Sx \&i , |
|
and |
and |
.Sx \&r . |
.Sx \&R . |
.Ss \&IB |
.Ss \&IB |
Text is rendered alternately in italics and bold face. |
Text is rendered alternately in italics and bold face. |
Whitespace between arguments is omitted in output. |
Whitespace between arguments is omitted in output. |
|
|
Text is rendered in roman (the default font). |
Text is rendered in roman (the default font). |
.Pp |
.Pp |
See also |
See also |
.Sx \&I , |
.Sx \&I |
.Sx \&B , |
|
.Sx \&b , |
|
.Sx \&i , |
|
and |
and |
.Sx \&r . |
.Sx \&B . |
.Ss \&RB |
.Ss \&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. |
Line 767 The paragraph left-margin width is reset to the defaul |
|
Line 758 The paragraph left-margin width is reset to the defaul |
|
Sets the title of the manual page with the following syntax: |
Sets the title of the manual page with the following syntax: |
.Bd -filled -offset indent |
.Bd -filled -offset indent |
.Pf \. Sx \&TH |
.Pf \. Sx \&TH |
.Cm title section |
.Ar title section date |
.Op Cm date Op Cm source Op Cm volume |
.Op Ar source Op Ar volume |
.Ed |
.Ed |
.Pp |
.Pp |
At least the upper-case document |
Conventionally, the document |
.Cm title |
.Ar title |
and the manual |
is given in all caps. |
.Cm section |
The recommended |
arguments must be provided. |
.Ar date |
The |
format is |
.Cm date |
.Sy YYYY-MM-DD |
argument should be formatted as described in |
as specified in the ISO-8601 standard; |
.Sx Dates , |
if the argument does not conform, it is printed verbatim. |
but will be printed verbatim if it is not. |
If the |
If the date is not specified, the current date is used. |
.Ar date |
The |
is empty or not specified, the current date is used. |
.Cm source |
The optional |
|
.Ar source |
string specifies the organisation providing the utility. |
string specifies the organisation providing the utility. |
The |
The |
.Cm volume |
.Ar volume |
string replaces the default rendered volume, which is dictated by the |
string replaces the default rendered volume, which is dictated by the |
manual section. |
manual section. |
.Pp |
.Pp |
Examples: |
Examples: |
.Pp |
.Pp |
.D1 \&.TH CVS 5 "1992-02-12" GNU |
.Dl \&.TH CVS 5 "1992-02-12" GNU |
.Ss \&TP |
.Ss \&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 |
|
|
.Sx \&P , |
.Sx \&P , |
and |
and |
.Sx \&PP . |
.Sx \&PP . |
.\" . |
|
.\" . |
|
.\" .Ss \&PD |
|
.\" Has no effect. Included for compatibility. |
|
.\" . |
|
.\" . |
|
.Ss \&UC |
.Ss \&UC |
Sets the volume for the footer for compatibility with man pages from |
Sets the volume for the footer for compatibility with man pages from |
BSD releases. |
BSD releases. |
|
|
.Ss \&fi |
.Ss \&fi |
End literal mode begun by |
End literal mode begun by |
.Sx \&nf . |
.Sx \&nf . |
.Ss \&i |
.Ss \&ft |
Italicise arguments. |
Change the current font mode. |
Synonym for |
See |
.Sx \&I . |
.Sx Text Decoration |
.Pp |
for a listing of available font modes. |
See also |
|
.Sx \&B , |
|
.Sx \&I , |
|
.Sx \&R . |
|
.Sx \&b , |
|
and |
|
.Sx \&r . |
|
.Ss \&in |
.Ss \&in |
Indent relative to the current indentation: |
Indent relative to the current indentation: |
.Pp |
.Pp |
Line 866 Begin literal mode: all subsequent free-form lines hav |
|
Line 845 Begin literal mode: all subsequent free-form lines hav |
|
line boundaries preserved. |
line boundaries preserved. |
May be ended by |
May be ended by |
.Sx \&fi . |
.Sx \&fi . |
.Ss \&r |
|
Fonts and styles (bold face, italics) reset to roman (default font). |
|
.Pp |
|
See also |
|
.Sx \&B , |
|
.Sx \&I , |
|
.Sx \&R , |
|
.Sx \&b , |
|
and |
|
.Sx \&i . |
|
.Ss \&sp |
.Ss \&sp |
Insert vertical spaces into output with the following syntax: |
Insert vertical spaces into output with the following syntax: |
.Bd -filled -offset indent |
.Bd -filled -offset indent |
Line 894 Defaults to 1, if unspecified. |
|
Line 863 Defaults to 1, if unspecified. |
|
.Pp |
.Pp |
See also |
See also |
.Sx \&br . |
.Sx \&br . |
.\" .Ss \&Sp |
|
.\" A synonym for |
|
.\" .Sx \&sp |
|
.\" .Cm 0.5v . |
|
.\" . |
|
.\" .Ss \&Vb |
|
.\" A synonym for |
|
.\" .Sx \&nf . |
|
.\" Accepts an argument (the height of the formatted space) which is |
|
.\" disregarded. |
|
.\" . |
|
.\" .Ss \&Ve |
|
.\" A synonym for |
|
.\" .Sx \&fi . |
|
.\" . |
|
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section documents areas of questionable portability between |
This section documents areas of questionable portability between |
implementations of the |
implementations of the |
|
|
.Pq zero-length character , |
.Pq zero-length character , |
.Sq \ew |
.Sq \ew |
.Pq string length , |
.Pq string length , |
|
.Sq \ek |
|
.Pq horizontal position marker , |
|
.Sq \eo |
|
.Pq text overstrike , |
and |
and |
.Sq \es |
.Sq \es |
.Pq text size |
.Pq text size |
Line 955 macro does not accept negative values in mandoc. |
|
Line 913 macro does not accept negative values in mandoc. |
|
In GNU troff, this would result in strange behaviour. |
In GNU troff, this would result in strange behaviour. |
.El |
.El |
.Sh SEE ALSO |
.Sh SEE ALSO |
|
.Xr man 1 , |
.Xr mandoc 1 , |
.Xr mandoc 1 , |
.Xr mandoc_char 7 |
.Xr eqn 7 , |
|
.Xr mandoc_char 7 , |
|
.Xr mdoc 7 , |
|
.Xr roff 7 , |
|
.Xr tbl 7 |
.Sh HISTORY |
.Sh HISTORY |
The |
The |
.Nm |
.Nm |