On Dec 13, 2007 12:55 AM, John Plocher <plocher at sac.sfbay.sun.com> wrote:
> I am ARC-sponsoring this fasttrack from Mike Gerdts, an
> OpenSolaris community member. Mike is finding someone else
> to be his code/putback sponsor...
Based upon feedback received (thanks!), the spec has been updated with the
following changes:
- Made it clear that legacy behavior is to be expected if MANPATH is
set.
- Add more detailed explanation of PATH to MANPATH transformation rules
- Reversed relative precedence of share/man vs. man to align with
filesystem(5).
- Added NOTE in man(1) that path transformations involving
<prefix>/share/man exist for legacy support reasons and refer to
filesystem(5)
- Add SEE ALSO in man(1) for filesystem(5).
- Clarify "Search Path" section of man(1) with regards to "man -M ..."
- Add Sections 4.6.2 and 4.6.3 to clarify changes or lack thereof for
catman(1M), whatis(1), and apropos(1).
Updated spec follows:
2. Project Summary
2.1. Project Description:
When projects such as Indiana or individuals customize PATH,
MANPATH is often left unset. This leads to confusion because man(1)
will display the manual page for the wrong variant of a command.
For example, if /usr/gnu/bin is at the front of the path, the
default behavior of man(1) would most appropriately be to display a
manual page from /usr/gnu/share/man rather than /usr/share/man.
Similar, but slightly more complex, considerations are made for
/usr/ucb and for invocations of man(1) that specify the path to the
executable for which a man page is sought.
2.2. Risks and Assumptions:
Traditional behavior and expectation is that /usr/share/man is the
only directory searched in the case that the MANPATH environment
variable is undefined. This behavior is documented in the man page
for man.
To allow behavior that closely resembles the legacy behavior of
man(1), setting MANPATH and using name arguments that do not
contain the "/" character will not invoke any PATH to MANPATH
translations.
4. Technical Description:
4.1. Details:
The source file man.c will be enhanced to refer to PATH only in the
absence of MANPATH. Each element of PATH will be translated based
into the appropriate MANPATH element based upon the following
priorities:
- Explicit transformation rule. For example, /usr/ucb in PATH
translates to /usr/share/man,1b. See below for details.
- The parent directory of the PATH directory with /man
appended. For example, /opt/VRTSvcs/bin becomes
/opt/VRTSvcs/man, assuming /opt/VRTSvcs/man exists.
- The parent directory of the PATH directory with /share/man
appended. For example, /usr/gnu/bin becomes
/usr/gnu/share/man because /usr/gnu/man does not exist.
In addition and higher precedence to the above, if man is invoked
referring to particular instance of a command (e.g. "man ./ls" or
"man /usr/ucb/ps") the path transformation rules are applied using
the directory component of the argument.
In all cases where MANPATH is not defined and the path to a command
is not specified /usr/share/man will be appended to MANPATH if it
is not otherwise included based upon PATH transform rules. This
ensures that sections other than 1* are accessible.
The PATH to MANPATH transformations are as follows:
PATH element MANPATH element
---------------- -------------------------------
/sbin /usr/share/man,1m
/usr/sbin /usr/share/man,1m
/usr/ucb /usr/share/man,1b
/usr/bin /usr/share/man,1,1m,1s,1t,1c,1f
/usr/xpg4/bin /usr/share/man,1
/usr/xpg6/bin /usr/share/man,1
Sections within each directory are explicitely set to ensure proper
ordering of results for invocations such as "man -l", "man -a",
whatis(1), etc.
The transformation rules are stored in a data structure within
man.c. The use of such a static mapping instead of a configuration
file is chosen based upon the following:
- The rules to use <prefix>/man or <prefix>/share/man directories
will accomodate the vast majority of add-on software.
- The alternative would be to create a configuration file to
store the mappings. History has shown that providers of add-on
software do not do a good job of modifying configuration files
properly during installation and removal of software. In
contrast, add-on software providers can easily create
strategically placed symbolic links to trigger the automatic
<prefix>/man or <prefix>/share/man translation.
- Providing a command to update the configuration file would be
significant work for a presumably very small number of edge
cases.
- If demand is shown, a configuration file can be added with very
little rework in the future.
A prototype of this behavior has been implemented and is available
for review at http://cr.opensolaris.org/~mgerdts/manpath-from-path/.
4.3. In Scope:
Described above.
4.4. Out of Scope:
GNU utilities often times provide only stub man pages and more
complete documentation using an alternative format known as "info".
While translators from info to man do exist, this project does not
seek to bridge this gap.
4.5. Interfaces
The interface stability of man(1) is documented as "Standard"
("Comitted", in updated terminology). This project alters the
documented "Search Path" behavior when MANPATH is not set.
This project also extends the documented interface to man(1) such
that "name" arguments that specify a fully qualified or relative
path (with at least one '/' character) alter the documented "Search
Path" behavior.
Corresponding interface changes apply to whatis(1), catman(1M), and
apropos(1) which are all hard links to man(1).
4.6. Doc Impact
4.6.1. man(1) manual page
The man(1) manual page will be enhanced as follows.
OPERANDS
The following operand is supported:
name The name of a standard utility or a keyword. If the
name contains a '/' character, the search path (See
"Search Path") is altered to search only the man
directory corresponding to the name argument. For
example, if name is "/usr/ucb/ps" man will behave as
if the MANPATH environment variable is set to
/usr/share/man,1b.
. . .
Search Path
Before searching for a given name, man constructs a list of
candidate directories and sections. man searches for name in
the directories specified by the MANPATH environment vari-
able. If this variable is not set and the -M option is not
used, a substitute MANPATH is constructed based upon the
PATH environment variable. In all cases, except as described
above when the name operand has a "/" character,
/usr/share/man is searched.
For each name operand that contains a "/" character, neither
MANPATH nor PATH are used to construct the search path.
. . .
ENVIRONMENT VARIABLES
. . .
MANPATH A colon-separated list of directories; each
directory can be followed by a comma-separated
list of sections. If set, its value overrides
the default directory search path, and man.cf as
the default section search path. The -M and -s
flags, in turn, override these values. The
default directory search path is constructed
based upon the contents of the PATH environment
variable with /usr/share/man appended, as
necessary.
PATH The search path for commands. If MANPATH is not
set, MANPATH is derived from PATH.
SEE ALSO
apropos(1), cat(1), col(1), dpost(1), eqn(1), more(1),
nroff(1), refer(1), tbl(1), troff(1), vgrind(1), whatis(1),
catman(1M), attributes(5), environ(5), eqnchar(5),
filesystem(5), man(5), sgml(5), standards(5)
NOTES
When transforming PATH elements to MANPATH elements, man(1)
first attempts to transform <prefix>/bin or <prefix>/sbin to
<prefix>/man, as filesystem(5) indicates that add-on software
should use /opt/packagename/man for manual pages. In the
event that <prefix>/man does not exist but <prefix>/share/man
does exist, <prefix>/share/man will be searched. Searching
<prefix>/share/man is intended for legacy compatibility only.
4.6.2. catman(1M) manaul page changes
The catman(1M) manual page will change as follows:
ENVIRONMENT VARIABLES
. . .
MANPATH A colon-separated list of directories; each
directory can be followed by a comma-separated
list of sections. If set, its value overrides
the default directory search path, and man.cf as
the default section search path. The -M and -s
flags, in turn, override these values. The
default directory search path is constructed
based upon the contents of the PATH environment
variable with /usr/share/man appended, as
necessary.
PATH The search path for commands. If MANPATH is not
set, MANPATH is derived from PATH.
4.6.3. Related manual pages not changing
While the behavior of whatis(1) changes in the event that MANPATH
is not set or a relative or absolute command path provided, the
whatis(1) man page is sufficiently vague as to not require any
changes to remain accurate. whatis(1) indicates that it is
equivalent to "the -f option of the man(1) command" and as such
refers users to more complete documentation.
Similarly, the behavior of apropos(1) changes in the event that
MANPATH is not set. However, the man page for apropos(1) is
sufficiently vague to as to not require any changes to remain
accurate. apropos(1) indicates "apropos is actually just the -k
option to the man(1) command" and as such refers users to more
complete documentation.
--
Mike Gerdts
http://mgerdts.blogspot.com/
