version 1.226, 2014/01/24 22:54:33 |
version 1.230, 2014/06/24 21:43:08 |
Line 125 file for a utility |
|
Line 125 file for a utility |
|
\&.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 |
Line 135 file for a utility |
|
Line 135 file for a utility |
|
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 |
Line 318 macro followed by a non-standard section name, and eac |
|
Line 320 macro followed by a non-standard section name, and eac |
|
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 . |
Line 502 in the alphabetical |
|
Line 513 in the alphabetical |
|
.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 |
Line 530 in the alphabetical |
|
Line 540 in the alphabetical |
|
.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 |
|
|
.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 \&Sy . |
.Sx \&Sy . |
.Ss \&En |
.Ss \&En |
This macro is obsolete and not implemented in |
This macro is obsolete and ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
.Ss \&Eo |
.Ss \&Eo |
An arbitrary enclosure. |
An arbitrary enclosure. |
|
|
.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 and ignored by |
|
.Xr mandoc 1 . |
.Ss \&Ev |
.Ss \&Ev |
Environmental variables such as those specified in |
Environmental variables such as those specified in |
.Xr environ 7 . |
.Xr environ 7 . |
|
|
and |
and |
.Sx \&Ft . |
.Sx \&Ft . |
.Ss \&Fr |
.Ss \&Fr |
This macro is obsolete and not implemented in |
This macro is obsolete and ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
.Pp |
.Pp |
It was used to show function return values. |
It was used to show function return values. |
|
|
.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 |
|
|
and |
and |
.Sx \&Dt . |
.Sx \&Dt . |
.Ss \&Ot |
.Ss \&Ot |
This macro is obsolete and not implemented in |
This macro is obsolete and ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
.Pp |
.Pp |
Historical |
Historical |
|
|
.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 |
Line 2622 Table cell separator in |
|
Line 2626 Table cell separator in |
|
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 |
Line 3128 Manually switching the font using the |
|
Line 3115 Manually switching the font using the |
|
.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 |
Line 3238 certain list types. |
|
Line 3226 certain list types. |
|
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. |
Line 3256 in new groff and mandoc. |
|
Line 3244 in new groff and mandoc. |
|
.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 offset Cm 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 , |