Return to mdoc.7 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.223, 2013/12/25 14:09:32 | version 1.239, 2014/10/20 17:59:20 | ||
---|---|---|---|
|
|
||
\&.Nm progname | \&.Nm progname | ||
\&.Nd one line about what it does | \&.Nd one line about what it does | ||
\&.\e\(dq .Sh LIBRARY | \&.\e\(dq .Sh LIBRARY | ||
\&.\e\(dq For sections 2, 3, & 9 only. | \&.\e\(dq For sections 2, 3, and 9 only. | ||
\&.\e\(dq Not used in OpenBSD. | \&.\e\(dq Not used in OpenBSD. | ||
\&.Sh SYNOPSIS | \&.Sh SYNOPSIS | ||
\&.Nm progname | \&.Nm progname | ||
|
|
||
The | The | ||
\&.Nm | \&.Nm | ||
utility processes files ... | utility processes files ... | ||
\&.\e\(dq .Sh CONTEXT | |||
\&.\e\(dq For section 9 functions only. | |||
\&.\e\(dq .Sh IMPLEMENTATION NOTES | \&.\e\(dq .Sh IMPLEMENTATION NOTES | ||
\&.\e\(dq Not used in OpenBSD. | \&.\e\(dq Not used in OpenBSD. | ||
\&.\e\(dq .Sh RETURN VALUES | \&.\e\(dq .Sh RETURN VALUES | ||
\&.\e\(dq For sections 2, 3, & 9 only. | \&.\e\(dq For sections 2, 3, and 9 function return values only. | ||
\&.\e\(dq .Sh ENVIRONMENT | \&.\e\(dq .Sh ENVIRONMENT | ||
\&.\e\(dq For sections 1, 6, 7, & 8 only. | \&.\e\(dq For sections 1, 6, 7, and 8 only. | ||
\&.\e\(dq .Sh FILES | \&.\e\(dq .Sh FILES | ||
\&.\e\(dq .Sh EXIT STATUS | \&.\e\(dq .Sh EXIT STATUS | ||
\&.\e\(dq For sections 1, 6, & 8 only. | \&.\e\(dq For sections 1, 6, and 8 only. | ||
\&.\e\(dq .Sh EXAMPLES | \&.\e\(dq .Sh EXAMPLES | ||
\&.\e\(dq .Sh DIAGNOSTICS | \&.\e\(dq .Sh DIAGNOSTICS | ||
\&.\e\(dq For sections 1, 4, 6, 7, & 8 only. | \&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. | ||
\&.\e\(dq .Sh ERRORS | \&.\e\(dq .Sh ERRORS | ||
\&.\e\(dq For sections 2, 3, & 9 only. | \&.\e\(dq For sections 2, 3, 4, and 9 errno settings only. | ||
\&.\e\(dq .Sh SEE ALSO | \&.\e\(dq .Sh SEE ALSO | ||
\&.\e\(dq .Xr foobar 1 | \&.\e\(dq .Xr foobar 1 | ||
\&.\e\(dq .Sh STANDARDS | \&.\e\(dq .Sh STANDARDS | ||
|
|
||
several subsections, like in the present | several subsections, like in the present | ||
.Nm | .Nm | ||
manual. | manual. | ||
.It Em CONTEXT | |||
This section lists the contexts in which functions can be called in section 9. | |||
The contexts are autoconf, process, or interrupt. | |||
.It Em IMPLEMENTATION NOTES | .It Em IMPLEMENTATION NOTES | ||
Implementation-specific notes should be kept here. | Implementation-specific notes should be kept here. | ||
This is useful when implementing standard functions that may have side | This is useful when implementing standard functions that may have side | ||
|
|
||
This often contains snippets of well-formed, well-tested invocations. | This often contains snippets of well-formed, well-tested invocations. | ||
Make sure that examples work properly! | Make sure that examples work properly! | ||
.It Em DIAGNOSTICS | .It Em DIAGNOSTICS | ||
Documents error conditions. | Documents error messages. | ||
This is most useful in section 4 manuals. | In section 4 and 9 manuals, these are usually messages printed by the | ||
kernel to the console and to the kernel log. | |||
In section 1, 6, 7, and 8, these are usually messages printed by | |||
userland programs to the standard error output. | |||
.Pp | |||
Historically, this section was used in place of | Historically, this section was used in place of | ||
.Em EXIT STATUS | .Em EXIT STATUS | ||
for manuals in sections 1, 6, and 8; however, this practise is | for manuals in sections 1, 6, and 8; however, this practise is | ||
|
|
||
.Sx \&Bl | .Sx \&Bl | ||
.Fl diag . | .Fl diag . | ||
.It Em ERRORS | .It Em ERRORS | ||
Documents error handling in sections 2, 3, and 9. | Documents | ||
.Xr errno 2 | |||
settings in sections 2, 3, 4, and 9. | |||
.Pp | .Pp | ||
See | See | ||
.Sx \&Er . | .Sx \&Er . | ||
|
|
||
References other manuals with related topics. | References other manuals with related topics. | ||
This section should exist for most manuals. | This section should exist for most manuals. | ||
Cross-references should conventionally be ordered first by section, then | Cross-references should conventionally be ordered first by section, then | ||
alphabetically. | alphabetically (ignoring case). | ||
.Pp | .Pp | ||
References to other documentation concerning the topic of the manual page, | References to other documentation concerning the topic of the manual page, | ||
for example authoritative books or journal articles, may also be | for example authoritative books or journal articles, may also be | ||
|
|
||
.It Sx \&Pf Ta prefix, no following horizontal space (one argument) | .It Sx \&Pf Ta prefix, no following horizontal space (one argument) | ||
.It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments) | .It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments) | ||
.It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments) | .It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments) | ||
.It Sx \&Sm Ta switch horizontal spacing mode: Cm on | off | .It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off | ||
.It Sx \&Bk , \&Ek Ta keep block: Fl words | .It Sx \&Bk , \&Ek Ta keep block: Fl words | ||
.It Sx \&br Ta force output line break in text mode (no arguments) | .It Sx \&br Ta force output line break in text mode (no arguments) | ||
.It Sx \&sp Ta force vertical space: Op Ar height | .It Sx \&sp Ta force vertical space: Op Ar height | ||
|
|
||
.It Sx \&Cd Ta kernel configuration declaration (>0 arguments) | .It Sx \&Cd Ta kernel configuration declaration (>0 arguments) | ||
.It Sx \&Ad Ta memory address (>0 arguments) | .It Sx \&Ad Ta memory address (>0 arguments) | ||
.It Sx \&Ms Ta mathematical symbol (>0 arguments) | .It Sx \&Ms Ta mathematical symbol (>0 arguments) | ||
.It Sx \&Tn Ta tradename (>0 arguments) | |||
.El | .El | ||
.Ss Physical markup | .Ss Physical markup | ||
.Bl -column "Brq, Bro, Brc" description | .Bl -column "Brq, Bro, Brc" description | ||
|
|
||
.It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ... | .It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ... | ||
.It Sx \&Rv Fl std Ta standard function return values: Op Ar function ... | .It Sx \&Rv Fl std Ta standard function return values: Op Ar function ... | ||
.It Sx \&St Ta reference to a standards document (one argument) | .It Sx \&St Ta reference to a standards document (one argument) | ||
.It Sx \&Ux Ta Ux | |||
.It Sx \&At Ta At | .It Sx \&At Ta At | ||
.It Sx \&Bx Ta Bx | .It Sx \&Bx Ta Bx | ||
.It Sx \&Bsx Ta Bsx | .It Sx \&Bsx Ta Bsx | ||
|
|
||
.Sx \&Dx , | .Sx \&Dx , | ||
.Sx \&Fx , | .Sx \&Fx , | ||
.Sx \&Nx , | .Sx \&Nx , | ||
.Sx \&Ox , | |||
and | and | ||
.Sx \&Ux . | .Sx \&Ox . | ||
.Ss \&Bc | .Ss \&Bc | ||
Close a | Close a | ||
.Sx \&Bo | .Sx \&Bo | ||
|
|
||
.Sx \&Dx , | .Sx \&Dx , | ||
.Sx \&Fx , | .Sx \&Fx , | ||
.Sx \&Nx , | .Sx \&Nx , | ||
.Sx \&Ox , | |||
and | and | ||
.Sx \&Ux . | .Sx \&Ox . | ||
.Ss \&Bt | .Ss \&Bt | ||
Supported only for compatibility, do not use this in new manuals. | |||
Prints | Prints | ||
.Dq is currently in beta test. | .Dq is currently in beta test. | ||
.Ss \&Bx | .Ss \&Bx | ||
|
|
||
.Sx \&Dx , | .Sx \&Dx , | ||
.Sx \&Fx , | .Sx \&Fx , | ||
.Sx \&Nx , | .Sx \&Nx , | ||
.Sx \&Ox , | |||
and | and | ||
.Sx \&Ux . | .Sx \&Ox . | ||
.Ss \&Cd | .Ss \&Cd | ||
Kernel configuration declaration. | Kernel configuration declaration. | ||
This denotes strings accepted by | This denotes strings accepted by | ||
|
|
||
block. | block. | ||
Does not have any tail arguments. | Does not have any tail arguments. | ||
.Ss \&Dd | .Ss \&Dd | ||
Document date. | Document date for display in the page footer. | ||
This is the mandatory first macro of any | This is the mandatory first macro of any | ||
.Nm | .Nm | ||
manual. | manual. | ||
|
|
||
.Dq $\&Mdocdate$ | .Dq $\&Mdocdate$ | ||
can be given as an argument. | can be given as an argument. | ||
.It | .It | ||
A few alternative date formats are accepted as well | The traditional, purely numeric | ||
and converted to the standard form. | .Xr man 7 | ||
format | |||
.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day | |||
is accepted, too. | |||
.It | .It | ||
If a date string cannot be parsed, it is used verbatim. | If a date string cannot be parsed, it is used verbatim. | ||
.It | .It | ||
|
|
||
and | and | ||
.Sx \&Os . | .Sx \&Os . | ||
.Ss \&Dl | .Ss \&Dl | ||
One-line intended display. | One-line indented display. | ||
This is formatted as literal text and is useful for commands and | This is formatted as literal text and is useful for commands and | ||
invocations. | invocations. | ||
It is followed by a newline. | It is followed by a newline. | ||
|
|
||
and | and | ||
.Sx \&Do . | .Sx \&Do . | ||
.Ss \&Dt | .Ss \&Dt | ||
Document title. | Document title for display in the page header. | ||
This is the mandatory second macro of any | This is the mandatory second macro of any | ||
.Nm | .Nm | ||
file. | file. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
.Bd -ragged -offset indent | .Bd -ragged -offset indent | ||
.Pf \. Sx \&Dt | .Pf \. Sx \&Dt | ||
.Oo | .Ar TITLE | ||
.Ar title | |||
.Oo | |||
.Ar section | .Ar section | ||
.Op Ar volume | .Op Ar volume | arch | ||
.Op Ar arch | |||
.Oc | |||
.Oc | |||
.Ed | .Ed | ||
.Pp | .Pp | ||
Its arguments are as follows: | Its arguments are as follows: | ||
.Bl -tag -width Ds -offset Ds | .Bl -tag -width section -offset 2n | ||
.It Ar title | .It Ar TITLE | ||
The document's title (name), defaulting to | The document's title (name), defaulting to | ||
.Dq UNKNOWN | .Dq UNTITLED | ||
if unspecified. | if unspecified. | ||
It should be capitalised. | To achieve a uniform appearance of page header lines, | ||
it should by convention be all caps. | |||
.It Ar section | .It Ar section | ||
The manual section. | The manual section. | ||
This may be one of | This may be one of | ||
.Ar 1 | .Cm 1 | ||
.Pq utilities , | .Pq utilities , | ||
.Ar 2 | .Cm 2 | ||
.Pq system calls , | .Pq system calls , | ||
.Ar 3 | .Cm 3 | ||
.Pq libraries , | .Pq libraries , | ||
.Ar 3p | .Cm 3p | ||
.Pq Perl libraries , | .Pq Perl libraries , | ||
.Ar 4 | .Cm 4 | ||
.Pq devices , | .Pq devices , | ||
.Ar 5 | .Cm 5 | ||
.Pq file formats , | .Pq file formats , | ||
.Ar 6 | .Cm 6 | ||
.Pq games , | .Pq games , | ||
.Ar 7 | .Cm 7 | ||
.Pq miscellaneous , | .Pq miscellaneous , | ||
.Ar 8 | .Cm 8 | ||
.Pq system utilities , | .Pq system utilities , | ||
.Ar 9 | .Cm 9 | ||
.Pq kernel functions , | .Pq kernel functions , | ||
.Ar X11 | .Cm X11 | ||
.Pq X Window System , | .Pq X Window System , | ||
.Ar X11R6 | .Cm X11R6 | ||
.Pq X Window System , | .Pq X Window System , | ||
.Ar unass | .Cm unass | ||
.Pq unassociated , | .Pq unassociated , | ||
.Ar local | .Cm local | ||
.Pq local system , | .Pq local system , | ||
.Ar draft | .Cm draft | ||
.Pq draft manual , | .Pq draft manual , | ||
or | or | ||
.Ar paper | .Cm 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 | ||
.Dq 1 | the empty string if unspecified. | ||
if unspecified. | |||
.It Ar volume | .It Ar volume | ||
This overrides the volume inferred from | This overrides the volume inferred from | ||
.Ar section . | .Ar section . | ||
This field is optional, and if specified, must be one of | This field is optional, and if specified, must be one of | ||
.Ar USD | .Cm USD | ||
.Pq users' supplementary documents , | .Pq users' supplementary documents , | ||
.Ar PS1 | .Cm PS1 | ||
.Pq programmers' supplementary documents , | .Pq programmers' supplementary documents , | ||
.Ar AMD | .Cm AMD | ||
.Pq administrators' supplementary documents , | .Pq administrators' supplementary documents , | ||
.Ar SMM | .Cm SMM | ||
.Pq system managers' manuals , | .Pq system managers' manuals , | ||
.Ar URM | .Cm URM | ||
.Pq users' reference manuals , | .Pq users' reference manuals , | ||
.Ar PRM | .Cm PRM | ||
.Pq programmers' reference manuals , | .Pq programmers' reference manuals , | ||
.Ar KM | .Cm KM | ||
.Pq kernel manuals , | .Pq kernel manuals , | ||
.Ar IND | .Cm IND | ||
.Pq master index , | .Pq master index , | ||
.Ar MMI | .Cm MMI | ||
.Pq master index , | .Pq master index , | ||
.Ar LOCAL | .Cm LOCAL | ||
.Pq local manuals , | .Pq local manuals , | ||
.Ar LOC | .Cm LOC | ||
.Pq local manuals , | .Pq local manuals , | ||
or | or | ||
.Ar CON | .Cm CON | ||
.Pq contributed manuals . | .Pq contributed manuals . | ||
.It Ar arch | .It Ar arch | ||
This specifies the machine architecture a manual page applies to, | This specifies the machine architecture a manual page applies to, | ||
|
|
||
.Sx \&Bx , | .Sx \&Bx , | ||
.Sx \&Fx , | .Sx \&Fx , | ||
.Sx \&Nx , | .Sx \&Nx , | ||
.Sx \&Ox , | |||
and | and | ||
.Sx \&Ux . | .Sx \&Ox . | ||
.Ss \&Ec | .Ss \&Ec | ||
Close a scope started by | Close a scope started by | ||
.Sx \&Eo . | .Sx \&Eo . | ||
|
|
||
and | and | ||
.Sx \&It . | .Sx \&It . | ||
.Ss \&Em | .Ss \&Em | ||
Denotes text that should be | Request an italic font. | ||
.Em emphasised . | If the output device does not provide that, underline. | ||
Note that this is a presentation term and should not be used for | |||
stylistically decorating technical terms. | |||
Depending on the output device, this is usually represented | |||
using an italic font or underlined characters. | |||
.Pp | .Pp | ||
This is most often used for stress emphasis (not to be confused with | |||
importance, see | |||
.Sx \&Sy ) . | |||
In the rare cases where none of the semantic markup macros fit, | |||
it can also be used for technical terms and placeholders, except | |||
that for syntax elements, | |||
.Sx \&Sy | |||
and | |||
.Sx \&Ar | |||
are preferred, respectively. | |||
.Pp | |||
Examples: | Examples: | ||
.Dl \&.Em Warnings! | .Bd -literal -compact -offset indent | ||
.Dl \&.Em Remarks : | Selected lines are those | ||
\&.Em not | |||
matching any of the specified patterns. | |||
Some of the functions use a | |||
\&.Em hold space | |||
to save the pattern space for subsequent retrieval. | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Bf , | .Sx \&Bf , | ||
|
|
||
and | and | ||
.Sx \&Sy . | .Sx \&Sy . | ||
.Ss \&En | .Ss \&En | ||
This macro is obsolete and not implemented in | This macro is obsolete. | ||
.Xr mandoc 1 . | Use | ||
.Sx \&Eo | |||
or any of the other enclosure macros. | |||
.Pp | |||
It encloses its argument in the delimiters specified by the last | |||
.Sx \&Es | |||
macro. | |||
.Ss \&Eo | .Ss \&Eo | ||
An arbitrary enclosure. | An arbitrary enclosure. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
|
|
||
.Sx \&Dv | .Sx \&Dv | ||
for general constants. | for general constants. | ||
.Ss \&Es | .Ss \&Es | ||
This macro is obsolete and not implemented. | This macro is obsolete. | ||
Use | |||
.Sx \&Eo | |||
or any of the other enclosure macros. | |||
.Pp | |||
It takes two arguments, defining the delimiters to be used by subsequent | |||
.Sx \&En | |||
macros. | |||
.Ss \&Ev | .Ss \&Ev | ||
Environmental variables such as those specified in | Environmental variables such as those specified in | ||
.Xr environ 7 . | .Xr environ 7 . | ||
|
|
||
See also | See also | ||
.Sx \&Rv . | .Sx \&Rv . | ||
.Ss \&Fa | .Ss \&Fa | ||
Function argument. | Function argument or parameter. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
.Bd -ragged -offset indent | .Bd -ragged -offset indent | ||
.Pf \. Sx \&Fa | .Pf \. Sx \&Fa | ||
.Op Cm argtype | .Qo | ||
.Cm argname | .Op Ar argtype | ||
.Op Ar argname | |||
.Qc Ar \&... | |||
.Ed | .Ed | ||
.Pp | .Pp | ||
This may be invoked for names with or without the corresponding type. | Each argument may be a name and a type (recommended for the | ||
It is also used to specify the field name of a structure. | .Em SYNOPSIS | ||
section), a name alone (for function invocations), | |||
or a type alone (for function prototypes). | |||
If both a type and a name are given or if the type consists of multiple | |||
words, all words belonging to the same function argument have to be | |||
given in a single argument to the | |||
.Sx \&Fa | |||
macro. | |||
.Pp | |||
This macro is also used to specify the field name of a structure. | |||
.Pp | |||
Most often, the | Most often, the | ||
.Sx \&Fa | .Sx \&Fa | ||
macro is used in the | macro is used in the | ||
.Em SYNOPSIS | .Em SYNOPSIS | ||
within | within | ||
.Sx \&Fo | .Sx \&Fo | ||
section when documenting multi-line function prototypes. | blocks when documenting multi-line function prototypes. | ||
If invoked with multiple arguments, the arguments are separated by a | If invoked with multiple arguments, the arguments are separated by a | ||
comma. | comma. | ||
Furthermore, if the following macro is another | Furthermore, if the following macro is another | ||
|
|
||
Examples: | Examples: | ||
.Dl \&.Fa \(dqconst char *p\(dq | .Dl \&.Fa \(dqconst char *p\(dq | ||
.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq | .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq | ||
.Dl \&.Fa foo | .Dl \&.Fa \(dqchar *\(dq size_t | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Fo . | .Sx \&Fo . | ||
|
|
||
.br | .br | ||
.Pf \. Sx \&Fo Ar funcname | .Pf \. Sx \&Fo Ar funcname | ||
.br | .br | ||
.Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname | .Pf \. Sx \&Fa Qq Ar argtype Ar argname | ||
.br | .br | ||
\&.\.\. | \&.\.\. | ||
.br | .br | ||
|
|
||
and | and | ||
.Sx \&Ft . | .Sx \&Ft . | ||
.Ss \&Fr | .Ss \&Fr | ||
This macro is obsolete and not implemented in | This macro is obsolete. | ||
.Xr mandoc 1 . | No replacement markup is needed. | ||
.Pp | .Pp | ||
It was used to show function return values. | It was used to show numerical function return values in an italic font. | ||
The syntax was: | |||
.Pp | |||
.Dl Pf . Sx \&Fr Ar value | |||
.Ss \&Ft | .Ss \&Ft | ||
A function type. | A function type. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
|
|
||
.Sx \&Bx , | .Sx \&Bx , | ||
.Sx \&Dx , | .Sx \&Dx , | ||
.Sx \&Nx , | .Sx \&Nx , | ||
.Sx \&Ox , | |||
and | and | ||
.Sx \&Ux . | .Sx \&Ox . | ||
.Ss \&Hf | .Ss \&Hf | ||
This macro is not implemented in | This macro is not implemented in | ||
.Xr mandoc 1 . | .Xr mandoc 1 . | ||
|
|
||
.Sx \&Bx , | .Sx \&Bx , | ||
.Sx \&Dx , | .Sx \&Dx , | ||
.Sx \&Fx , | .Sx \&Fx , | ||
.Sx \&Ox , | |||
and | and | ||
.Sx \&Ux . | .Sx \&Ox . | ||
.Ss \&Oc | .Ss \&Oc | ||
Close multi-line | Close multi-line | ||
.Sx \&Oo | .Sx \&Oo | ||
|
|
||
See also | See also | ||
.Sx \&Oo . | .Sx \&Oo . | ||
.Ss \&Os | .Ss \&Os | ||
Document operating system version. | Operating system version for display in the page footer. | ||
This is the mandatory third macro of | This is the mandatory third macro of | ||
any | any | ||
.Nm | .Nm | ||
|
|
||
and | and | ||
.Sx \&Dt . | .Sx \&Dt . | ||
.Ss \&Ot | .Ss \&Ot | ||
This macro is obsolete and not implemented in | This macro is obsolete. | ||
.Xr mandoc 1 . | Use | ||
.Sx \&Ft | |||
instead; with | |||
.Xr mandoc 1 , | |||
both have the same effect. | |||
.Pp | .Pp | ||
Historical | Historical | ||
.Nm | .Nm | ||
|
|
||
.Sx \&Bx , | .Sx \&Bx , | ||
.Sx \&Dx , | .Sx \&Dx , | ||
.Sx \&Fx , | .Sx \&Fx , | ||
.Sx \&Nx , | |||
and | and | ||
.Sx \&Ux . | .Sx \&Nx . | ||
.Ss \&Pa | .Ss \&Pa | ||
An absolute or relative file system path, or a file or directory name. | An absolute or relative file system path, or a file or directory name. | ||
If an argument is not provided, the character | If an argument is not provided, the character | ||
|
|
||
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: | ||
.Pp | .Pp | ||
.D1 Pf \. Sx \&Sm Cm on | off | .D1 Pf \. Sx \&Sm Op Cm on | off | ||
.Pp | .Pp | ||
By default, spacing is | By default, spacing is | ||
.Cm on . | .Cm on . | ||
|
|
||
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. | ||
.Pp | |||
When called without an argument, the | |||
.Sx \&Sm | |||
macro toggles the spacing mode. | |||
Using this is not recommended because it makes the code harder to read. | |||
.Ss \&So | .Ss \&So | ||
Multi-line version of | Multi-line version of | ||
.Sx \&Sq . | .Sx \&Sq . | ||
|
|
||
.Sx \&Sx . | .Sx \&Sx . | ||
.Ss \&St | .Ss \&St | ||
Replace an abbreviation for a standard with the full form. | Replace an abbreviation for a standard with the full form. | ||
The following standards are recognised: | The following standards are recognised. | ||
Where multiple lines are given without a blank line in between, | |||
they all refer to the same standard, and using the first form | |||
is recommended. | |||
.Bl -tag -width 1n | |||
.It C language standards | |||
.Pp | .Pp | ||
.Bl -tag -width "-p1003.1g-2000X" -compact | .Bl -tag -width "-p1003.1g-2000" -compact | ||
.It \-p1003.1-88 | .It \-ansiC | ||
.St -p1003.1-88 | .St -ansiC | ||
.It \-p1003.1-90 | .It \-ansiC-89 | ||
.St -p1003.1-90 | .St -ansiC-89 | ||
.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.1d-99 | |||
.St -p1003.1d-99 | |||
.It \-p1003.1g-2000 | |||
.St -p1003.1g-2000 | |||
.It \-p1003.1i-95 | |||
.St -p1003.1i-95 | |||
.It \-p1003.1j-2000 | |||
.St -p1003.1j-2000 | |||
.It \-p1003.1q-2000 | |||
.St -p1003.1q-2000 | |||
.It \-p1003.2 | |||
.St -p1003.2 | |||
.It \-p1003.2-92 | |||
.St -p1003.2-92 | |||
.It \-p1003.2a-92 | |||
.St -p1003.2a-92 | |||
.It \-p1387.2 | |||
.St -p1387.2 | |||
.It \-p1387.2-95 | |||
.St -p1387.2-95 | |||
.It \-isoC | .It \-isoC | ||
.St -isoC | .St -isoC | ||
.It \-isoC-90 | .It \-isoC-90 | ||
.St -isoC-90 | .St -isoC-90 | ||
.br | |||
The original C standard. | |||
.Pp | |||
.It \-isoC-amd1 | .It \-isoC-amd1 | ||
.St -isoC-amd1 | .St -isoC-amd1 | ||
.Pp | |||
.It \-isoC-tcor1 | .It \-isoC-tcor1 | ||
.St -isoC-tcor1 | .St -isoC-tcor1 | ||
.Pp | |||
.It \-isoC-tcor2 | .It \-isoC-tcor2 | ||
.St -isoC-tcor2 | .St -isoC-tcor2 | ||
.Pp | |||
.It \-isoC-99 | .It \-isoC-99 | ||
.St -isoC-99 | .St -isoC-99 | ||
.It \-ansiC-99 | |||
.St -ansiC-99 | |||
.br | |||
The second major version of the C language standard. | |||
.Pp | |||
.It \-isoC-2011 | .It \-isoC-2011 | ||
.St -isoC-2011 | .St -isoC-2011 | ||
.br | |||
The third major version of the C language standard. | |||
.El | |||
.It POSIX.1 before the Single UNIX Specification | |||
.Pp | |||
.Bl -tag -width "-p1003.1g-2000" -compact | |||
.It \-p1003.1-88 | |||
.St -p1003.1-88 | |||
.It \-p1003.1 | |||
.St -p1003.1 | |||
.br | |||
The original POSIX standard, based on ANSI C. | |||
.Pp | |||
.It \-p1003.1-90 | |||
.St -p1003.1-90 | |||
.It \-iso9945-1-90 | .It \-iso9945-1-90 | ||
.St -iso9945-1-90 | .St -iso9945-1-90 | ||
.br | |||
The first update of POSIX.1. | |||
.Pp | |||
.It \-p1003.1b-93 | |||
.St -p1003.1b-93 | |||
.It \-p1003.1b | |||
.St -p1003.1b | |||
.br | |||
Real-time extensions. | |||
.Pp | |||
.It \-p1003.1c-95 | |||
.St -p1003.1c-95 | |||
.br | |||
POSIX thread interfaces. | |||
.Pp | |||
.It \-p1003.1i-95 | |||
.St -p1003.1i-95 | |||
.br | |||
Technical Corrigendum. | |||
.Pp | |||
.It \-p1003.1-96 | |||
.St -p1003.1-96 | |||
.It \-iso9945-1-96 | .It \-iso9945-1-96 | ||
.St -iso9945-1-96 | .St -iso9945-1-96 | ||
.It \-iso9945-2-93 | .br | ||
.St -iso9945-2-93 | Includes POSIX.1-1990, 1b, 1c, and 1i. | ||
.It \-ansiC | .El | ||
.St -ansiC | .It X/Open Portability Guide version 4 and related standards | ||
.It \-ansiC-89 | .Pp | ||
.St -ansiC-89 | .Bl -tag -width "-p1003.1g-2000" -compact | ||
.It \-ansiC-99 | |||
.St -ansiC-99 | |||
.It \-ieee754 | |||
.St -ieee754 | |||
.It \-iso8802-3 | |||
.St -iso8802-3 | |||
.It \-iso8601 | |||
.St -iso8601 | |||
.It \-ieee1275-94 | |||
.St -ieee1275-94 | |||
.It \-xpg3 | .It \-xpg3 | ||
.St -xpg3 | .St -xpg3 | ||
.br | |||
An XPG4 precursor, published in 1989. | |||
.Pp | |||
.It \-p1003.2 | |||
.St -p1003.2 | |||
.It \-p1003.2-92 | |||
.St -p1003.2-92 | |||
.It \-iso9945-2-93 | |||
.St -iso9945-2-93 | |||
.br | |||
An XCU4 precursor. | |||
.Pp | |||
.It \-p1003.2a-92 | |||
.St -p1003.2a-92 | |||
.br | |||
Updates to POSIX.2. | |||
.Pp | |||
.It \-xpg4 | .It \-xpg4 | ||
.St -xpg4 | .St -xpg4 | ||
.br | |||
Based on POSIX.1 and POSIX.2, published in 1992. | |||
.El | |||
.It Single UNIX Specification version 1 and related standards | |||
.Pp | |||
.Bl -tag -width "-p1003.1g-2000" -compact | |||
.It \-susv1 | |||
.St -susv1 | |||
.It \-xpg4.2 | .It \-xpg4.2 | ||
.St -xpg4.2 | .St -xpg4.2 | ||
.br | |||
This standard was published in 1994. | |||
It was used as the basis for UNIX 95 certification. | |||
The following three refer to parts of it. | |||
.Pp | |||
.It \-xsh4.2 | |||
.St -xsh4.2 | |||
.Pp | |||
.It \-xcurses4.2 | |||
.St -xcurses4.2 | |||
.Pp | |||
.It \-p1003.1g-2000 | |||
.St -p1003.1g-2000 | |||
.br | |||
Networking APIs, including sockets. | |||
.Pp | |||
.It \-xpg4.3 | .It \-xpg4.3 | ||
.St -xpg4.3 | .St -xpg4.3 | ||
.Pp | |||
.It \-svid4 | |||
.St -svid4 , | |||
.br | |||
Published in 1995. | |||
.El | |||
.It Single UNIX Specification version 2 and related standards | |||
.Pp | |||
.Bl -tag -width "-p1003.1g-2000" -compact | |||
.It \-susv2 | |||
.St -susv2 | |||
This Standard was published in 1997 | |||
and is also called X/Open Portability Guide version 5. | |||
It was used as the basis for UNIX 98 certification. | |||
The following refer to parts of it. | |||
.Pp | |||
.It \-xbd5 | .It \-xbd5 | ||
.St -xbd5 | .St -xbd5 | ||
.It \-xcu5 | .Pp | ||
.St -xcu5 | |||
.It \-xsh4.2 | |||
.St -xsh4.2 | |||
.It \-xsh5 | .It \-xsh5 | ||
.St -xsh5 | .St -xsh5 | ||
.Pp | |||
.It \-xcu5 | |||
.St -xcu5 | |||
.Pp | |||
.It \-xns5 | .It \-xns5 | ||
.St -xns5 | .St -xns5 | ||
.It \-xns5.2 | |||
.St -xns5.2 | |||
.It \-xns5.2d2.0 | .It \-xns5.2d2.0 | ||
.St -xns5.2d2.0 | .St -xns5.2d2.0 | ||
.It \-xcurses4.2 | .It \-xns5.2 | ||
.St -xcurses4.2 | .St -xns5.2 | ||
.It \-susv2 | .Pp | ||
.St -susv2 | .It \-p1387.2 | ||
.St -p1387.2 | |||
.It \-p1387.2-95 | |||
.St -p1387.2-95 | |||
.br | |||
POSIX software administration. | |||
.El | |||
.It Single UNIX Specification version 3 and related standards | |||
.Pp | |||
.Bl -tag -width "-p1003.1g-2000X" -compact | |||
.It \-p1003.1d-99 | |||
.St -p1003.1d-99 | |||
.br | |||
Additional real-time extensions. | |||
.Pp | |||
.It \-p1003.1j-2000 | |||
.St -p1003.1j-2000 | |||
.br | |||
Advanced real-time extensions. | |||
.Pp | |||
.It \-p1003.1q-2000 | |||
.St -p1003.1q-2000 | |||
.br | |||
Amendment 7: Tracing [C Language]. | |||
.Pp | |||
.It \-p1003.1-2001 | |||
.St -p1003.1-2001 | |||
.It \-susv3 | .It \-susv3 | ||
.St -susv3 | .St -susv3 | ||
.It \-svid4 | .br | ||
.St -svid4 | This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j. | ||
It is also called X/Open Portability Guide version 6. | |||
It is used as the basis for UNIX 03 certification. | |||
.Pp | |||
.It \-p1003.1-2004 | |||
.St -p1003.1-2004 | |||
.br | |||
The second and last Technical Corrigendum. | |||
.El | .El | ||
.It Single UNIX Specification version 4 | |||
.Pp | |||
.Bl -tag -width "-p1003.1g-2000" -compact | |||
.It \-p1003.1-2008 | |||
.St -p1003.1-2008 | |||
.It \-susv4 | |||
.St -susv4 | |||
.br | |||
This standard is also called | |||
X/Open Portability Guide version 7. | |||
.Pp | |||
.It \-p1003.1-2013 | |||
.St -p1003.1-2013 | |||
.br | |||
This is the first Technical Corrigendum. | |||
.El | |||
.It Other standards | |||
.Pp | |||
.Bl -tag -width "-p1003.1g-2000" -compact | |||
.It \-ieee754 | |||
.St -ieee754 | |||
.br | |||
Floating-point arithmetic. | |||
.Pp | |||
.It \-iso8601 | |||
.St -iso8601 | |||
.br | |||
Representation of dates and times, published in 1988. | |||
.Pp | |||
.It \-iso8802-3 | |||
.St -iso8802-3 | |||
.br | |||
Ethernet local area networks. | |||
.Pp | |||
.It \-ieee1275-94 | |||
.St -ieee1275-94 | |||
.El | |||
.El | |||
.Ss \&Sx | .Ss \&Sx | ||
Reference a section or subsection in the same manual page. | Reference a section or subsection in the same manual page. | ||
The referenced section or subsection name must be identical to the | The referenced section or subsection name must be identical to the | ||
|
|
||
and | and | ||
.Sx \&Ss . | .Sx \&Ss . | ||
.Ss \&Sy | .Ss \&Sy | ||
Format enclosed arguments in symbolic | Request a boldface font. | ||
.Pq Dq boldface . | |||
Note that this is a presentation term and should not be used for | |||
stylistically decorating technical terms. | |||
.Pp | .Pp | ||
This is most often used to indicate importance or seriousness (not to be | |||
confused with stress emphasis, see | |||
.Sx \&Em ) . | |||
When none of the semantic macros fit, it is also adequate for syntax | |||
elements that have to be given or that appear verbatim. | |||
.Pp | |||
Examples: | |||
.Bd -literal -compact -offset indent | |||
\&.Sy Warning : | |||
If | |||
\&.Sy s | |||
appears in the owner permissions, set-user-ID mode is set. | |||
This utility replaces the former | |||
\&.Sy dumpdir | |||
program. | |||
.Ed | |||
.Pp | |||
See also | See also | ||
.Sx \&Bf , | .Sx \&Bf , | ||
.Sx \&Em , | .Sx \&Em , | ||
|
|
||
lists; can only be used below | lists; can only be used below | ||
.Sx \&It . | .Sx \&It . | ||
.Ss \&Tn | .Ss \&Tn | ||
Format a tradename. | Supported only for compatibility, do not use this in new manuals. | ||
.Pp | Even though the macro name | ||
Since this macro is often implemented to use a small caps font, | .Pq Dq tradename | ||
it has historically been used for acronyms (like ASCII) as well. | suggests a semantic function, historic usage is inconsistent, mostly | ||
Such usage is not recommended because it would use the same macro | using it as a presentation-level macro to request a small caps font. | ||
sometimes for semantical annotation, sometimes for physical formatting. | |||
.Pp | |||
Examples: | |||
.Dl \&.Tn IBM | |||
.Ss \&Ud | .Ss \&Ud | ||
Supported only for compatibility, do not use this in new manuals. | |||
Prints out | Prints out | ||
.Dq currently under development. | .Dq currently under development. | ||
.Ss \&Ux | .Ss \&Ux | ||
Format the | Supported only for compatibility, do not use this in new manuals. | ||
.Ux | Prints out | ||
name. | .Dq Ux . | ||
Accepts no argument. | |||
.Pp | |||
Examples: | |||
.Dl \&.Ux | |||
.Pp | |||
See also | |||
.Sx \&At , | |||
.Sx \&Bsx , | |||
.Sx \&Bx , | |||
.Sx \&Dx , | |||
.Sx \&Fx , | |||
.Sx \&Nx , | |||
and | |||
.Sx \&Ox . | |||
.Ss \&Va | .Ss \&Va | ||
A variable name. | A variable name. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Dl \&.Va foo | .Dl \&.Va foo | ||
.Dl \&.Va const char *bar ; | .Dl \&.Va const char *bar ; | ||
.Pp | |||
For function arguments and parameters, use | |||
.Sx \&Fa | |||
instead. | |||
For declarations of global variables in the | |||
.Em SYNOPSIS | |||
section, use | |||
.Sx \&Vt . | |||
.Ss \&Vt | .Ss \&Vt | ||
A variable type. | A variable type. | ||
.Pp | |||
This is also used for indicating global variables in the | This is also used for indicating global variables in the | ||
.Em SYNOPSIS | .Em SYNOPSIS | ||
section, in which case a variable name is also specified. | section, in which case a variable name is also specified. | ||
|
|
||
and a blank line is inserted in front if there is a preceding | and a blank line is inserted in front if there is a preceding | ||
function definition or include directive. | function definition or include directive. | ||
.Pp | .Pp | ||
Note that this should not be confused with | |||
.Sx \&Ft , | |||
which is used for function return types. | |||
.Pp | |||
Examples: | Examples: | ||
.Dl \&.Vt unsigned char | .Dl \&.Vt unsigned char | ||
.Dl \&.Vt extern const char * const sys_signame[] \&; | .Dl \&.Vt extern const char * const sys_signame[] \&; | ||
.Pp | .Pp | ||
For parameters in function prototypes, use | |||
.Sx \&Fa | |||
instead, for function return types | |||
.Sx \&Ft , | |||
and for variable names outside the | |||
.Em SYNOPSIS | |||
section | |||
.Sx \&Va , | |||
even when including a type with the name. | |||
See also | See also | ||
.Sx MANUAL STRUCTURE | .Sx MANUAL STRUCTURE . | ||
and | |||
.Sx \&Va . | |||
.Ss \&Xc | .Ss \&Xc | ||
Close a scope opened by | Close a scope opened by | ||
.Sx \&Xo . | .Sx \&Xo . | ||
|
|
||
.It Sx \&D1 Ta \&No Ta \&Yes | .It Sx \&D1 Ta \&No Ta \&Yes | ||
.It Sx \&Dl Ta \&No Ta Yes | .It Sx \&Dl Ta \&No Ta Yes | ||
.It Sx \&Dq Ta Yes Ta Yes | .It Sx \&Dq Ta Yes Ta Yes | ||
.It Sx \&En Ta Yes Ta Yes | |||
.It Sx \&Op Ta Yes Ta Yes | .It Sx \&Op Ta Yes Ta Yes | ||
.It Sx \&Pq Ta Yes Ta Yes | .It Sx \&Pq Ta Yes Ta Yes | ||
.It Sx \&Ql Ta Yes Ta Yes | .It Sx \&Ql Ta Yes Ta Yes | ||
|
|
||
.It Sx \&Dv Ta Yes Ta Yes Ta >0 | .It Sx \&Dv Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Dx Ta Yes Ta Yes Ta n | .It Sx \&Dx Ta Yes Ta Yes Ta n | ||
.It Sx \&Em Ta Yes Ta Yes Ta >0 | .It Sx \&Em Ta Yes Ta Yes Ta >0 | ||
.It Sx \&En Ta \&No Ta \&No Ta 0 | |||
.It Sx \&Er Ta Yes Ta Yes Ta >0 | .It Sx \&Er Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Es Ta \&No Ta \&No Ta 0 | .It Sx \&Es Ta Yes Ta Yes Ta 2 | ||
.It Sx \&Ev Ta Yes Ta Yes Ta >0 | .It Sx \&Ev Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Ex Ta \&No Ta \&No Ta n | .It Sx \&Ex Ta \&No Ta \&No Ta n | ||
.It Sx \&Fa Ta Yes Ta Yes Ta >0 | .It Sx \&Fa Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Fd Ta \&No Ta \&No Ta >0 | .It Sx \&Fd Ta \&No Ta \&No Ta >0 | ||
.It Sx \&Fl Ta Yes Ta Yes Ta n | .It Sx \&Fl Ta Yes Ta Yes Ta n | ||
.It Sx \&Fn Ta Yes Ta Yes Ta >0 | .It Sx \&Fn Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Fr Ta \&No Ta \&No Ta n | .It Sx \&Fr Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Ft Ta Yes Ta Yes Ta >0 | .It Sx \&Ft Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Fx Ta Yes Ta Yes Ta n | .It Sx \&Fx Ta Yes Ta Yes Ta n | ||
.It Sx \&Hf Ta \&No Ta \&No Ta n | .It Sx \&Hf Ta \&No Ta \&No Ta n | ||
|
|
||
.It Sx \&Ns Ta Yes Ta Yes Ta 0 | .It Sx \&Ns Ta Yes Ta Yes Ta 0 | ||
.It Sx \&Nx Ta Yes Ta Yes Ta n | .It Sx \&Nx Ta Yes Ta Yes Ta n | ||
.It Sx \&Os Ta \&No Ta \&No Ta n | .It Sx \&Os Ta \&No Ta \&No Ta n | ||
.It Sx \&Ot Ta \&No Ta \&No Ta n | .It Sx \&Ot Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Ox Ta Yes Ta Yes Ta n | .It Sx \&Ox Ta Yes Ta Yes Ta n | ||
.It Sx \&Pa Ta Yes Ta Yes Ta n | .It Sx \&Pa Ta Yes Ta Yes Ta n | ||
.It Sx \&Pf Ta Yes Ta Yes Ta 1 | .It Sx \&Pf Ta Yes Ta Yes Ta 1 | ||
.It Sx \&Pp Ta \&No Ta \&No Ta 0 | .It Sx \&Pp Ta \&No Ta \&No Ta 0 | ||
.It Sx \&Rv Ta \&No Ta \&No Ta n | .It Sx \&Rv Ta \&No Ta \&No Ta n | ||
.It Sx \&Sm Ta \&No Ta \&No Ta 1 | .It Sx \&Sm Ta \&No Ta \&No Ta <2 | ||
.It Sx \&St Ta \&No Ta Yes Ta 1 | .It Sx \&St Ta \&No Ta Yes Ta 1 | ||
.It Sx \&Sx Ta Yes Ta Yes Ta >0 | .It Sx \&Sx Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Sy Ta Yes Ta Yes Ta >0 | .It Sx \&Sy Ta Yes Ta Yes Ta >0 | ||
|
|
||
.Ql \ef | .Ql \ef | ||
font escape sequences is never required. | font escape sequences is never required. | ||
.Sh COMPATIBILITY | .Sh COMPATIBILITY | ||
This section documents compatibility between mandoc and other | This section provides an incomplete list of compatibility issues | ||
troff implementations, at this time limited to GNU troff | between mandoc and other troff implementations, at this time limited | ||
to GNU troff | |||
.Pq Qq groff . | .Pq Qq groff . | ||
The term | The term | ||
.Qq historic groff | .Qq historic groff | ||
|
|
||
can only be called by other macros, but not at the beginning of a line. | can only be called by other macros, but not at the beginning of a line. | ||
.It | .It | ||
.Sx \&%C | .Sx \&%C | ||
is not implemented. | is not implemented (up to and including groff-1.22.2). | ||
.It | .It | ||
Historic groff only allows up to eight or nine arguments per macro input | Historic groff only allows up to eight or nine arguments per macro input | ||
line, depending on the exact situation. | line, depending on the exact situation. | ||
|
|
||
.Sq \ef | .Sq \ef | ||
.Pq font face | .Pq font face | ||
and | and | ||
.Sq \ef | .Sq \eF | ||
.Pq font family face | .Pq font family face | ||
.Sx Text Decoration | .Sx Text Decoration | ||
escapes behave irregularly when specified within line-macro scopes. | escapes behave irregularly when specified within line-macro scopes. | ||
|
|
||
.Fl file Ar file . | .Fl file Ar file . | ||
.It | .It | ||
.Sx \&Bd | .Sx \&Bd | ||
.Fl offset Ar center | .Fl offset Cm center | ||
and | and | ||
.Fl offset Ar right . | .Fl offset Cm right . | ||
Groff does not implement centred and flush-right rendering either, | Groff does not implement centred and flush-right rendering either, | ||
but produces large indentations. | but produces large indentations. | ||
.It | |||
The | |||
.Sq \eh | |||
.Pq horizontal position , | |||
.Sq \ev | |||
.Pq vertical position , | |||
.Sq \em | |||
.Pq text colour , | |||
.Sq \eM | |||
.Pq text filling colour , | |||
.Sq \ez | |||
.Pq zero-length character , | |||
.Sq \ew | |||
.Pq string length , | |||
.Sq \ek | |||
.Pq horizontal position marker , | |||
.Sq \eo | |||
.Pq text overstrike , | |||
and | |||
.Sq \es | |||
.Pq text size | |||
escape sequences are all discarded in mandoc. | |||
.It | |||
The | |||
.Sq \ef | |||
scaling unit is accepted by mandoc, but rendered as the default unit. | |||
.It | |||
In quoted literals, groff allows pairwise double-quotes to produce a | |||
standalone double-quote in formatted output. | |||
This is not supported by mandoc. | |||
.El | .El | ||
.Sh SEE ALSO | .Sh SEE ALSO | ||
.Xr man 1 , | .Xr man 1 , |