version 1.199, 2011/08/16 23:44:58 |
version 1.200, 2011/08/17 20:34:53 |
Line 30 language is used to format |
|
Line 30 language is used to format |
|
manuals. |
manuals. |
This reference document describes its syntax, structure, and |
This reference document describes its syntax, structure, and |
usage. |
usage. |
The reference implementation is |
The reference implementation for |
|
.Nm |
|
formatting is |
.Xr mandoc 1 ; |
.Xr mandoc 1 ; |
the |
the |
.Sx COMPATIBILITY |
.Sx COMPATIBILITY |
section describes compatibility with other troff \-mdoc implementations. |
section describes compatibility with other implementations. |
.Pp |
.Pp |
An |
An |
.Nm |
.Nm |
Line 42 document follows simple rules: lines beginning with th |
|
Line 44 document follows simple rules: lines beginning with th |
|
character |
character |
.Sq \&. |
.Sq \&. |
are parsed for macros. |
are parsed for macros. |
Text lines, those not beginning with the control character, are |
Lines not beginning with the control character are |
interpreted within the scope of 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. |
Line 52 Text lines are interpreted within the current state. |
|
Line 54 Text lines are interpreted within the current state. |
|
.Nm |
.Nm |
documents may contain only graphable 7-bit ASCII characters, the space |
documents may contain only graphable 7-bit ASCII characters, the space |
character, and, in certain circumstances, the tab character. |
character, and, in certain circumstances, the tab character. |
.Pp |
The back-space character |
If the first character of a text line is a space, that line is printed |
.Sq \e |
with a leading newline. |
indicates the start of an escape sequence for |
|
.Sx Comments , |
|
.Sx Predefined Strings , |
|
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 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 optional whitespace are |
Furthermore, |
|
macro lines with only a control character and optional trailing |
|
whitespace are |
stripped from input. |
stripped from input. |
.Ss Special Characters |
.Ss Special Characters |
Special characters may occur in both macro and text 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 76 for two-character sequences; an open-bracket |
|
Line 86 for two-character sequences; an open-bracket |
|
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, |
.Dl \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. |
If a macro opens a font scope after calling |
If a macro opens a font scope after calling |
.Sq \ef , |
.Sq \ef , |
Line 105 mode will be restored upon exiting the |
|
Line 115 mode will be restored upon exiting the |
|
.Sx \&Bf |
.Sx \&Bf |
scope. |
scope. |
.Pp |
.Pp |
Note this form is |
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 |
|
.Pp |
|
Text decoration is |
.Em not |
.Em not |
recommended for |
recommended for |
.Nm , |
.Nm , |
which encourages semantic annotation. |
which encourages semantic annotation. |
.Ss Predefined Strings |
.Ss Predefined Strings |
Historically, |
Predefined strings, like |
troff |
|
also defined a set of package-specific |
|
.Dq predefined strings , |
|
which, like |
|
.Sx Special Characters , |
.Sx Special Characters , |
mark special output characters and strings by way of input codes. |
mark special output glyphs. |
Predefined strings are escaped with the slash-asterisk, |
Predefined strings are escaped with the slash-asterisk, |
.Sq \e* : |
.Sq \e* : |
single-character |
single-character |
|
|
.Sq \e*(XX , |
.Sq \e*(XX , |
and N-character |
and N-character |
.Sq \e*[N] . |
.Sq \e*[N] . |
See |
.Pp |
.Xr mandoc_char 7 |
Examples: |
for a complete list. |
.Bl -tag -width Ds -offset indent -compact |
Examples include |
.It \e*(Am |
.Sq \e*(Am |
ampersand |
.Pq ampersand |
.It \e*(Ba |
and |
vertical bar |
.Sq \e*(Ba |
.El |
.Pq vertical bar . |
.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 text 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). |
In macro lines, whitespace delimits arguments and is discarded. |
Blank text lines, which may include whitespace, are only permitted |
|
within literal contexts. |
|
.Pp |
.Pp |
In general, trailing whitespace on input lines is discouraged |
Unescaped trailing spaces are stripped from text line input unless in a |
for reasons of clarity and portability. |
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 |
In the rare case that a blank character is needed at the end of an |
input line, it may be forced by |
input line, it may be forced by |
.Sq \e\ \e& . |
.Sq \e\ \e& . |
.Pp |
.Pp |
In macro lines, whitespace delimits arguments and is discarded. |
Blank text lines, which may include whitespace, are only permitted |
|
within literal contexts. |
|
If the first character of a text line is a space, that line is printed |
|
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; in this case, |
whitespace within the quotes is retained as part of the argument. |
whitespace within the quotes is retained as part of the argument. |
Line 184 Thus, the following produces |
|
Line 207 Thus, the following produces |
|
.Pp |
.Pp |
In text lines, quotes are regarded as opaque text. |
In text lines, quotes are regarded as opaque text. |
.Ss Scaling Widths |
.Ss Scaling Widths |
Many macros support scaled widths for their arguments, such as |
Many macros support scaled widths for their arguments. |
stipulating a two-inch list indentation with the following: |
The syntax for a scaled width is |
.Bd -literal -offset indent |
|
\&.Bl -tag -width 2i |
|
.Ed |
|
.Pp |
|
The syntax for scaled widths is |
|
.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , |
.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 |
|
|
is necessarily non-portable across output media. |
is necessarily non-portable across output media. |
See |
See |
.Sx COMPATIBILITY . |
.Sx COMPATIBILITY . |
|
.Pp |
|
Examples: |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \&.Bl -tag -width 2i |
|
two-inch tagged list indentation |
|
.Pq see Sx \&Bl |
|
.It \&.br 2v |
|
two vertical spaces |
|
.Pq see Sx \&br |
|
.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 |
|
|
.Pp |
.Pp |
The proper spacing is also intelligently preserved if a sentence ends at |
The proper spacing is also intelligently preserved if a sentence ends at |
the boundary of a macro line. |
the boundary of a macro line. |
For example: |
|
.Pp |
.Pp |
.Dl \&.Xr mandoc 1 \&. |
Examples: |
.Dl \&.Fl T \&Ns \&Cm ascii \&. |
.Bd -literal -offset indent -compact |
|
Do not end sentences mid-line like this. Instead, |
|
end a sentence like this. |
|
A macro would end like this: |
|
\&.Xr mandoc 1 \&. |
|
.Ed |
.Sh MANUAL STRUCTURE |
.Sh MANUAL STRUCTURE |
A well-formed |
A well-formed |
.Nm |
.Nm |