manwhich: Deriving MANPATH from PATH [PSARC/2007/688 FastTrack timeout 12/19/2007]
John Plocher
plocher at sac.sfbay.sun.com
Wed Dec 12 22:55:34 PST 2007
I am ARC-sponsoring this fasttrack from Mike Gerdts, an
OpenSolaris community member. Mike is finding someone else
to be his code/putback sponsor...
Binding is to a minor release of the ON consolidation.
As mentioned in 4.5 below:
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(1),
and apropos(1) which are all hard links to man(1).
-John
Template Version: @(#)sac_nextcase 1.64 07/13/07 SMI
This information is Copyright 2007 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
manwhich: Deriving MANPATH from PATH
1.2. Name of Document Author/Supplier:
Author: Mike Gerdts
1.3 Date of This Document:
12 December, 2007
4. Technical Description
1. Introduction
1.1. Project/Component Working Name:
manwhich: Deriving MANPATH from PATH
1.2. Name of Document Author/Supplier:
Mike Gerdts <mgerdts at gmail.com>
OpenSolaris Contributor ID OS0018
1.3. Date of This Document:
12/12/2007
1.4. Name of Major Document Customer(s)/Consumer(s):
1.4.1. The Community you expect to review your project:
ON
1.4.2. The ARC(s) you expect to review your project:
OpenSolaris ARC
1.5. Email Aliases:
1.5.2. Responsible Engineer:
Mike Gerdts <mgerdts at gmail.com>
1.5.4. Interest List:
opensolaris-code at opensolaris.org
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.
3. Business Summary
3.1. Problem Area:
This project increases the usability of online help accessed through
the command line. History has shown that end-users have little
success in keeping MANPATH in sync with PATH.
3.2. Market/Requester:
Users and developers who wish to learn how to use the commands and
utilities found in OpenSolaris.
3.3. Business Justification:
As more FOSS functionality is added to various parts of OpenSolaris
and its distros, keeping individual user's MANPATHs up to date gets
harder and harder. This project effectively removes the
requirement for most users to even bother setting it in the first
place.
3.4. Competitive Analysis:
Various Linux and *BSD distros provide similar or related
mechanisms.
3.5. Opportunity Window/Exposure:
// Time-to-market window, if any, and precision.
3.6. How will you know when you are done?:
When the user has "unset MANPATH", "man foo" will find the man page
associated with foo as determined by the user's PATH setting.
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.
- The parent directory of the PATH directory with /share/man
appended. For example, /usr/gnu/bin becomes
/usr/gnu/share/man.
- The parent directory of the PATH directory with /man
appended. For example, /opt/VRTSvcs/bin becomes
/opt/VRTSvcs/man because /opt/VRTSvcs/share/man does not exist
but /opt/VRTSvcs/man does.
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.
A prototype of this behavior has been implemented and is available
for review at http://cr.opensolaris.org/~mgerdts/manpath-from-path/.
4.2. Bug/RFE Number(s):
6634079 man should take hints from PATH when MANPATH not set
6516767 RFE:/etc/profile should set ${MANPATH} to
${PATH}/${LANG}-related value
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(1), and
apropos(1) which are all hard links to man(1).
4.6. Doc Impact:
man(1) man 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, 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.
While the behavior of whatis changes in the event that a relative
or absoluate 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.
4.7. Admin/Config Impact:
On systems without MANPATH explicitly set by the administrator, but
with customized PATH, man(1) may provide results that are more
likely to be correct for the users' environments. The system
administration overhead for "more correct" behavior of man is thus
reduced.
4.8. HA Impact:
None.
4.9. I18N/L10N Impact:
Aside from man pages mentioned above, none. No error or usage
strings are added modified or added.
4.10. Packaging & Delivery:
No impact.
4.11. Security Impact:
No impact.
4.12. Dependencies:
None.
5. Reference Documents:
6634079 man should take hints from PATH when MANPATH not set
This CR was opened as a means for tracking this specific change.
Absent from the scope of this CR is the behavior if the name
operand contains a / character.
http://mail.opensolaris.org/pipermail/opensolaris-code/2007-November/006390.html
Initial discussion of this functionality and initial code review
of prototype.
6. Resources and Schedule:
6.1. Projected Availability:
December, 2007.
6.2. Cost of Effort:
One to two people-months of part-time work.
6.4. Product Approval Committee requested information:
6.4.1. Consolidation or Component Name:
ON
6.4.7. Target RTI Date/Release:
Build 81, 82, or 83 (December 2007 - January 2008)
6.4.8. Target Code Design Review Date:
December 13, 2007
6.5. ARC review type:
FastTrack
6.6. ARC Exposure: open
6.6.1. Rationale: Part of OpenSolaris
7. Prototype Availability:
7.1. Prototype Availability:
prototype available December 12, 2007 at
http://cr.opensolaris.org/~mgerdts/manpath-from-path/. This
prototype offers nearly complete functionality.
7.2. Prototype Cost:
2 part-time programmer-weeks.
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
More information about the opensolaris-arc
mailing list