version 1.134, 2010/07/15 23:50:15 |
version 1.140, 2010/07/19 21:59:48 |
|
|
language is used to format |
language is used to format |
.Bx |
.Bx |
.Ux |
.Ux |
manuals. In this reference document, we describe its syntax, structure, |
manuals. |
and usage. Our reference implementation is mandoc; the |
In this reference document, we describe its syntax, structure, and |
|
usage. |
|
Our reference implementation is mandoc; the |
.Sx COMPATIBILITY |
.Sx COMPATIBILITY |
section describes compatibility with other troff \-mdoc implementations. |
section describes compatibility with other troff \-mdoc implementations. |
.Pp |
.Pp |
|
|
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. Other lines are interpreted within the scope of |
are parsed for macros. |
|
Other lines are interpreted within the scope of |
prior macros: |
prior macros: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Sh Macro lines change control state. |
\&.Sh Macro lines change control state. |
Line 46 Other lines are interpreted within the current state. |
|
Line 49 Other lines are interpreted within the current state. |
|
.Sh LANGUAGE SYNTAX |
.Sh LANGUAGE SYNTAX |
.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. All |
character, and, in certain circumstances, the tab character. |
manuals must have |
All manuals must have |
.Ux |
.Ux |
line terminators. |
line terminators. |
.Ss Comments |
.Ss Comments |
Text following a |
Text following a |
.Sq \e" , |
.Sq \e\*q , |
whether in a macro or free-form text line, is ignored to the end of |
whether in a macro or free-form text line, is ignored to the end of |
line. A macro line with only a control character and comment escape, |
line. |
.Sq \&.\e" , |
A macro line with only a control character and comment escape, |
is also ignored. Macro lines with only a control character and optionally |
.Sq \&.\e\*q , |
whitespace are stripped from input. |
is also ignored. |
|
Macro lines with only a control character and optionally whitespace are |
|
stripped from input. |
.Ss Reserved Characters |
.Ss Reserved Characters |
Within a macro line, the following characters are reserved: |
Within a macro line, the following characters are reserved: |
.Pp |
.Pp |
|
|
is specified outside of any font scope, such as in unenclosed, free-form |
is specified outside of any font scope, such as in unenclosed, free-form |
text, it will affect the remainder of the document. |
text, it will affect the remainder of the document. |
.Pp |
.Pp |
Text may also be sized with the |
Note this form is |
.Sq \es |
|
escape, whose syntax is one of |
|
.Sq \es+-n |
|
for one-digit numerals; |
|
.Sq \es(+-nn |
|
or |
|
.Sq \es+-(nn |
|
for two-digit numerals; and |
|
.Sq \es[+-N] , |
|
.Sq \es+-[N] , |
|
.Sq \es'+-N' , |
|
or |
|
.Sq \es+-'N' |
|
for arbitrary-digit numerals: |
|
.Pp |
|
.D1 \es+1bigger\es-1 |
|
.D1 \es[+10]much bigger\es[-10] |
|
.D1 \es+(10much bigger\es-(10 |
|
.D1 \es+'100'much much bigger\es-'100' |
|
.Pp |
|
Note these forms are |
|
.Em not |
.Em not |
recommended for |
recommended for |
.Nm , |
.Nm , |
Line 466 section, particularly |
|
Line 450 section, particularly |
|
.Sx \&Vt , |
.Sx \&Vt , |
and |
and |
.Sx \&Ft . |
.Sx \&Ft . |
All of these macros are output on their own line. If two such |
All of these macros are output on their own line. |
dissimilar macros are pair-wise invoked (except for |
If two such dissimilar macros are pair-wise invoked (except for |
.Sx \&Ft |
.Sx \&Ft |
before |
before |
.Sx \&Fo |
.Sx \&Fo |
Line 879 For the scoping of individual macros, see |
|
Line 863 For the scoping of individual macros, see |
|
.Ss \&%A |
.Ss \&%A |
Author name of an |
Author name of an |
.Sx \&Rs |
.Sx \&Rs |
block. Multiple authors should each be accorded their own |
block. |
|
Multiple authors should each be accorded their own |
.Sx \%%A |
.Sx \%%A |
line. Author names should be ordered with full or abbreviated |
line. |
forename(s) first, then full surname. |
Author names should be ordered with full or abbreviated forename(s) |
|
first, then full surname. |
.Ss \&%B |
.Ss \&%B |
Book title of an |
Book title of an |
.Sx \&Rs |
.Sx \&Rs |
block. This macro may also be used in a non-bibliographic context when |
block. |
|
This macro may also be used in a non-bibliographic context when |
referring to book titles. |
referring to book titles. |
.Ss \&%C |
.Ss \&%C |
Publication city or location of an |
Publication city or location of an |
Line 899 this macro is not implemented in |
|
Line 886 this macro is not implemented in |
|
.Ss \&%D |
.Ss \&%D |
Publication date of an |
Publication date of an |
.Sx \&Rs |
.Sx \&Rs |
block. This should follow the reduced or canonical form syntax |
block. |
described in |
This should follow the reduced or canonical form syntax described in |
.Sx Dates . |
.Sx Dates . |
.Ss \&%I |
.Ss \&%I |
Publisher or issuer name of an |
Publisher or issuer name of an |
|
|
.Ss \&%Q |
.Ss \&%Q |
Institutional author (school, government, etc.) of an |
Institutional author (school, government, etc.) of an |
.Sx \&Rs |
.Sx \&Rs |
block. Multiple institutional authors should each be accorded their own |
block. |
|
Multiple institutional authors should each be accorded their own |
.Sx \&%Q |
.Sx \&%Q |
line. |
line. |
.Ss \&%R |
.Ss \&%R |
|
|
.Ss \&%T |
.Ss \&%T |
Article title of an |
Article title of an |
.Sx \&Rs |
.Sx \&Rs |
block. This macro may also be used in a non-bibliographical context |
block. |
when referring to article titles. |
This macro may also be used in a non-bibliographical context when |
|
referring to article titles. |
.Ss \&%U |
.Ss \&%U |
URI of reference document. |
URI of reference document. |
.Ss \&%V |
.Ss \&%V |
|
|
.Ss \&Ac |
.Ss \&Ac |
Closes an |
Closes an |
.Sx \&Ao |
.Sx \&Ao |
block. Does not have any tail arguments. |
block. |
|
Does not have any tail arguments. |
.Ss \&Ad |
.Ss \&Ad |
Address construct: usually in the context of an computational address in |
Address construct: usually in the context of an computational address in |
memory, not a physical (post) address. |
memory, not a physical (post) address. |
|
|
Author name. |
Author name. |
This macro may alternatively accepts the following arguments, although |
This macro may alternatively accepts the following arguments, although |
these may not be specified along with a parameter: |
these may not be specified along with a parameter: |
.Bl -tag -width 12n -offset indent |
.Pp |
|
.Bl -tag -width "-nosplitX" -offset indent -compact |
.It Fl split |
.It Fl split |
Renders a line break before each author listing. |
Renders a line break before each author listing. |
.It Fl nosplit |
.It Fl nosplit |
|
|
.Fl split . |
.Fl split . |
.El |
.El |
.Pp |
.Pp |
In the AUTHORS section, the default is not to split the first author |
In the |
|
.Em AUTHORS |
|
section, the default is not to split the first author |
listing, but all subsequent author listings, whether or not they're |
listing, but all subsequent author listings, whether or not they're |
interspersed by other macros or text, are split. |
interspersed by other macros or text, are split. |
Thus, specifying |
Thus, specifying |
.Fl split |
.Fl split |
will cause the first listing also to be split. |
will cause the first listing also to be split. |
If not in the AUTHORS section, the default is not to split. |
If not in the |
|
.Em AUTHORS |
|
section, the default is not to split. |
.Pp |
.Pp |
Examples: |
Examples: |
.D1 \&.An -nosplit |
.D1 \&.An -nosplit |
|
|
.Fl split |
.Fl split |
or |
or |
.Fl nosplit |
.Fl nosplit |
are re-set when entering the AUTHORS section, so if one specifies |
are re-set when entering the |
|
.Em AUTHORS |
|
section, so if one specifies |
.Sx \&An Fl nosplit |
.Sx \&An Fl nosplit |
in the general document body, it must be re-specified in the AUTHORS |
in the general document body, it must be re-specified in the |
|
.Em AUTHORS |
section. |
section. |
.Ss \&Ao |
.Ss \&Ao |
Begins a block enclosed by angled brackets. |
Begins a block enclosed by angled brackets. |
|
|
See also |
See also |
.Sx \&Aq . |
.Sx \&Aq . |
.Ss \&Ap |
.Ss \&Ap |
Inserts an apostrophe without any surrounding white-space. |
Inserts an apostrophe without any surrounding whitespace. |
This is generally used as a grammatical device when referring to the verb |
This is generally used as a grammatical device when referring to the verb |
form of a function: |
form of a function. |
.Bd -literal -offset indent |
.Pp |
\&.Fn execve Ap d |
Examples: |
.Ed |
.D1 \&.Fn execve \&Ap d |
.Ss \&Aq |
.Ss \&Aq |
Encloses its arguments in angled brackets. |
Encloses its arguments in angled brackets. |
.Pp |
.Pp |
|
|
.Ss \&At |
.Ss \&At |
Formats an AT&T version. |
Formats an AT&T version. |
Accepts at most one parameter: |
Accepts at most one parameter: |
.Bl -tag -width 12n -offset indent |
.Pp |
|
.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact |
.It Cm v[1-7] | 32v |
.It Cm v[1-7] | 32v |
A version of |
A version of |
.At . |
.At . |
|
|
.Ss \&Bc |
.Ss \&Bc |
Closes a |
Closes a |
.Sx \&Bo |
.Sx \&Bo |
block. Does not have any tail arguments. |
block. |
|
Does not have any tail arguments. |
.Ss \&Bd |
.Ss \&Bd |
Begins a display block. |
Begins a display block. |
Its syntax is as follows: |
Its syntax is as follows: |
|
|
.Fl width |
.Fl width |
argument is ignored. |
argument is ignored. |
.It Fl tag |
.It Fl tag |
A list offset by list entry heads. List entry bodies are positioned |
A list offset by list entry heads. |
after the head as specified by the |
List entry bodies are positioned after the head as specified by the |
.Fl width |
.Fl width |
argument. |
argument. |
.El |
.El |
Line 1323 Begins a block enclosed by square brackets. |
|
Line 1323 Begins a block enclosed by square brackets. |
|
Does not have any head arguments. |
Does not have any head arguments. |
.Pp |
.Pp |
Examples: |
Examples: |
.Bd -literal -offset indent |
.Bd -literal -offset indent -compact |
\&.Bo 1 , |
\&.Bo 1 , |
\&.Dv BUFSIZ \&Bc |
\&.Dv BUFSIZ \&Bc |
.Ed |
.Ed |
|
|
.Ss \&Brc |
.Ss \&Brc |
Closes a |
Closes a |
.Sx \&Bro |
.Sx \&Bro |
block. Does not have any tail arguments. |
block. |
|
Does not have any tail arguments. |
.Ss \&Bro |
.Ss \&Bro |
Begins a block enclosed by curly braces. |
Begins a block enclosed by curly braces. |
Does not have any head arguments. |
Does not have any head arguments. |
.Pp |
.Pp |
Examples: |
Examples: |
.Bd -literal -offset indent |
.Bd -literal -offset indent -compact |
\&.Bro 1 , ... , |
\&.Bro 1 , ... , |
\&.Va n \&Brc |
\&.Va n \&Brc |
.Ed |
.Ed |
|
|
.Pp |
.Pp |
.Em Remarks : |
.Em Remarks : |
this macro is commonly abused by using quoted literals to retain |
this macro is commonly abused by using quoted literals to retain |
white-space and align consecutive |
whitespace and align consecutive |
.Sx \&Cd |
.Sx \&Cd |
declarations. |
declarations. |
This practise is discouraged. |
This practise is discouraged. |
Line 1453 Its syntax is as follows: |
|
Line 1454 Its syntax is as follows: |
|
.Ss \&Dc |
.Ss \&Dc |
Closes a |
Closes a |
.Sx \&Do |
.Sx \&Do |
block. Does not have any tail arguments. |
block. |
|
Does not have any tail arguments. |
.Ss \&Dd |
.Ss \&Dd |
Document date. |
Document date. |
This is the mandatory first macro of any |
This is the mandatory first macro of any |
|
|
It is followed by a newline. |
It is followed by a newline. |
.Pp |
.Pp |
Examples: |
Examples: |
.D1 \&.Dl % mandoc mdoc.7 | less |
.D1 \&.Dl % mandoc mdoc.7 \e(ba less |
.Pp |
.Pp |
See also |
See also |
.Sx \&Bd |
.Sx \&Bd |
and |
and |
.Sx \&D1 . |
.Sx \&D1 . |
.Ss \&Do |
.Ss \&Do |
Begins a block enclosed by double quotes. Does not have any head |
Begins a block enclosed by double quotes. |
arguments. |
Does not have any head arguments. |
.Pp |
.Pp |
Examples: |
Examples: |
.D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot |
.Bd -literal -offset indent -compact |
|
\&.Do |
|
April is the cruellest month |
|
\&.Dc |
|
\e(em T.S. Eliot |
|
.Ed |
.Pp |
.Pp |
See also |
See also |
.Sx \&Dq . |
.Sx \&Dq . |
.Ss \&Dq |
.Ss \&Dq |
Encloses its arguments in double quotes. |
Encloses its arguments in |
|
.Dq typographic |
|
double-quotes. |
.Pp |
.Pp |
Examples: |
Examples: |
.Bd -literal -offset indent -compact |
.Bd -literal -offset indent -compact |
|
|
.Ed |
.Ed |
.Pp |
.Pp |
See also |
See also |
|
.Sx \&Qq , |
|
.Sx \&Sq , |
|
and |
.Sx \&Do . |
.Sx \&Do . |
.Ss \&Dt |
.Ss \&Dt |
Document title. |
Document title. |
Line 1536 Its arguments are as follows: |
|
Line 1548 Its arguments are as follows: |
|
.Bl -tag -width Ds -offset Ds |
.Bl -tag -width Ds -offset Ds |
.It Cm title |
.It Cm title |
The document's title (name), defaulting to |
The document's title (name), defaulting to |
.Qq UNKNOWN |
.Dq UNKNOWN |
if unspecified. |
if unspecified. |
It should be capitalised. |
It should be capitalised. |
.It Cm section |
.It Cm section |
|
|
.Ar paper |
.Ar paper |
.Pq paper . |
.Pq paper . |
It should correspond to the manual's filename suffix and defaults to |
It should correspond to the manual's filename suffix and defaults to |
.Qq 1 |
.Dq 1 |
if unspecified. |
if unspecified. |
.It Cm volume |
.It Cm volume |
This overrides the volume inferred from |
This overrides the volume inferred from |
Line 1717 stylistically decorating technical terms. |
|
Line 1729 stylistically decorating technical terms. |
|
Examples: |
Examples: |
.D1 \&.Em Warnings! |
.D1 \&.Em Warnings! |
.D1 \&.Em Remarks : |
.D1 \&.Em Remarks : |
|
.Pp |
|
See also |
|
.Sx \&Bf , |
|
.Sx \&Sy , |
|
and |
|
.Sx \&Li . |
.Ss \&En |
.Ss \&En |
This macro is obsolete and not implemented. |
This macro is obsolete and not implemented. |
.Ss \&Eo |
.Ss \&Eo |
|
|
.D1 \&.Ev DISPLAY |
.D1 \&.Ev DISPLAY |
.D1 \&.Ev PATH |
.D1 \&.Ev PATH |
.Ss \&Ex |
.Ss \&Ex |
Inserts text regarding a utility's exit values. |
Inserts text regarding a utility's exit value. |
This macro must have first the |
This macro must consist of the |
.Fl std |
.Fl std |
argument specified, then an optional |
argument followed by an optional |
.Ar utility . |
.Ar utility . |
If |
If |
.Ar utility |
.Ar utility |
is not provided, the document's name as stipulated in |
is not provided, the document's name as stipulated in |
.Sx \&Nm |
.Sx \&Nm |
is provided. |
is provided. |
|
.Pp |
|
See also |
|
.Sx \&Rv . |
.Ss \&Fa |
.Ss \&Fa |
Function argument. |
Function argument. |
Its syntax is as follows: |
Its syntax is as follows: |
|
|
.Sx \&Fa , |
.Sx \&Fa , |
.Sx \&Fc , |
.Sx \&Fc , |
and |
and |
|
.Sx \&Ft . |
.Ss \&Ft |
.Ss \&Ft |
A function type. |
A function type. |
Its syntax is as follows: |
Its syntax is as follows: |
Line 1934 is preferred for displaying code; the |
|
Line 1956 is preferred for displaying code; the |
|
macro is used when referring to specific instructions. |
macro is used when referring to specific instructions. |
.Ss \&In |
.Ss \&In |
An |
An |
.Qq include |
.Dq include |
file. |
file. |
In the |
In the |
.Em SYNOPSIS |
.Em SYNOPSIS |
section (only if invoked as the line macro), the first argument is |
section (only if invoked as the line macro), the first argument is |
preceded by |
preceded by |
.Qq #include , |
.Dq #include , |
the arguments is enclosed in angled braces. |
the arguments is enclosed in angled braces. |
.Pp |
.Pp |
Examples: |
Examples: |
Line 2012 are interpreted within the scope of the last phrase. |
|
Line 2034 are interpreted within the scope of the last phrase. |
|
Calling the pseudo-macro |
Calling the pseudo-macro |
.Sq \&Ta |
.Sq \&Ta |
will open a new phrase scope (this must occur on a macro line to be |
will open a new phrase scope (this must occur on a macro line to be |
interpreted as a macro). Note that the tab phrase delimiter may only be |
interpreted as a macro). |
used within the |
Note that the tab phrase delimiter may only be used within the |
.Sx \&It |
.Sx \&It |
line itself. |
line itself. |
Subsequent this, only the |
Subsequent this, only the |
|
|
Denotes text that should be in a literal font mode. |
Denotes text that should be in a literal font mode. |
Note that this is a presentation term and should not be used for |
Note that this is a presentation term and should not be used for |
stylistically decorating technical terms. |
stylistically decorating technical terms. |
|
.Pp |
|
See also |
|
.Sx \&Bf , |
|
.Sx \&Sy , |
|
and |
|
.Sx \&Em . |
.Ss \&Lk |
.Ss \&Lk |
Format a hyperlink. |
Format a hyperlink. |
Its syntax is as follows: |
Its syntax is as follows: |
|
|
Synonym for |
Synonym for |
.Sx \&Pp . |
.Sx \&Pp . |
.Ss \&Ms |
.Ss \&Ms |
|
Display a mathematical symbol. |
|
Its syntax is as follows: |
|
.Pp |
|
.D1 Pf \. Sx \&Ms Cm symbol |
|
.Pp |
|
Examples: |
|
.D1 \&.Ms sigma |
|
.D1 \&.Ms aleph |
.Ss \&Mt |
.Ss \&Mt |
Format a |
Format a |
.Qq mailto: |
.Dq mailto: |
hyperlink. |
hyperlink. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
Line 2146 macro rather than |
|
Line 2182 macro rather than |
|
to mark up the name of the manual page. |
to mark up the name of the manual page. |
.Ss \&No |
.Ss \&No |
A |
A |
.Qq noop |
.Dq noop |
macro used to terminate prior macro contexts. |
macro used to terminate prior macro contexts. |
.Pp |
.Pp |
Examples: |
Examples: |
.D1 \&.Sx \&Fl ab \&No cd \&Fl ef |
.D1 \&.Sx \&Fl ab \&No cd \&Fl ef |
.Ss \&Ns |
.Ss \&Ns |
|
Suppress a space. |
|
Following invocation, text is interpreted as free-form text until a |
|
macro is encountered. |
|
.Pp |
|
Examples: |
|
.D1 \&.Fl o \&Ns \&Ar output |
|
.Pp |
|
See also |
|
.Sx \&No |
|
and |
|
.Sx \&Sm . |
.Ss \&Nx |
.Ss \&Nx |
Format the NetBSD version provided as an argument, or a default value if |
Format the NetBSD version provided as an argument, or a default value if |
no argument is provided. |
no argument is provided. |
Line 2178 Multi-line version of |
|
Line 2225 Multi-line version of |
|
.Sx \&Op . |
.Sx \&Op . |
.Pp |
.Pp |
Examples: |
Examples: |
.Bd -literal -offset indent |
.Bd -literal -offset indent -compact |
\&.Oo |
\&.Oo |
\&.Op Fl flag Ns Ar value |
\&.Op Fl flag Ns Ar value |
\&.Oc |
\&.Oc |
Line 2255 Close parenthesised context opened by |
|
Line 2302 Close parenthesised context opened by |
|
.Sx \&Po . |
.Sx \&Po . |
.Ss \&Pf |
.Ss \&Pf |
Removes the space |
Removes the space |
.Pq Qq prefix |
.Pq Dq prefix |
between its arguments. |
between its arguments. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
Line 2280 Parenthesised enclosure. |
|
Line 2327 Parenthesised enclosure. |
|
See also |
See also |
.Sx \&Po . |
.Sx \&Po . |
.Ss \&Qc |
.Ss \&Qc |
|
Close quoted context opened by |
|
.Sx \&Qo . |
.Ss \&Ql |
.Ss \&Ql |
|
Format a single-quoted literal. |
|
See also |
|
.Sx \&Qq |
|
and |
|
.Sx \&Sq . |
.Ss \&Qo |
.Ss \&Qo |
|
Multi-line version of |
|
.Sx \&Qq . |
.Ss \&Qq |
.Ss \&Qq |
|
Encloses its arguments in |
|
.Dq typewriter |
|
double-quotes. |
|
Consider using |
|
.Sx \&Dq . |
|
.Pp |
|
See also |
|
.Sx \&Dq , |
|
.Sx \&Sq , |
|
and |
|
.Sx \&Qo . |
.Ss \&Re |
.Ss \&Re |
Closes a |
Closes a |
.Sx \&Rs |
.Sx \&Rs |
Line 2329 block is used within a SEE ALSO section, a vertical sp |
|
Line 2396 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 |
|
Inserts text regarding a function call's return value. |
|
This macro must consist of the |
|
.Fl std |
|
argument followed by an optional |
|
.Ar function . |
|
If |
|
.Ar function |
|
is not provided, the document's name as stipulated by the first |
|
.Sx \&Nm |
|
is provided. |
|
.Pp |
|
See also |
|
.Sx \&Ex . |
.Ss \&Sc |
.Ss \&Sc |
|
Close single-quoted context opened by |
|
.Sx \&So . |
.Ss \&Sh |
.Ss \&Sh |
|
Begin a new section. |
|
For a list of conventional manual sections, see |
|
.Sx MANUAL STRUCTURE . |
|
These sections should be used unless it's absolutely necessary that |
|
custom sections be used. |
|
.Pp |
|
Section names should be unique so that they may be keyed by |
|
.Sx \&Sx . |
|
.Pp |
|
See also |
|
.Sx \&Pp , |
|
.Sx \&Ss , |
|
and |
|
.Sx \&Sx . |
.Ss \&Sm |
.Ss \&Sm |
Switches the spacing mode for output generated from macros. |
Switches the spacing mode for output generated from macros. |
Its syntax is as follows: |
Its syntax is as follows: |
Line 2345 no white space is inserted between macro arguments and |
|
Line 2441 no white space is inserted between macro arguments and |
|
output generated from adjacent macros, but free-form text lines |
output generated from adjacent macros, but free-form text lines |
still get normal spacing between words and sentences. |
still get normal spacing between words and sentences. |
.Ss \&So |
.Ss \&So |
|
Multi-line version of |
|
.Sx \&Sq . |
.Ss \&Sq |
.Ss \&Sq |
|
Encloses its arguments in |
|
.Dq typewriter |
|
single-quotes. |
|
.Pp |
|
See also |
|
.Sx \&Dq , |
|
.Sx \&Qq , |
|
and |
|
.Sx \&So . |
.Ss \&Ss |
.Ss \&Ss |
|
Begin a new sub-section. |
|
Unlike with |
|
.Sx \&Sh , |
|
there's no convention for sub-sections. |
|
Conventional sections, as described in |
|
.Sx MANUAL STRUCTURE , |
|
rarely have sub-sections. |
|
.Pp |
|
Sub-section names should be unique so that they may be keyed by |
|
.Sx \&Sx . |
|
.Pp |
|
See also |
|
.Sx \&Pp , |
|
.Sx \&Sh , |
|
and |
|
.Sx \&Sx . |
.Ss \&St |
.Ss \&St |
|
Replace an abbreviation for a standard with the full form. |
|
The following standards are recognised: |
|
.Pp |
|
.Bl -tag -width "-p1003.1g-2000X" -compact |
|
.It \-p1003.1-88 |
|
.St -p1003.1-88 |
|
.It \-p1003.1-90 |
|
.St -p1003.1-90 |
|
.It \-p1003.1-96 |
|
.St -p1003.1-96 |
|
.It \-p1003.1-2001 |
|
.St -p1003.1-2001 |
|
.It \-p1003.1-2004 |
|
.St -p1003.1-2004 |
|
.It \-p1003.1-2008 |
|
.St -p1003.1-2008 |
|
.It \-p1003.1 |
|
.St -p1003.1 |
|
.It \-p1003.1b |
|
.St -p1003.1b |
|
.It \-p1003.1b-93 |
|
.St -p1003.1b-93 |
|
.It \-p1003.1c-95 |
|
.St -p1003.1c-95 |
|
.It \-p1003.1g-2000 |
|
.St -p1003.1g-2000 |
|
.It \-p1003.1i-95 |
|
.St -p1003.1i-95 |
|
.It \-p1003.2-92 |
|
.St -p1003.2-92 |
|
.It \-p1003.2a-92 |
|
.St -p1003.2a-92 |
|
.It \-p1387.2-95 |
|
.St -p1387.2-95 |
|
.It \-p1003.2 |
|
.St -p1003.2 |
|
.It \-p1387.2 |
|
.St -p1387.2 |
|
.It \-isoC |
|
.St -isoC |
|
.It \-isoC-90 |
|
.St -isoC-90 |
|
.It \-isoC-amd1 |
|
.St -isoC-amd1 |
|
.It \-isoC-tcor1 |
|
.St -isoC-tcor1 |
|
.It \-isoC-tcor2 |
|
.St -isoC-tcor2 |
|
.It \-isoC-99 |
|
.St -isoC-99 |
|
.It \-iso9945-1-90 |
|
.St -iso9945-1-90 |
|
.It \-iso9945-1-96 |
|
.St -iso9945-1-96 |
|
.It \-iso9945-2-93 |
|
.St -iso9945-2-93 |
|
.It \-ansiC |
|
.St -ansiC |
|
.It \-ansiC-89 |
|
.St -ansiC-89 |
|
.It \-ansiC-99 |
|
.St -ansiC-99 |
|
.It \-ieee754 |
|
.St -ieee754 |
|
.It \-iso8802-3 |
|
.St -iso8802-3 |
|
.It \-ieee1275-94 |
|
.St -ieee1275-94 |
|
.It \-xpg3 |
|
.St -xpg3 |
|
.It \-xpg4 |
|
.St -xpg4 |
|
.It \-xpg4.2 |
|
.St -xpg4.2 |
|
.St -xpg4.3 |
|
.It \-xbd5 |
|
.St -xbd5 |
|
.It \-xcu5 |
|
.St -xcu5 |
|
.It \-xsh5 |
|
.St -xsh5 |
|
.It \-xns5 |
|
.St -xns5 |
|
.It \-xns5.2 |
|
.St -xns5.2 |
|
.It \-xns5.2d2.0 |
|
.St -xns5.2d2.0 |
|
.It \-xcurses4.2 |
|
.St -xcurses4.2 |
|
.It \-susv2 |
|
.St -susv2 |
|
.It \-susv3 |
|
.St -susv3 |
|
.It \-svid4 |
|
.St -svid4 |
|
.El |
.Ss \&Sx |
.Ss \&Sx |
|
Reference a section or sub-section. |
|
The referenced section or sub-section name must be identical to the |
|
enclosed argument, including whitespace. |
|
.Pp |
|
Examples: |
|
.D1 \&.Sx MANUAL STRUCTURE |
.Ss \&Sy |
.Ss \&Sy |
|
Format enclosed arguments in symbolic |
|
.Pq Dq boldface . |
|
Note that this is a presentation term and should not be used for |
|
stylistically decorating technical terms. |
|
.Pp |
|
See also |
|
.Sx \&Bf , |
|
.Sx \&Li , |
|
and |
|
.Sx \&Em . |
.Ss \&Tn |
.Ss \&Tn |
|
Format a tradename. |
|
.Pp |
|
Examples: |
|
.D1 \&.Tn IBM |
.Ss \&Ud |
.Ss \&Ud |
Prints out |
Prints out |
.Dq currently under development. |
.Dq currently under development. |
|
|
.D1 \&.Xr mandoc 1 \&; |
.D1 \&.Xr mandoc 1 \&; |
.D1 \&.Xr mandoc 1 \&Ns s behaviour |
.D1 \&.Xr mandoc 1 \&Ns s behaviour |
.Ss \&br |
.Ss \&br |
|
Emits a line-break. |
|
This macro should not be used; it is implemented for compatibility with |
|
historical manuals. |
|
.Pp |
|
Consider using |
|
.Sx \&Pp |
|
in the event of natural paragraph breaks. |
.Ss \&sp |
.Ss \&sp |
|
Emits vertical space. |
|
This macro should not be used; it is implemented for compatibility with |
|
historical manuals. |
|
Its syntax is as follows: |
|
.Pp |
|
.D1 Pf \. Sx \&sp Op Cm height |
|
.Pp |
|
The |
|
.Cm height |
|
argument must be formatted as described in |
|
.Sx Scaling Widths . |
|
If unspecified, |
|
.Sx \&sp |
|
asserts a single vertical space. |
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section documents compatibility between mandoc and other other |
This section documents compatibility between mandoc and other other |
troff implementations, at this time limited to GNU troff |
troff implementations, at this time limited to GNU troff |
Line 2450 Heirloom troff, the other significant troff implementa |
|
Line 2710 Heirloom troff, the other significant troff implementa |
|
.Pp |
.Pp |
.Bl -dash -compact |
.Bl -dash -compact |
.It |
.It |
|
The \es (font size), \em (font colour), and \eM (font filling colour) |
|
font decoration escapes are all discarded in mandoc. |
|
.It |
Old groff fails to assert a newline before |
Old groff fails to assert a newline before |
.Sx \&Bd Fl ragged compact . |
.Sx \&Bd Fl ragged compact . |
.It |
.It |
Line 2497 pseudo-macro as a line macro. |
|
Line 2760 pseudo-macro as a line macro. |
|
mandoc does. |
mandoc does. |
.It |
.It |
The comment syntax |
The comment syntax |
.Sq \e." |
.Sq \e\." |
is no longer accepted. |
is no longer accepted. |
.It |
.It |
In groff, the |
In groff, the |
|
|
.Nm |
.Nm |
reference was written by |
reference was written by |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
.\" |
|
.\" XXX: this really isn't the place for these caveats. |
|
.\" . |
|
.\" . |
|
.\" .Sh CAVEATS |
|
.\" There are many ambiguous parts of mdoc. |
|
.\" . |
|
.\" .Pp |
|
.\" .Bl -dash -compact |
|
.\" .It |
|
.\" .Sq \&Fa |
|
.\" should be |
|
.\" .Sq \&Va |
|
.\" as function arguments are variables. |
|
.\" .It |
|
.\" .Sq \&Ft |
|
.\" should be |
|
.\" .Sq \&Vt |
|
.\" as function return types are still types. Furthermore, the |
|
.\" .Sq \&Ft |
|
.\" should be removed and |
|
.\" .Sq \&Fo , |
|
.\" which ostensibly follows it, should follow the same convention as |
|
.\" .Sq \&Va . |
|
.\" .It |
|
.\" .Sq \&Va |
|
.\" should formalise that only one or two arguments are acceptable: a |
|
.\" variable name and optional, preceding type. |
|
.\" .It |
|
.\" .Sq \&Fd |
|
.\" is ambiguous. It's commonly used to indicate an include file in the |
|
.\" synopsis section. |
|
.\" .Sq \&In |
|
.\" should be used, instead. |
|
.\" .It |
|
.\" Only the |
|
.\" .Sq \-literal |
|
.\" argument to |
|
.\" .Sq \&Bd |
|
.\" makes sense. The remaining ones should be removed. |
|
.\" .It |
|
.\" The |
|
.\" .Sq \&Xo |
|
.\" and |
|
.\" .Sq \&Xc |
|
.\" macros should be deprecated. |
|
.\" .It |
|
.\" The |
|
.\" .Sq \&Dt |
|
.\" macro lacks clarity. It should be absolutely clear which title will |
|
.\" render when formatting the manual page. |
|
.\" .It |
|
.\" A |
|
.\" .Sq \&Lx |
|
.\" should be provided for Linux (\(`a la |
|
.\" .Sq \&Ox , |
|
.\" .Sq \&Nx |
|
.\" etc.). |
|
.\" .It |
|
.\" There's no way to refer to references in |
|
.\" .Sq \&Rs/Re |
|
.\" blocks. |
|
.\" .It |
|
.\" The \-split and \-nosplit dictates via |
|
.\" .Sq \&An |
|
.\" are re-set when entering and leaving the AUTHORS section. |
|
.\" .El |
|
.\" . |
|