version 1.134, 2010/07/15 23:50:15 |
version 1.138, 2010/07/19 15:28:11 |
|
|
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. |
|
|
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 |
.Bd -literal -offset indent |
|
|
.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 |
|
|
.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 |
.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 1445 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 |
|
|
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 |
.D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot |
|
|
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 |
|
.Ss \&Qq , |
|
.Ss \&Sq , |
|
and |
.Sx \&Do . |
.Sx \&Do . |
.Ss \&Dt |
|
Document title. |
Document title. |
This is the mandatory second macro of any |
This is the mandatory second macro of any |
.Nm |
.Nm |
Line 1536 Its arguments are as follows: |
|
Line 1533 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 1714 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 |
Line 1934 is preferred for displaying code; the |
|
Line 1937 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 2015 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. |
|
.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 2160 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 2203 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 2280 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 2305 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 2330 before the rendered output, else the block continues o |
|
Line 2375 before the rendered output, else the block continues o |
|
line. |
line. |
.Ss \&Rv |
.Ss \&Rv |
.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 2406 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 |
.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. |
Line 2450 Heirloom troff, the other significant troff implementa |
|
Line 2558 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 2608 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 |
|
.\" . |
|