I have posted a fresh webrev of my efforts to derive MANPATH from PATH. New in this revision:
- Remove the need for an extra pass through PATH before processing MANPATH. - Get rid of most calls to realpath() and instead compare device and inode to get rid of duplicates. - Allow special cases such as /usr/ucb -> /usr/share/man,1b and /usr/xpg4/bin -> /usr/share/man. - Add the ability to do stuff like "man /usr/gnu/bin/ls" and even "cd /usr/ucb ; man ./ps". Ephasis so far has been on correct behavior of typical man usage and I haven't given a whole lot of time/thought to apropos, catman, whatis, or invocations such as "man -k /usr/ucb/ps" Webrev at: http://cr.opensolaris.org/~mgerdts/manpath-from-path/ Previous discussion at: http://mail.opensolaris.org/pipermail/opensolaris-code/2007-November/006390.html Draft one-pager follows. This information is Copyright 2007 Sun Microsystems This information is Copyright 2007 Mike Gerdts 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/01/2007 1.4. Name of Major Document Customer(s)/Consumer(s): 1.4.1. The Community you expect to review your project: 1.4.2. The ARC(s) you expect to review your project: // Leave blank if you don't have any preference // This item is advisory only 1.5. Email Aliases: 1.5.2. Responsible Engineer: 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: // Who needs the project? 3.3. Business Justification: // Why is it important or valuable to do this project? 3.4. Competitive Analysis: // Who are the current and anticipated players in this market? 3.5. Opportunity Window/Exposure: // Time-to-market window, if any, and precision. 3.6. How will you know when you are done?: // What will you measure to determine that the project is complete? // // This section is for explicit measurable customer CTQs that apply // to this specific feature proposal, not to the product as a whole. // // We *expect* every development team to meet their Feature, // Performance and Security and Testing goals, as well as getting // all required ARC and PAC review approvals, so don't put that // sort of metric here. 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 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) 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 MANPATH 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. . . . Corresponding changes are appropriate for catman(1), whatis(1), and apropos(1). 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: // Order of magnitude people and time for the *whole* project, not // just the development engineering part. // You may wish to split the estimate between feature // implementation, implementing adminsitrative Interfaces, unit // tests, documentation, support training material, i18n, etc. 6.4. Product Approval Committee requested information: 6.4.1. Consolidation or Component Name: 6.4.7. Target RTI Date/Release: // List target release & build and/or date. // RTI = Request to Integrate - when does *this* project // expect to be ready to integrate its changes back into // the master source tree? We are not asking when the // component wants to ship, but instead, when the // gatekeeper/PM needs to expect your changes to show up. // examples: S8u7_1, S9_45, Aug 2002... 6.4.8. Target Code Design Review Date: 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: Second pass of prototype available December 1, 2007 at http://cr.opensolaris.org/~mgerdts/manpath-from-path/. This prototype offers nearly complete functionality. 7.2. Prototype Cost: // Subset of Cost of Effort to leave "prototype" stage. -- Mike Gerdts http://mgerdts.blogspot.com/ _______________________________________________ opensolaris-code mailing list [email protected] http://mail.opensolaris.org/mailman/listinfo/opensolaris-code
