version 1.191, 2011/07/18 10:23:02 |
version 1.194, 2011/08/01 07:45:11 |
Line 178 trailing spaces are stripped from input (unless in a l |
|
Line 178 trailing spaces are stripped from input (unless in a l |
|
Blank text 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 general, trailing whitespace on input lines is discouraged |
|
for reasons of clarity and portability. |
|
In the rare case that a blank character is needed at the end of an |
|
input line, it may be forced by |
|
.Sq \e\ \e& . |
|
.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. |
|
.Ss Quotation |
.Ss Quotation |
Macro arguments may be quoted with double-quotes to group |
Macro arguments may be quoted with double-quotes; in this case, |
space-delimited terms or to retain blocks of whitespace. |
whitespace within the quotes is retained as part of the argument. |
|
For example, |
|
.Pp |
|
.D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq" |
|
.Pp |
|
renders as |
|
.Sq Fn strlen "const char *s" , |
|
while |
|
.Pp |
|
.D1 Pf \. \&Fn strlen "const char *s" |
|
.Pp |
|
would produce |
|
.Sq Fn strlen const char *s . |
|
.Pp |
A quoted argument begins with a double-quote preceded by whitespace. |
A quoted argument begins with a double-quote preceded by whitespace. |
The next double-quote not pairwise adjacent to another double-quote |
The next double-quote not pairwise adjacent to another double-quote |
terminates the literal, regardless of surrounding whitespace. |
terminates the literal, regardless of surrounding whitespace. |
.Pp |
.Pp |
|
In unquoted arguments, space characters can alternatively be included |
|
by preceding them with a backslash |
|
.Pq Sq \e\~ , |
|
but quoting is usually better for clarity. |
|
.Pp |
Note that any quoted text, even if it would cause a macro invocation |
Note that any quoted text, even if it would cause a macro invocation |
when unquoted, is considered literal text. |
when unquoted, is considered literal text. |
Thus, the following produces |
Thus, the following produces |
Line 304 file for a utility |
|
Line 327 file for a utility |
|
\&.Os |
\&.Os |
\&.Sh NAME |
\&.Sh NAME |
\&.Nm progname |
\&.Nm progname |
\&.Nd a description goes here |
\&.Nd one line about what it does |
\&.\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. |
|
|
.Em Callable |
.Em Callable |
column indicates that the macro may also be called by passing its name |
column indicates that the macro may also be called by passing its name |
as an argument to another macro. |
as an argument to another macro. |
|
For example, |
|
.Sq \&.Op \&Fl O \&Ar file |
|
produces |
|
.Sq Op Fl O Ar file . |
|
To prevent a macro call and render the macro name literally, |
|
escape it by prepending a non-breaking space, |
|
.Sq \e& . |
|
For example, |
|
.Sq \&Op \e&Fl O |
|
produces |
|
.Sq Op \&Fl O . |
If a macro is not callable but its name appears as an argument |
If a macro is not callable but its name appears as an argument |
to another macro, it is interpreted as opaque text. |
to another macro, it is interpreted as opaque text. |
For example, |
For example, |
Line 1038 Accepts one optional argument: |
|
Line 1072 Accepts one optional argument: |
|
.It Cm v[1-7] | 32v |
.It Cm v[1-7] | 32v |
A version of |
A version of |
.At . |
.At . |
|
.It Cm III |
|
.At III . |
.It Cm V[.[1-4]]? |
.It Cm V[.[1-4]]? |
A version of |
A version of |
.At V . |
.At V . |
Line 1047 Note that these arguments do not begin with a hyphen. |
|
Line 1083 Note that these arguments do not begin with a hyphen. |
|
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.At |
.Dl \&.At |
|
.Dl \&.At III |
.Dl \&.At V.1 |
.Dl \&.At V.1 |
.Pp |
.Pp |
See also |
See also |
Line 1825 Insert a standard sentence regarding command exit valu |
|
Line 1862 Insert a standard sentence regarding command exit valu |
|
and >0 on failure. |
and >0 on failure. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Ex Fl std Op Ar utility... |
.D1 Pf \. Sx \&Ex Fl std Op Ar utility ... |
.Pp |
.Pp |
If |
If |
.Ar utility |
.Ar utility |
Line 2122 The syntax is as follows: |
|
Line 2159 The syntax is as follows: |
|
The |
The |
.Ar library |
.Ar library |
parameter may be a system library, such as |
parameter may be a system library, such as |
.Ar libz |
.Cm libz |
or |
or |
.Ar libpam , |
.Cm 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. |
Line 2466 block is used within a SEE ALSO section, a vertical sp |
|
Line 2503 block is used within a SEE ALSO section, a vertical sp |
|
before the rendered output, else the block continues on the current |
before the rendered output, else the block continues on the current |
line. |
line. |
.Ss \&Rv |
.Ss \&Rv |
Insert a standard sentence regarding a system call's return value of 0 |
Insert a standard sentence regarding a function call's return value of 0 |
on success and \-1 on error, with the |
on success and \-1 on error, with the |
.Va errno |
.Va errno |
libc global variable set on error. |
libc global variable set on error. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Rv Fl std Op Ar function... |
.D1 Pf \. Sx \&Rv Fl std Op Ar function ... |
.Pp |
.Pp |
If |
If |
.Ar function |
.Ar function |
Line 2510 Its syntax is as follows: |
|
Line 2547 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 |
.Ar on . |
.Cm on . |
When switched |
When switched |
.Ar off , |
.Cm 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 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. |