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
