version 1.200, 2011/08/17 20:34:53 |
version 1.205, 2011/08/19 13:07:22 |
|
|
.Sx Special Characters . |
.Sx Special Characters . |
.Ss Comments |
.Ss Comments |
Text following an escaped double-quote |
Text following an escaped double-quote |
.Sq \e\*q , |
.Sq \e\(dq , |
whether in a macro or 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 beginning with a control character and comment escape |
A macro line beginning with a control character and comment escape |
.Sq \&.\e\*q |
.Sq \&.\e\(dq |
is also ignored. |
is also ignored. |
Furthermore, |
Furthermore, |
macro lines with only a control character and optional trailing |
macro lines with only a control character and optional trailing |
whitespace are |
whitespace are |
stripped from input. |
stripped from input. |
|
.Pp |
|
Examples: |
|
.Bd -literal -offset indent -compact |
|
\&.\e\(dq This is a comment line. |
|
\&.\e\(dq The next line is ignored: |
|
\&. |
|
\&.Em Emphasis \e\(dq This is also a comment. |
|
.Ed |
.Ss Special Characters |
.Ss Special Characters |
Special characters are used to encode special glyphs and are rendered |
Special characters are used to encode special glyphs and are rendered |
differently across output media. |
differently across output media. |
Line 89 or a single one character sequence. |
|
Line 97 or a single one character sequence. |
|
.Pp |
.Pp |
Examples: |
Examples: |
.Bl -tag -width Ds -offset indent -compact |
.Bl -tag -width Ds -offset indent -compact |
.It \e(em |
.It Li \e(em |
em dash |
Two-letter em dash escape. |
.It \ee |
.It Li \ee |
backslash |
One-letter backslash escape. |
.El |
.El |
.Pp |
.Pp |
See |
See |
|
|
.Pp |
.Pp |
Examples: |
Examples: |
.Bl -tag -width Ds -offset indent -compact |
.Bl -tag -width Ds -offset indent -compact |
.It \efBbold\efR |
.It Li \efBbold\efR |
write in bold, then switch to regular |
Write in bold, then switch to regular font mode. |
.It \efIitalic\efP |
.It Li \efIitalic\efP |
write in italic, then return to previous |
Write in italic, then return to previous font mode. |
.El |
.El |
.Pp |
.Pp |
Text decoration is |
Text decoration is |
|
|
.Pp |
.Pp |
Examples: |
Examples: |
.Bl -tag -width Ds -offset indent -compact |
.Bl -tag -width Ds -offset indent -compact |
.It \e*(Am |
.It Li \e*(Am |
ampersand |
Two-letter ampersand predefined string. |
.It \e*(Ba |
.It Li \e*q |
vertical bar |
One-letter double-quote predefined string. |
.El |
.El |
.Pp |
.Pp |
These strings are set using |
These strings are set using |
Line 168 In the rare case that a blank character is needed at t |
|
Line 176 In the rare case that a blank character is needed at t |
|
input line, it may be forced by |
input line, it may be forced by |
.Sq \e\ \e& . |
.Sq \e\ \e& . |
.Pp |
.Pp |
|
In general, space characters can be rendered as literal |
|
characters by using non-breaking space escapes or |
|
.Sx Quotation . |
|
.Pp |
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. |
If the first character of a text 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 Quotation |
.Ss Quotation |
Macro arguments may be quoted with double-quotes; in this case, |
Macro arguments may be quoted with double-quotes to so that the |
whitespace within the quotes is retained as part of the argument. |
enclosed text is one literal term. |
For example, |
Quoted text, even if whitespace or if it would cause a macro invocation |
|
when unquoted, is considered literal text. |
.Pp |
.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 |
Examples: |
by preceding them with a backslash |
.Bl -tag -width Ds -offset indent -compact |
.Pq Sq \e\~ , |
.It Li .Fn strlen \(dqconst char *s\(dq |
but quoting is usually better for clarity. |
Group arguments |
.Pp |
.Qq const char *s |
Note that any quoted text, even if it would cause a macro invocation |
into one function argument. |
when unquoted, is considered literal text. |
If unspecified, |
Thus, the following produces |
.Qq const , |
.Sq Op "Fl a" : |
.Qq char , |
.Bd -literal -offset indent |
and |
\&.Op "Fl a" |
.Qq *s |
.Ed |
would be considered separate arguments. |
.Pp |
.Pq See Sx \&Fn . |
In text lines, quotes are regarded as opaque text. |
.It Li .Op \(dqFl a\(dq |
|
Consider |
|
.Qq \&Fl a |
|
as literal text instead of a flag macro. |
|
.Pq Aee Sx \&Op , \&Fl . |
|
.El |
.Ss Scaling Widths |
.Ss Scaling Widths |
Many macros support scaled widths for their arguments. |
Many macros support scaled widths for their arguments. |
The syntax for a scaled width is |
The syntax for a scaled width is |
|
|
.Pp |
.Pp |
Examples: |
Examples: |
.Bl -tag -width Ds -offset indent -compact |
.Bl -tag -width Ds -offset indent -compact |
.It \&.Bl -tag -width 2i |
.It Li \&.Bl -tag -width 2i |
two-inch tagged list indentation |
two-inch tagged list indentation |
.Pq see Sx \&Bl |
.Pq see Sx \&Bl |
.It \&.br 2v |
.It Li \&.sp 2v |
two vertical spaces |
two vertical spaces |
.Pq see Sx \&br |
.Pq see Sx \&sp |
.El |
.El |
.Ss Sentence Spacing |
.Ss Sentence Spacing |
Sentences should terminate at the end of an input line. |
Sentences should terminate at the end of an input line. |
Line 324 file for a utility |
|
Line 331 file for a utility |
|
\&.Sh NAME |
\&.Sh NAME |
\&.Nm progname |
\&.Nm progname |
\&.Nd one line about what it does |
\&.Nd one line about what it does |
\&.\e\*q .Sh LIBRARY |
\&.\e\(dq .Sh LIBRARY |
\&.\e\*q For sections 2, 3, & 9 only. |
\&.\e\(dq For sections 2, 3, & 9 only. |
\&.\e\*q Not used in OpenBSD. |
\&.\e\(dq Not used in OpenBSD. |
\&.Sh SYNOPSIS |
\&.Sh SYNOPSIS |
\&.Nm progname |
\&.Nm progname |
\&.Op Fl options |
\&.Op Fl options |
Line 335 file for a utility |
|
Line 342 file for a utility |
|
The |
The |
\&.Nm |
\&.Nm |
utility processes files ... |
utility processes files ... |
\&.\e\*q .Sh IMPLEMENTATION NOTES |
\&.\e\(dq .Sh IMPLEMENTATION NOTES |
\&.\e\*q Not used in OpenBSD. |
\&.\e\(dq Not used in OpenBSD. |
\&.\e\*q .Sh RETURN VALUES |
\&.\e\(dq .Sh RETURN VALUES |
\&.\e\*q For sections 2, 3, & 9 only. |
\&.\e\(dq For sections 2, 3, & 9 only. |
\&.\e\*q .Sh ENVIRONMENT |
\&.\e\(dq .Sh ENVIRONMENT |
\&.\e\*q For sections 1, 6, 7, & 8 only. |
\&.\e\(dq For sections 1, 6, 7, & 8 only. |
\&.\e\*q .Sh FILES |
\&.\e\(dq .Sh FILES |
\&.\e\*q .Sh EXIT STATUS |
\&.\e\(dq .Sh EXIT STATUS |
\&.\e\*q For sections 1, 6, & 8 only. |
\&.\e\(dq For sections 1, 6, & 8 only. |
\&.\e\*q .Sh EXAMPLES |
\&.\e\(dq .Sh EXAMPLES |
\&.\e\*q .Sh DIAGNOSTICS |
\&.\e\(dq .Sh DIAGNOSTICS |
\&.\e\*q For sections 1, 4, 6, 7, & 8 only. |
\&.\e\(dq For sections 1, 4, 6, 7, & 8 only. |
\&.\e\*q .Sh ERRORS |
\&.\e\(dq .Sh ERRORS |
\&.\e\*q For sections 2, 3, & 9 only. |
\&.\e\(dq For sections 2, 3, & 9 only. |
\&.\e\*q .Sh SEE ALSO |
\&.\e\(dq .Sh SEE ALSO |
\&.\e\*q .Xr foobar 1 |
\&.\e\(dq .Xr foobar 1 |
\&.\e\*q .Sh STANDARDS |
\&.\e\(dq .Sh STANDARDS |
\&.\e\*q .Sh HISTORY |
\&.\e\(dq .Sh HISTORY |
\&.\e\*q .Sh AUTHORS |
\&.\e\(dq .Sh AUTHORS |
\&.\e\*q .Sh CAVEATS |
\&.\e\(dq .Sh CAVEATS |
\&.\e\*q .Sh BUGS |
\&.\e\(dq .Sh BUGS |
\&.\e\*q .Sh SECURITY CONSIDERATIONS |
\&.\e\(dq .Sh SECURITY CONSIDERATIONS |
\&.\e\*q Not used in OpenBSD. |
\&.\e\(dq Not used in OpenBSD. |
.Ed |
.Ed |
.Pp |
.Pp |
The sections in an |
The sections in an |
Line 438 macros should follow C header-file conventions. |
|
Line 445 macros should follow C header-file conventions. |
|
.Pp |
.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 \(dqit* at isa? port 0x2e\(dq |
\&.Cd \*qit* at isa? port 0x4e\*q |
\&.Cd \(dqit* at isa? port 0x4e\(dq |
.Ed |
.Ed |
.Pp |
.Pp |
Manuals not in these sections generally don't need a |
Manuals not in these sections generally don't need a |
Line 2095 section, this macro starts a new output line, |
|
Line 2102 section, this macro starts a new output line, |
|
and a blank line is automatically inserted between function definitions. |
and a blank line is automatically inserted between function definitions. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q |
.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq |
.Dl \&.Fn funcname \*qint arg0\*q |
.Dl \&.Fn funcname \(dqint arg0\(dq |
.Dl \&.Fn funcname arg0 |
.Dl \&.Fn funcname arg0 |
.Pp |
.Pp |
.Bd -literal -offset indent -compact |
.Bd -literal -offset indent -compact |
Line 2361 Its syntax is as follows: |
|
Line 2368 Its syntax is as follows: |
|
.D1 Pf \. Sx \&Lk Ar uri Op Ar 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 \(dqThe BSD.lv Project\(dq |
.Dl \&.Lk http://bsd.lv |
.Dl \&.Lk http://bsd.lv |
.Pp |
.Pp |
See also |
See also |
Line 3261 utility written by Kristaps Dzonsons appeared in |
|
Line 3268 utility written by Kristaps Dzonsons appeared in |
|
The |
The |
.Nm |
.Nm |
reference was written by |
reference was written by |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
.An Kristaps Dzonsons , |
|
.Mt kristaps@bsd.lv . |