version 1.105, 2011/08/18 08:58:43 |
version 1.109, 2011/09/06 17:56:00 |
Line 39 language, instead. |
|
Line 39 language, instead. |
|
.Pp |
.Pp |
A |
A |
.Nm |
.Nm |
document follows simple rules: lines beginning with the control |
document follows simple rules: lines beginning with the control |
character |
character |
.Sq \&. |
.Sq \&. |
are parsed for macros. |
are parsed for macros. |
Other lines are interpreted within the scope of |
Lines not beginning with the control character are |
prior macros: |
interpreted within the scope of prior macros: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.SH Macro lines change control state. |
\&.SH Macro lines change control state. |
Other lines are interpreted within the current state. |
Text lines are interpreted within the current state. |
.Ed |
.Ed |
.Sh LANGUAGE SYNTAX |
.Sh LANGUAGE SYNTAX |
.Nm |
.Nm |
|
|
.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 |
Line 75 stripped from input. |
|
Line 75 stripped from input. |
|
.Pp |
.Pp |
Examples: |
Examples: |
.Bd -literal -offset indent -compact |
.Bd -literal -offset indent -compact |
\&.\e\*q This is a comment line. |
\&.\e\(dq This is a comment line. |
\&.\e\*q The next line is ignored: |
\&.\e\(dq The next line is ignored: |
\&. |
\&. |
\&.Em Emphasis \e\*q This is also a comment. |
\&.Em Emphasis \e\(dq This is also a comment. |
.Ed |
.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 |
Line 96 or a single one character sequence. |
|
Line 96 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 |
Line 109 for a complete list. |
|
Line 109 for a complete list. |
|
Terms may be text-decorated using the |
Terms may be text-decorated using the |
.Sq \ef |
.Sq \ef |
escape followed by an indicator: B (bold), I (italic), R (regular), or P |
escape followed by an indicator: B (bold), I (italic), R (regular), or P |
(revert to previous mode): |
(revert to previous mode). |
A numerical representation 3, 2, or 1 (bold, italic, and regular, |
A numerical representation 3, 2, or 1 (bold, italic, and regular, |
respectively) may be used instead. |
respectively) may be used instead. |
A text decoration is only valid, if specified in free-form text, until |
A text decoration is only valid, if specified in free-form text, until |
Line 125 attribute is forgotten when entering or exiting a macr |
|
Line 125 attribute is forgotten when entering or exiting a macr |
|
.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 |
.Ss Predefined Strings |
.Ss Predefined Strings |
Predefined strings, like |
Predefined strings, like |
|
|
.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 170 In the rare case that a blank character is needed at t |
|
Line 170 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 . |
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. |
|
Quoted text, even if whitespace or if it would cause a macro invocation |
|
when unquoted, is considered literal text. |
.Pp |
.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 .BR a \(dqb c\(dq d |
but quoting is usually better for clarity. |
Group arguments |
.Pp |
.Qq b c |
Note that any quoted text, even if it would cause a macro invocation |
into one un-bolded argument. |
when unquoted, is considered literal text. |
If unspecified, |
.Pp |
.Qq a |
In text lines, quotes are regarded as opaque text. |
and |
|
.Qq c |
|
will be in bold, |
|
.Qq b |
|
and |
|
.Qq d |
|
in regular font mode. |
|
Furthermore, will be preserved between |
|
.Qq b |
|
and |
|
.Qq c . |
|
.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 |
Line 294 file for a utility |
|
Line 310 file for a utility |
|
\&.TH PROGNAME 1 2009-10-10 |
\&.TH PROGNAME 1 2009-10-10 |
\&.SH NAME |
\&.SH NAME |
\efBprogname\efR \e(en a description goes here |
\efBprogname\efR \e(en a description goes here |
\&.\e\*q .SH LIBRARY |
\&.\e\(dq .SH LIBRARY |
\&.\e\*q For sections 2 & 3 only. |
\&.\e\(dq For sections 2 & 3 only. |
\&.\e\*q Not used in OpenBSD. |
\&.\e\(dq Not used in OpenBSD. |
\&.SH SYNOPSIS |
\&.SH SYNOPSIS |
\efBprogname\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\(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 .BR foo ( 1 ) |
\&.\e\(dq .BR foo ( 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 a |
The sections in a |
Line 485 The syntax is as follows: |
|
Line 501 The syntax is as follows: |
|
\&.YO \(lBbody...\(rB |
\&.YO \(lBbody...\(rB |
\(lBbody...\(rB |
\(lBbody...\(rB |
.Ed |
.Ed |
.Pp |
.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent |
.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" |
|
.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes |
.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes |
.It Sx \&AT Ta <=1 Ta current Ta \& |
.It Sx \&AT Ta <=1 Ta current Ta \& |
.It Sx \&B Ta n Ta next-line Ta \& |
.It Sx \&B Ta n Ta next-line Ta \& |
Line 553 No closure refers to an explicit block closing macro. |
|
Line 568 No closure refers to an explicit block closing macro. |
|
As a rule, block macros may not be nested; thus, calling a block macro |
As a rule, block macros may not be nested; thus, calling a block macro |
while another block macro scope is open, and the open scope is not |
while another block macro scope is open, and the open scope is not |
implicitly closed, is syntactically incorrect. |
implicitly closed, is syntactically incorrect. |
.Pp |
.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent |
.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" |
|
.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes |
.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes |
.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& |
.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& |
.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& |
.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& |
Line 957 implementations of the |
|
Line 971 implementations of the |
|
language. |
language. |
.Pp |
.Pp |
.Bl -dash -compact |
.Bl -dash -compact |
|
.It |
|
Do not depend on |
|
.Sx \&SH |
|
or |
|
.Sx \&SS |
|
to close out a literal context opened with |
|
.Sx \&nf . |
|
This behaviour may not be portable. |
.It |
.It |
In quoted literals, GNU troff allowed pair-wise double-quotes to produce |
In quoted literals, GNU troff allowed pair-wise double-quotes to produce |
a standalone double-quote in formatted output. |
a standalone double-quote in formatted output. |