manwhich: Deriving MANPATH from PATH [PSARC/2007/688 FastTrack timeout 12/19/2007]
Alan Coopersmith
alan.coopersmith at sun.com
Mon Dec 17 16:50:31 PST 2007
It would seem simpler (from the user perspective at least,
not sure about the code) if you could insert a value into the
$MANPATH to add the automatic paths at that point, so your
example would reduce to something more like:
MANPATH=auto:<my extra junk>
though a --found-dynamic-manpath-search-directories would be
useful for debugging purposes.
-Alan Coopersmith- alan.coopersmith at sun.com
Sun Microsystems, Inc. - X Window System Engineering
Edward Pilatowicz wrote:
> i really like the suggested manpatch search mechanism.
> it should make the management of manpath much easier.
>
> that said, currently i have some MANPATH entries (ie,
> entries in my MANPATH environment variable) which aren't
> associated with any PATH entries. so to switch to this
> new mechanism i'd have to drop these entries. so what
> i was wondering is would it be possible to have some
> new man(1) cli option that would display the current
> dynamic man search path in the format of a MANPATH variable?
> this would allow me to do something like the following
> in my profile:
>
> PATH="<my_desired_path>
> unset MANPATH
> MANPATH=`man --found-dynamic-manpath-search-directories`
> MANPATH=$MANPATH:<my extra junk>
> export MANPATH
>
> thoughts?
> ed
>
> On Wed, Dec 12, 2007 at 10:55:34PM -0800, John Plocher 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...
>>
>> 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
>>
>> _______________________________________________
>> opensolaris-arc mailing list
>> opensolaris-arc at opensolaris.org
More information about the opensolaris-arc
mailing list