version 1.185, 2011/04/06 11:39:25 |
version 1.195, 2011/08/02 01:07:26 |
Line 65 A macro line with only a control character and comment |
|
Line 65 A macro line with only a control character and comment |
|
is also ignored. |
is also ignored. |
Macro lines with only a control character and optional whitespace are |
Macro lines with only a control character and optional whitespace are |
stripped from input. |
stripped from input. |
.Ss Reserved Terms |
|
Within a macro line, the following terms are reserved: |
|
.Pp |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \&. |
|
.Pq period |
|
.It \e. |
|
.Pq escaped period |
|
.It \&, |
|
.Pq comma |
|
.It \&: |
|
.Pq colon |
|
.It \&; |
|
.Pq semicolon |
|
.It \&( |
|
.Pq left-parenthesis |
|
.It \&) |
|
.Pq right-parenthesis |
|
.It \&[ |
|
.Pq left-bracket |
|
.It \&] |
|
.Pq right-bracket |
|
.It \&? |
|
.Pq question |
|
.It \&! |
|
.Pq exclamation |
|
.It \&| |
|
.Pq vertical bar |
|
.It \e*(Ba |
|
.Pq reserved-word vertical bar |
|
.El |
|
.Pp |
|
Use of reserved terms is described in |
|
.Sx MACRO SYNTAX . |
|
For general use in macro lines, these can be escaped with a non-breaking |
|
space |
|
.Pq Sq \e& . |
|
In text lines, these may be used as normal punctuation. |
|
.Ss Special Characters |
.Ss Special Characters |
Special characters may occur in both macro and text lines. |
Special characters may occur in both macro and text lines. |
Sequences begin with the escape character |
Sequences begin with the escape character |
Line 180 trailing spaces are stripped from input (unless in a l |
|
Line 142 trailing spaces are stripped from input (unless in a l |
|
Blank text lines, which may include whitespace, are only permitted |
Blank text lines, which may include whitespace, are only permitted |
within literal contexts. |
within literal contexts. |
.Pp |
.Pp |
|
In general, trailing whitespace on input lines is discouraged |
|
for reasons of clarity and 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 |
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 Quotation |
.Ss Quotation |
Macro arguments may be quoted with double-quotes to group |
Macro arguments may be quoted with double-quotes; in this case, |
space-delimited terms or to retain blocks of whitespace. |
whitespace within the quotes is retained as part of the argument. |
|
For example, |
|
.Pp |
|
.D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq" |
|
.Pp |
|
renders as |
|
.Sq Fn strlen "const char *s" , |
|
while |
|
.Pp |
|
.D1 Pf \. \&Fn strlen "const char *s" |
|
.Pp |
|
would produce |
|
.Sq Fn strlen const char *s . |
|
.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 |
|
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 |
Note that any quoted text, even if it would cause a macro invocation |
when unquoted, is considered literal text. |
when unquoted, is considered literal text. |
Thus, the following produces |
Thus, the following produces |
Line 298 sections, although this varies between manual sections |
|
Line 283 sections, although this varies between manual sections |
|
.Pp |
.Pp |
The following is a well-formed skeleton |
The following is a well-formed skeleton |
.Nm |
.Nm |
file: |
file for a utility |
|
.Qq progname : |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Dd $\&Mdocdate$ |
\&.Dd $\&Mdocdate$ |
\&.Dt mdoc 7 |
\&.Dt PROGNAME section |
\&.Os |
\&.Os |
\&.Sh NAME |
\&.Sh NAME |
\&.Nm foo |
\&.Nm progname |
\&.Nd a description goes here |
\&.Nd one line about what it does |
\&.\e\*q .Sh LIBRARY |
\&.\e\*q .Sh LIBRARY |
\&.\e\*q For sections 2, 3, & 9 only. |
\&.\e\*q For sections 2, 3, & 9 only. |
\&.\e\*q Not used in OpenBSD. |
\&.\e\*q Not used in OpenBSD. |
\&.Sh SYNOPSIS |
\&.Sh SYNOPSIS |
\&.Nm foo |
\&.Nm progname |
\&.Op Fl options |
\&.Op Fl options |
\&.Ar |
\&.Ar |
\&.Sh DESCRIPTION |
\&.Sh DESCRIPTION |
|
|
.Em Callable |
.Em Callable |
column indicates that the macro may also be called by passing its name |
column indicates that the macro may also be called by passing its name |
as an argument to another macro. |
as an argument to another macro. |
|
For example, |
|
.Sq \&.Op \&Fl O \&Ar file |
|
produces |
|
.Sq Op Fl O Ar file . |
|
To prevent a macro call and render the macro name literally, |
|
escape it by prepending a zero-width space, |
|
.Sq \e& . |
|
For example, |
|
.Sq \&Op \e&Fl O |
|
produces |
|
.Sq Op \&Fl O . |
If a macro is not callable but its name appears as an argument |
If a macro is not callable but its name appears as an argument |
to another macro, it is interpreted as opaque text. |
to another macro, it is interpreted as opaque text. |
For example, |
For example, |
|
|
.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc |
.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc |
.El |
.El |
.Ss Block partial-implicit |
.Ss Block partial-implicit |
Like block full-implicit, but with single-line scope closed by |
Like block full-implicit, but with single-line scope closed by the |
.Sx Reserved Terms |
end of the line. |
or end of line. |
|
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB |
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB |
.Ed |
.Ed |
|
|
.Em SYNOPSIS |
.Em SYNOPSIS |
section line, else it is |
section line, else it is |
.Sx In-line . |
.Sx In-line . |
|
.Ss Special block macro |
|
The |
|
.Sx \&Ta |
|
macro can only be used below |
|
.Sx \&It |
|
in |
|
.Sx \&Bl Fl column |
|
lists. |
|
It delimits blocks representing table cells; |
|
these blocks have bodies, but no heads. |
|
.Pp |
|
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent |
|
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope |
|
.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It |
|
.El |
.Ss In-line |
.Ss In-line |
Closed by |
Closed by the end of the line, fixed argument lengths, |
.Sx Reserved Terms , |
and/or subsequent macros. |
end of line, fixed argument lengths, and/or subsequent macros. |
|
In-line macros have only text children. |
In-line macros have only text children. |
If a number (or inequality) of arguments is |
If a number (or inequality) of arguments is |
.Pq n , |
.Pq n , |
Line 854 then the macro accepts an arbitrary number of argument |
|
Line 864 then the macro accepts an arbitrary number of argument |
|
.It Sx \&br Ta \&No Ta \&No Ta 0 |
.It Sx \&br Ta \&No Ta \&No Ta 0 |
.It Sx \&sp Ta \&No Ta \&No Ta 1 |
.It Sx \&sp Ta \&No Ta \&No Ta 1 |
.El |
.El |
|
.Ss Delimiters |
|
When a macro argument consists of one single input character |
|
considered as a delimiter, the argument gets special handling. |
|
This does not apply when delimiters appear in arguments containing |
|
more than one character. |
|
Consequently, to prevent special handling and just handle it |
|
like any other argument, a delimiter can be escaped by prepending |
|
a zero-width space |
|
.Pq Sq \e& . |
|
In text lines, delimiters never need escaping, but may be used |
|
as normal punctuation. |
|
.Pp |
|
For many macros, when the leading arguments are opening delimiters, |
|
these delimiters are put before the macro scope, |
|
and when the trailing arguments are closing delimiters, |
|
these delimiters are put after the macro scope. |
|
For example, |
|
.Pp |
|
.D1 Pf \. \&Aq "( [ word ] ) ." |
|
.Pp |
|
renders as: |
|
.Pp |
|
.D1 Aq ( [ word ] ) . |
|
.Pp |
|
Opening delimiters are: |
|
.Pp |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \&( |
|
left parenthesis |
|
.It \&[ |
|
left bracket |
|
.El |
|
.Pp |
|
Closing delimiters are: |
|
.Pp |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \&. |
|
period |
|
.It \&, |
|
comma |
|
.It \&: |
|
colon |
|
.It \&; |
|
semicolon |
|
.It \&) |
|
right parenthesis |
|
.It \&] |
|
right bracket |
|
.It \&? |
|
question mark |
|
.It \&! |
|
exclamation mark |
|
.El |
|
.Pp |
|
Note that even a period preceded by a backslash |
|
.Pq Sq \e.\& |
|
gets this special handling; use |
|
.Sq \e&. |
|
to prevent that. |
|
.Pp |
|
Many in-line macros interrupt their scope when they encounter |
|
delimiters, and resume their scope when more arguments follow that |
|
are not delimiters. |
|
For example, |
|
.Pp |
|
.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" |
|
.Pp |
|
renders as: |
|
.Pp |
|
.D1 Fl a ( b | c \*(Ba d ) e |
|
.Pp |
|
This applies to both opening and closing delimiters, |
|
and also to the middle delimiter: |
|
.Pp |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It \&| |
|
vertical bar |
|
.El |
|
.Pp |
|
As a special case, the predefined string \e*(Ba is handled and rendered |
|
in the same way as a plain |
|
.Sq \&| |
|
character. |
|
Using this predefined string is not recommended in new manuals. |
.Sh REFERENCE |
.Sh REFERENCE |
This section is a canonical reference of all macros, arranged |
This section is a canonical reference of all macros, arranged |
alphabetically. |
alphabetically. |
Line 1024 Accepts one optional argument: |
|
Line 1118 Accepts one optional argument: |
|
.It Cm v[1-7] | 32v |
.It Cm v[1-7] | 32v |
A version of |
A version of |
.At . |
.At . |
|
.It Cm III |
|
.At III . |
.It Cm V[.[1-4]]? |
.It Cm V[.[1-4]]? |
A version of |
A version of |
.At V . |
.At V . |
Line 1033 Note that these arguments do not begin with a hyphen. |
|
Line 1129 Note that these arguments do not begin with a hyphen. |
|
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.At |
.Dl \&.At |
|
.Dl \&.At III |
.Dl \&.At V.1 |
.Dl \&.At V.1 |
.Pp |
.Pp |
See also |
See also |
|
|
and |
and |
.Sx \&Sy . |
.Sx \&Sy . |
.Ss \&Bk |
.Ss \&Bk |
Keep the output generated from each macro input line together |
For each macro, keep its output together on the same output line, |
on one single output line. |
until the end of the macro or the end of the input line is reached, |
|
whichever comes first. |
Line breaks in text lines are unaffected. |
Line breaks in text lines are unaffected. |
The syntax is as follows: |
The syntax is as follows: |
.Pp |
.Pp |
|
|
and |
and |
.Sx \&Os . |
.Sx \&Os . |
.Ss \&Dv |
.Ss \&Dv |
Defined variables such as preprocessor constants. |
Defined variables such as preprocessor constants, constant symbols, |
|
enumeration values, and so on. |
.Pp |
.Pp |
Examples: |
Examples: |
|
.Dl \&.Dv NULL |
.Dl \&.Dv BUFSIZ |
.Dl \&.Dv BUFSIZ |
.Dl \&.Dv STDOUT_FILENO |
.Dl \&.Dv STDOUT_FILENO |
.Pp |
.Pp |
See also |
See also |
.Sx \&Er . |
.Sx \&Er |
|
and |
|
.Sx \&Ev |
|
for special-purpose constants and |
|
.Sx \&Va |
|
for variable symbols. |
.Ss \&Dx |
.Ss \&Dx |
Format the DragonFly BSD version provided as an argument, or a default |
Format the DragonFly BSD version provided as an argument, or a default |
value if no argument is provided. |
value if no argument is provided. |
Line 1774 argument is used as the enclosure head, for example, s |
|
Line 1879 argument is used as the enclosure head, for example, s |
|
will emulate |
will emulate |
.Sx \&Do . |
.Sx \&Do . |
.Ss \&Er |
.Ss \&Er |
Display error constants. |
Error constants for definitions of the |
|
.Va errno |
|
libc global variable. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Er EPERM |
.Dl \&.Er EPERM |
.Dl \&.Er ENOENT |
.Dl \&.Er ENOENT |
.Pp |
.Pp |
See also |
See also |
.Sx \&Dv . |
.Sx \&Dv |
|
for general constants. |
.Ss \&Es |
.Ss \&Es |
This macro is obsolete and not implemented. |
This macro is obsolete and not implemented. |
.Ss \&Ev |
.Ss \&Ev |
Line 1791 Environmental variables such as those specified in |
|
Line 1899 Environmental variables such as those specified in |
|
Examples: |
Examples: |
.Dl \&.Ev DISPLAY |
.Dl \&.Ev DISPLAY |
.Dl \&.Ev PATH |
.Dl \&.Ev PATH |
|
.Pp |
|
See also |
|
.Sx \&Dv |
|
for general constants. |
.Ss \&Ex |
.Ss \&Ex |
Insert a standard sentence regarding exit values. |
Insert a standard sentence regarding command exit values of 0 on success |
|
and >0 on failure. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Ex Fl std Op Ar utility |
.D1 Pf \. Sx \&Ex Fl std Op Ar utility ... |
.Pp |
.Pp |
When |
If |
.Ar utility |
.Ar utility |
is not specified, the document's name set by |
is not specified, the document's name set by |
.Sx \&Nm |
.Sx \&Nm |
is used. |
is used. |
|
Multiple |
|
.Ar utility |
|
arguments are treated as separate utilities. |
.Pp |
.Pp |
See also |
See also |
.Sx \&Rv . |
.Sx \&Rv . |
|
|
.Sx \&Fc , |
.Sx \&Fc , |
and |
and |
.Sx \&Ft . |
.Sx \&Ft . |
|
.Ss \&Fr |
|
This macro is obsolete and not implemented. |
.Ss \&Ft |
.Ss \&Ft |
A function type. |
A function type. |
Its syntax is as follows: |
Its syntax is as follows: |
|
|
list is the most complicated. |
list is the most complicated. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&It Op Cm args |
.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ... |
|
.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ... |
.Pp |
.Pp |
The |
The arguments consist of one or more lines of text and macros |
.Cm args |
representing a complete table line. |
are phrases, a mix of macros and text corresponding to a line column, |
Cells within the line are delimited by tabs or by the special |
delimited by tabs or the special |
.Sx \&Ta |
.Sq \&Ta |
block macro. |
pseudo-macro. |
The tab cell delimiter may only be used within the |
Lines subsequent the |
|
.Sx \&It |
.Sx \&It |
are interpreted within the scope of the last phrase. |
line itself; on following lines, only the |
Calling the pseudo-macro |
.Sx \&Ta |
.Sq \&Ta |
macro can be used to delimit cells, and |
will open a new phrase scope (this must occur on a macro line to be |
.Sx \&Ta |
interpreted as a macro). |
is only recognized as a macro when called by other macros, |
Note that the tab phrase delimiter may only be used within the |
not as the first macro on a line. |
|
.Pp |
|
Note that quoted strings may span tab-delimited cells on an |
.Sx \&It |
.Sx \&It |
line itself. |
line. |
Subsequent this, only the |
For example, |
.Sq \&Ta |
|
pseudo-macro may be used to delimit phrases. |
|
Furthermore, note that quoted sections propagate over tab-delimited |
|
phrases on an |
|
.Sx \&It , |
|
for example, |
|
.Pp |
.Pp |
.Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&; |
.Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&; |
.Pp |
.Pp |
Line 2091 The syntax is as follows: |
|
Line 2205 The syntax is as follows: |
|
The |
The |
.Ar library |
.Ar library |
parameter may be a system library, such as |
parameter may be a system library, such as |
.Ar libz |
.Cm libz |
or |
or |
.Ar libpam , |
.Cm libpam , |
in which case a small library description is printed next to the linker |
in which case a small library description is printed next to the linker |
invocation; or a custom library, in which case the library name is |
invocation; or a custom library, in which case the library name is |
printed in quotes. |
printed in quotes. |
Line 2435 block is used within a SEE ALSO section, a vertical sp |
|
Line 2549 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. |
Insert a standard sentence regarding a function call's return value of 0 |
This macro must consist of the |
on success and \-1 on error, with the |
.Fl std |
.Va errno |
argument followed by an optional |
libc global variable set on error. |
.Ar function . |
Its syntax is as follows: |
|
.Pp |
|
.D1 Pf \. Sx \&Rv Fl std Op Ar function ... |
|
.Pp |
If |
If |
.Ar function |
.Ar function |
is not provided, the document's name as stipulated by the first |
is not specified, the document's name set by |
.Sx \&Nm |
.Sx \&Nm |
is provided. |
is used. |
|
Multiple |
|
.Ar function |
|
arguments are treated as separate functions. |
.Pp |
.Pp |
See also |
See also |
.Sx \&Ex . |
.Sx \&Ex . |
Line 2473 Its syntax is as follows: |
|
Line 2593 Its syntax is as follows: |
|
.D1 Pf \. Sx \&Sm Cm on | off |
.D1 Pf \. Sx \&Sm Cm on | off |
.Pp |
.Pp |
By default, spacing is |
By default, spacing is |
.Ar on . |
.Cm on . |
When switched |
When switched |
.Ar off , |
.Cm off , |
no white space is inserted between macro arguments and between the |
no white space is inserted between macro arguments and between the |
output generated from adjacent macros, but text lines |
output generated from adjacent macros, but text lines |
still get normal spacing between words and sentences. |
still get normal spacing between words and sentences. |
|
|
.Sx \&Li , |
.Sx \&Li , |
and |
and |
.Sx \&Em . |
.Sx \&Em . |
|
.Ss \&Ta |
|
Table cell separator in |
|
.Sx \&Bl Fl column |
|
lists; can only be used below |
|
.Sx \&It . |
.Ss \&Tn |
.Ss \&Tn |
Format a tradename. |
Format a tradename. |
.Pp |
.Pp |
Line 2778 Newer groff and mandoc print |
|
Line 2903 Newer groff and mandoc print |
|
.Qq AT&T UNIX |
.Qq AT&T UNIX |
and the arguments. |
and the arguments. |
.It |
.It |
.Sx \&Bd Fl column |
.Sx \&Bl Fl column |
does not recognize trailing punctuation characters when they immediately |
does not recognize trailing punctuation characters when they immediately |
precede tabulator characters, but treats them as normal text and |
precede tabulator characters, but treats them as normal text and |
outputs a space before them. |
outputs a space before them. |
Line 2838 In new groff and mandoc, any list may be nested by def |
|
Line 2963 In new groff and mandoc, any list may be nested by def |
|
lists will restart the sequence only for the sub-list. |
lists will restart the sequence only for the sub-list. |
.It |
.It |
.Sx \&Li |
.Sx \&Li |
followed by a reserved character is incorrectly used in some manuals |
followed by a delimiter is incorrectly used in some manuals |
instead of properly quoting that character, which sometimes works with |
instead of properly quoting that character, which sometimes works with |
historic groff. |
historic groff. |
.It |
.It |