On Dec 1, 2007 7:41 PM, John Plocher <[EMAIL PROTECTED]> wrote: > > > Mike Gerdts wrote: > > Draft one-pager follows. > > Ah, something I can help with! I'd be happy to ARC-sponsor > this for you when you are ready.
Thanks! Since you offered most recently with the most feedback, I'll take you up on your offer. I'll send a separate request off to request-sponsor to get everything set up on that side. I've incorporated the feedback you offered and updated the webrev[1]. I think that the the functionality is complete and ready for review[2], assuming the ARC case doesn't mandate changes. 1. http://cr.opensolaris.org/~mgerdts/manpath-from-path/ 2. I just realized that I forgot to update the copyright date. 1. Introduction 1.1. Project/Component Working Name: manwhich: Deriving MANPATH from PATH 1.2. Name of Document Author/Supplier: Mike Gerdts <[EMAIL PROTECTED]> 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 <[EMAIL PROTECTED]> 1.5.4. Interest List: [email protected] 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. -- Mike Gerdts http://mgerdts.blogspot.com/ _______________________________________________ opensolaris-code mailing list [email protected] http://mail.opensolaris.org/mailman/listinfo/opensolaris-code
