version 1.191, 2011/07/18 10:23:02 |
version 1.195, 2011/08/02 01:07:26 |
Line 65 A macro line with only a control character and comment |
|
Line 65 A macro line with only a control character and comment |
|
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 Terms |
|
Within a macro line, the following terms are reserved: |
|
.Pp |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \&. |
|
.Pq period |
|
.It \e. |
|
.Pq escaped period |
|
.It \&, |
|
.Pq comma |
|
.It \&: |
|
.Pq colon |
|
.It \&; |
|
.Pq semicolon |
|
.It \&( |
|
.Pq left-parenthesis |
|
.It \&) |
|
.Pq right-parenthesis |
|
.It \&[ |
|
.Pq left-bracket |
|
.It \&] |
|
.Pq right-bracket |
|
.It \&? |
|
.Pq question |
|
.It \&! |
|
.Pq exclamation |
|
.It \&| |
|
.Pq vertical bar |
|
.It \e*(Ba |
|
.Pq reserved-word vertical bar |
|
.El |
|
.Pp |
|
For general use in macro lines, these can be escaped with a non-breaking |
|
space |
|
.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 text lines. |
Special characters may occur in both macro and text lines. |
Sequences begin with the escape character |
Sequences begin with the escape character |
Line 178 trailing spaces are stripped from input (unless in a l |
|
Line 142 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 291 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 zero-width 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, |
|
|
.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc |
.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc |
.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 the |
.Sx Reserved Terms |
end of the 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 |
.Ed |
.Ed |
Line 776 these blocks have bodies, but no heads. |
|
Line 773 these blocks have bodies, but no heads. |
|
.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It |
.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It |
.El |
.El |
.Ss In-line |
.Ss In-line |
Closed by |
Closed by the end of the line, fixed argument lengths, |
.Sx Reserved Terms , |
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 |
.Pq n , |
.Pq n , |
Line 868 then the macro accepts an arbitrary number of argument |
|
Line 864 then the macro accepts an arbitrary number of argument |
|
.It Sx \&br Ta \&No Ta \&No Ta 0 |
.It Sx \&br Ta \&No Ta \&No Ta 0 |
.It Sx \&sp Ta \&No Ta \&No Ta 1 |
.It Sx \&sp Ta \&No Ta \&No Ta 1 |
.El |
.El |
|
.Ss Delimiters |
|
When a macro argument consists of one single input character |
|
considered as a delimiter, the argument gets special handling. |
|
This does not apply when delimiters appear in arguments containing |
|
more than one character. |
|
Consequently, to prevent special handling and just handle it |
|
like any other argument, a delimiter can be escaped by prepending |
|
a zero-width space |
|
.Pq Sq \e& . |
|
In text lines, delimiters never need escaping, but may be used |
|
as normal punctuation. |
|
.Pp |
|
For many macros, when the leading arguments are opening delimiters, |
|
these delimiters are put before the macro scope, |
|
and when the trailing arguments are closing delimiters, |
|
these delimiters are put after the macro scope. |
|
For example, |
|
.Pp |
|
.D1 Pf \. \&Aq "( [ word ] ) ." |
|
.Pp |
|
renders as: |
|
.Pp |
|
.D1 Aq ( [ word ] ) . |
|
.Pp |
|
Opening delimiters are: |
|
.Pp |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \&( |
|
left parenthesis |
|
.It \&[ |
|
left bracket |
|
.El |
|
.Pp |
|
Closing delimiters are: |
|
.Pp |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \&. |
|
period |
|
.It \&, |
|
comma |
|
.It \&: |
|
colon |
|
.It \&; |
|
semicolon |
|
.It \&) |
|
right parenthesis |
|
.It \&] |
|
right bracket |
|
.It \&? |
|
question mark |
|
.It \&! |
|
exclamation mark |
|
.El |
|
.Pp |
|
Note that even a period preceded by a backslash |
|
.Pq Sq \e.\& |
|
gets this special handling; use |
|
.Sq \e&. |
|
to prevent that. |
|
.Pp |
|
Many in-line macros interrupt their scope when they encounter |
|
delimiters, and resume their scope when more arguments follow that |
|
are not delimiters. |
|
For example, |
|
.Pp |
|
.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" |
|
.Pp |
|
renders as: |
|
.Pp |
|
.D1 Fl a ( b | c \*(Ba d ) e |
|
.Pp |
|
This applies to both opening and closing delimiters, |
|
and also to the middle delimiter: |
|
.Pp |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \&| |
|
vertical bar |
|
.El |
|
.Pp |
|
As a special case, the predefined string \e*(Ba is handled and rendered |
|
in the same way as a plain |
|
.Sq \&| |
|
character. |
|
Using this predefined string is not recommended in new manuals. |
.Sh REFERENCE |
.Sh REFERENCE |
This section is a canonical reference of all macros, arranged |
This section is a canonical reference of all macros, arranged |
alphabetically. |
alphabetically. |
Line 1038 Accepts one optional argument: |
|
Line 1118 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 1129 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 1908 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 2205 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 2549 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 2593 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. |
Line 2880 In new groff and mandoc, any list may be nested by def |
|
Line 2963 In new groff and mandoc, any list may be nested by def |
|
lists will restart the sequence only for the sub-list. |
lists will restart the sequence only for the sub-list. |
.It |
.It |
.Sx \&Li |
.Sx \&Li |
followed by a reserved character is incorrectly used in some manuals |
followed by a delimiter is incorrectly used in some manuals |
instead of properly quoting that character, which sometimes works with |
instead of properly quoting that character, which sometimes works with |
historic groff. |
historic groff. |
.It |
.It |