The man utility shall write information about each of the name
operands. If name is the name of a standard
utility, man at a minimum shall write a message describing the
syntax used by the standard utility, its options, and
operands. If more information is available, the man utility
shall provide it in an implementation-defined manner.
An implementation may provide information for values of name
other than the standard utilities. Standard utilities that
are listed as optional and that are not supported by the implementation
either shall cause a brief message indicating that fact to
be displayed or shall cause a full display of information as described
previously.
The man utility shall conform to the Base Definitions volume
of IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
The following option shall be supported:
|
|
|
-k
|
Interpret name operands as keywords to be used in searching
a utilities summary database that contains a brief purpose
entry for each standard utility and write lines from the summary database
that match any of the keywords. The keyword search shall
produce results that are the equivalent of the output of the following
command:
grep -Ei ’
name
name...
|
|
This assumes that the summary-database is a text file with a
single entry per line; this organization is not required and
the example using grep -Ei is merely illustrative of the
type of search
intended. The purpose entry to be included in the database shall consist
of a terse description of the purpose of the utility.
The man utility shall write text describing the syntax of the
utility name, its options and its operands, or, when
-k is specified, lines from the summary database. The format
of this text is implementation-defined.
It is recognized that the man utility is only of minimal usefulness
as specified. The opinion of the standard developers
was strongly divided as to how much or how little information man
should be required to provide. They considered, however,
that the provision of some portable way of accessing documentation
would aid user portability. The arguments against a fuller
specification were:
|
|
|
*
|
Large quantities of documentation should not be required on a system
that does not have excess disk space.
|
|
*
|
The current manual system does not present information in a manner
that greatly aids user portability.
|
|
*
|
A "better help system" is currently an area in which vendors feel
that they can add value to their POSIX implementations.
|
|
The -f option was considered, but due to implementation differences,
it was not included in this volume of
IEEE Std 1003.1-2001.
The description was changed to be more specific about what has to
be displayed for a utility. The standard developers considered
it insufficient to allow a display of only the synopsis without giving
a short description of what each option and operand
does.
The "purpose" entry to be included in the database can be similar
to the section title (less the numeric prefix) from this
volume of IEEE Std 1003.1-2001 for each utility. These titles are
similar to those used in historical systems for this
purpose.
See mailx for rationale concerning the default paginator.
The caveat in the LC_CTYPE description was added because it
is not a requirement that an implementation provide reference
pages for all of its supported locales on each system; changing LC_CTYPE
does not necessarily translate the reference page
into another language. This is equivalent to the current state of
LC_MESSAGES in
IEEE Std 1003.1-2001-locale-specific messages are not yet a requirement.
The historical MANPATH variable is not included in POSIX because
no attempt is made to specify naming conventions for
reference page files, nor even to mandate that they are files at all.
On some implementations they could be a true database, a
hypertext file, or even fixed strings within the man executable.
The standard developers considered the portability of
reference pages to be outside their scope of work. However, users
should be aware that MANPATH is implemented on a number of
historical systems and that it can be used to tailor the search pattern
for reference pages from the various categories (utilities,
functions, file formats, and so on) when the system administrator
reveals the location and conventions for reference pages on the
system.
The keyword search can rely on at least the text of the section titles
from these utility descriptions, and the implementation
may add more keywords. The term "section titles" refers to the strings
such as:
man - Display system documentation
ps - Report process status
