version 1.99, 2011/03/07 01:35:51 |
version 1.104, 2011/08/17 22:20:14 |
|
|
\&.SH Macro lines change control state. |
\&.SH Macro lines change control state. |
Other lines are interpreted within the current state. |
Other lines are interpreted within the current state. |
.Ed |
.Ed |
.Sh INPUT ENCODING |
.Sh LANGUAGE SYNTAX |
.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. |
.Pp |
The back-space character |
Blank lines are acceptable; where found, the output will assert a |
.Sq \e |
vertical space. |
indicates the start of an escape sequence for |
.Pp |
.Sx Comments , |
If the first character of a line is a space, that line is printed |
.Sx Predefined Strings , |
with a leading newline. |
and |
|
.Sx Special Characters . |
.Ss Comments |
.Ss Comments |
Text following a |
Text following an escaped double-quote |
.Sq \e\*q , |
.Sq \e\*q , |
whether in a macro or free-form 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 with only a control character and comment escape, |
A macro line beginning with a control character and comment escape |
.Sq \&.\e\*q , |
.Sq \&.\e\*q |
is also ignored. |
is also ignored. |
Macro lines with only a control character and optionally whitespace are |
Furthermore, |
|
macro lines with only a control character and optional trailing |
|
whitespace are |
stripped from input. |
stripped from input. |
|
.Pp |
|
Examples: |
|
.Bd -literal -offset indent -compact |
|
\&.\e\*q This is a comment line. |
|
\&.\e\*q The next line is ignored: |
|
\&. |
|
\&.Em Emphasis \e\*q This is also a comment. |
|
.Ed |
.Ss Special Characters |
.Ss Special Characters |
Special characters may occur in both macro and free-form lines. |
Special characters are used to encode special glyphs and are rendered |
|
differently across output media. |
|
They may occur in both macro and text lines. |
Sequences begin with the escape character |
Sequences begin with the escape character |
.Sq \e |
.Sq \e |
followed by either an open-parenthesis |
followed by either an open-parenthesis |
Line 79 for two-character sequences; an open-bracket |
|
Line 92 for two-character sequences; an open-bracket |
|
.Sq \&[ |
.Sq \&[ |
for n-character sequences (terminated at a close-bracket |
for n-character sequences (terminated at a close-bracket |
.Sq \&] ) ; |
.Sq \&] ) ; |
or a single one-character sequence. |
or a single one character sequence. |
|
.Pp |
|
Examples: |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \e(em |
|
em dash |
|
.It \ee |
|
backslash |
|
.El |
|
.Pp |
See |
See |
.Xr mandoc_char 7 |
.Xr mandoc_char 7 |
for a complete list. |
for a complete list. |
Examples include |
|
.Sq \e(em |
|
.Pq em-dash |
|
and |
|
.Sq \ee |
|
.Pq back-slash . |
|
.Ss Text Decoration |
.Ss Text Decoration |
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 (Roman), or P |
escape followed by an indicator: B (bold), I (italic), R (regular), or P |
(revert to previous mode): |
(revert to previous mode): |
.Pp |
A numerical representation 3, 2, or 1 (bold, italic, and regular, |
.D1 \efBbold\efR \efIitalic\efP |
|
.Pp |
|
A numerical representation 3, 2, or 1 (bold, italic, and Roman, |
|
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 |
the next macro invocation; if specified within a macro, it's only valid |
the next macro invocation; if specified within a macro, it's only valid |
Line 109 open and close a font scope with each argument. |
|
Line 122 open and close a font scope with each argument. |
|
The |
The |
.Sq \ef |
.Sq \ef |
attribute is forgotten when entering or exiting a macro block. |
attribute is forgotten when entering or exiting a macro block. |
|
.Pp |
|
Examples: |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \efBbold\efR |
|
write in bold, then switch to regular |
|
.It \efIitalic\efP |
|
write in italic, then return to previous |
|
.El |
|
.Ss Predefined Strings |
|
Predefined strings, like |
|
.Sx Special Characters , |
|
mark special output glyphs. |
|
Predefined strings are escaped with the slash-asterisk, |
|
.Sq \e* : |
|
single-character |
|
.Sq \e*X , |
|
two-character |
|
.Sq \e*(XX , |
|
and N-character |
|
.Sq \e*[N] . |
|
.Pp |
|
Examples: |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \e*(Am |
|
ampersand |
|
.It \e*(Ba |
|
vertical bar |
|
.El |
|
.Pp |
|
These strings are set using |
|
.Xr roff 7 , |
|
although |
|
.Nm |
|
consists of several pre-set escapes listed in |
|
.Xr mandoc_char 7 . |
.Ss Whitespace |
.Ss Whitespace |
Whitespace consists of the space character. |
Whitespace consists of the space character. |
In free-form lines, whitespace is preserved within a line; unescaped |
In text lines, whitespace is preserved within a line. |
trailing spaces are stripped from input (unless in a literal context). |
|
Blank free-form lines, which may include spaces, are permitted and |
|
rendered as an empty line. |
|
.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 Scaling Widths |
|
Many macros support scaled widths for their arguments, such as |
|
stipulating a two-inch paragraph indentation with the following: |
|
.Bd -literal -offset indent |
|
\&.HP 2i |
|
.Ed |
|
.Pp |
.Pp |
The syntax for scaled widths is |
Unescaped trailing spaces are stripped from text line input unless in a |
.Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? , |
literal context. |
|
In general, trailing whitespace on any input line is discouraged for |
|
reasons of 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 |
|
If the first character of a text line is a space, that line is printed |
|
with a leading newline. |
|
.Ss Quotation |
|
Macro arguments may be quoted with double-quotes; in this case, |
|
whitespace within the quotes is retained as part of the argument. |
|
.Pp |
|
A quoted argument begins with a double-quote preceded by whitespace. |
|
The next double-quote not pairwise adjacent to another double-quote |
|
terminates the literal, regardless of surrounding whitespace. |
|
.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 |
|
when unquoted, is considered literal text. |
|
.Pp |
|
In text lines, quotes are regarded as opaque text. |
|
.Ss Scaling Widths |
|
Many macros support scaled widths for their arguments. |
|
The syntax for a scaled width is |
|
.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , |
where a decimal must be preceded or proceeded by at least one digit. |
where a decimal must be preceded or proceeded by at least one digit. |
Negative numbers, while accepted, are truncated to zero. |
Negative numbers, while accepted, are truncated to zero. |
|
.Pp |
The following scaling units are accepted: |
The following scaling units are accepted: |
.Pp |
.Pp |
.Bl -tag -width Ds -offset indent -compact |
.Bl -tag -width Ds -offset indent -compact |
Line 168 Using anything other than |
|
Line 235 Using anything other than |
|
or |
or |
.Sq v |
.Sq v |
is necessarily non-portable across output media. |
is necessarily non-portable across output media. |
|
See |
|
.Sx COMPATIBILITY . |
.Pp |
.Pp |
If a scaling unit is not provided, the numerical value is interpreted |
If a scaling unit is not provided, the numerical value is interpreted |
under the default rules of |
under the default rules of |
Line 175 under the default rules of |
|
Line 244 under the default rules of |
|
for vertical spaces and |
for vertical spaces and |
.Sq u |
.Sq u |
for horizontal ones. |
for horizontal ones. |
.Em Note : |
.Pp |
this differs from |
Examples: |
.Xr mdoc 7 , |
.Bl -tag -width Ds -offset indent -compact |
which, if a unit is not provided, will instead interpret the string as |
.It \&.HP 2i |
literal text. |
two-inch tagged list indentation |
|
.Pq see Sx \&HP |
|
.It \&.sp 2v |
|
two vertical spaces |
|
.Pq see Sx \&sp |
|
.El |
.Ss Sentence Spacing |
.Ss Sentence Spacing |
When composing a manual, make sure that sentences end at the end of |
Sentences should terminate at the end of an input line. |
a line. |
By doing this, a formatter will be able to apply the proper amount of |
By doing so, front-ends will be able to apply the proper amount of |
|
spacing after the end of sentence (unescaped) period, exclamation mark, |
spacing after the end of sentence (unescaped) period, exclamation mark, |
or question mark followed by zero or more non-sentence closing |
or question mark followed by zero or more non-sentence closing |
delimiters |
delimiters |
|
|
.Sq \&' , |
.Sq \&' , |
.Sq \&" |
.Sq \&" |
.Pc . |
.Pc . |
|
.Pp |
|
Examples: |
|
.Bd -literal -offset indent -compact |
|
Do not end sentences mid-line like this. Instead, |
|
end a sentence like this. |
|
A new sentence gets a new line. |
|
.Ed |
.Sh MANUAL STRUCTURE |
.Sh MANUAL STRUCTURE |
Each |
Each |
.Nm |
.Nm |
Line 205 appears as the first macro. |
|
Line 285 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 .SH LIBRARY |
\&.\e\*q .SH LIBRARY |
\&.\e\*q For sections 2 & 3 only. |
\&.\e\*q For sections 2 & 3 only. |
\&.\e\*q Not used in OpenBSD. |
\&.\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 |
|
|
.Ss \&RE |
.Ss \&RE |
Explicitly close out the scope of a prior |
Explicitly close out the scope of a prior |
.Sx \&RS . |
.Sx \&RS . |
|
The default left margin is restored to the state of the original |
|
.Sx \&RS |
|
invocation. |
.Ss \&RI |
.Ss \&RI |
Text is rendered alternately in roman (the default font) and italics. |
Text is rendered alternately in roman (the default font) and italics. |
Whitespace between arguments is omitted in output. |
Whitespace between arguments is omitted in output. |
|
|
and |
and |
.Sx \&IR . |
.Sx \&IR . |
.Ss \&RS |
.Ss \&RS |
Begin a part setting the left margin. |
Temporarily reset the default left margin. |
The left margin controls the offset, following an initial indentation, |
|
to un-indented text such as that of |
|
.Sx \&PP . |
|
This has the following syntax: |
This has the following syntax: |
.Bd -filled -offset indent |
.Bd -filled -offset indent |
.Pf \. Sx \&Rs |
.Pf \. Sx \&RS |
.Op Cm width |
.Op Cm width |
.Ed |
.Ed |
.Pp |
.Pp |
|
|
argument must conform to |
argument must conform to |
.Sx Scaling Widths . |
.Sx Scaling Widths . |
If not specified, the saved or default width is used. |
If not specified, the saved or default width is used. |
|
.Pp |
|
See also |
|
.Sx \&RE . |
.Ss \&SB |
.Ss \&SB |
Text is rendered in small size (one point smaller than the default font) |
Text is rendered in small size (one point smaller than the default font) |
bold face. |
bold face. |
Line 841 Begin literal mode: all subsequent free-form lines hav |
|
Line 928 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 . |
|
Literal mode is implicitly ended by |
|
.Sx \&SH |
|
or |
|
.Sx \&SS . |
.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 |