For completeness, is there any requirement to mention how the -M command line option interacts here or should it just be assumed that this is the equivalent of setting MANPATH to the same value for the execution of the command (man/catman)?
Mike Gerdts wrote: > On Dec 13, 2007 12:55 AM, John Plocher <plocher at sac.sfbay.sun.com> 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... >> > > Based upon feedback received (thanks!), the spec has been updated with the > following changes: > > - Made it clear that legacy behavior is to be expected if MANPATH is > set. > - Add more detailed explanation of PATH to MANPATH transformation rules > - Reversed relative precedence of share/man vs. man to align with > filesystem(5). > - Added NOTE in man(1) that path transformations involving > <prefix>/share/man exist for legacy support reasons and refer to > filesystem(5) > - Add SEE ALSO in man(1) for filesystem(5). > - Clarify "Search Path" section of man(1) with regards to "man -M ..." > - Add Sections 4.6.2 and 4.6.3 to clarify changes or lack thereof for > catman(1M), whatis(1), and apropos(1). > > Updated spec follows: > > 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. > > To allow behavior that closely resembles the legacy behavior of > man(1), setting MANPATH and using name arguments that do not > contain the "/" character will not invoke any PATH to MANPATH > translations. > > 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. See below for details. > - The parent directory of the PATH directory with /man > appended. For example, /opt/VRTSvcs/bin becomes > /opt/VRTSvcs/man, assuming /opt/VRTSvcs/man exists. > - The parent directory of the PATH directory with /share/man > appended. For example, /usr/gnu/bin becomes > /usr/gnu/share/man because /usr/gnu/man does not exist. > > 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. > > The PATH to MANPATH transformations are as follows: > > PATH element MANPATH element > ---------------- ------------------------------- > /sbin /usr/share/man,1m > /usr/sbin /usr/share/man,1m > /usr/ucb /usr/share/man,1b > /usr/bin /usr/share/man,1,1m,1s,1t,1c,1f > /usr/xpg4/bin /usr/share/man,1 > /usr/xpg6/bin /usr/share/man,1 > > Sections within each directory are explicitely set to ensure proper > ordering of results for invocations such as "man -l", "man -a", > whatis(1), etc. > > The transformation rules are stored in a data structure within > man.c. The use of such a static mapping instead of a configuration > file is chosen based upon the following: > > - The rules to use <prefix>/man or <prefix>/share/man directories > will accomodate the vast majority of add-on software. > - The alternative would be to create a configuration file to > store the mappings. History has shown that providers of add-on > software do not do a good job of modifying configuration files > properly during installation and removal of software. In > contrast, add-on software providers can easily create > strategically placed symbolic links to trigger the automatic > <prefix>/man or <prefix>/share/man translation. > - Providing a command to update the configuration file would be > significant work for a presumably very small number of edge > cases. > - If demand is shown, a configuration file can be added with very > little rework in the future. > > A prototype of this behavior has been implemented and is available > for review at http://cr.opensolaris.org/~mgerdts/manpath-from-path/. > > 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(1M), and > apropos(1) which are all hard links to man(1). > > 4.6. Doc Impact > 4.6.1. man(1) manual page > > The man(1) manual 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 and the -M option is not > used, 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. > > SEE ALSO > apropos(1), cat(1), col(1), dpost(1), eqn(1), more(1), > nroff(1), refer(1), tbl(1), troff(1), vgrind(1), whatis(1), > catman(1M), attributes(5), environ(5), eqnchar(5), > filesystem(5), man(5), sgml(5), standards(5) > > NOTES > > When transforming PATH elements to MANPATH elements, man(1) > first attempts to transform <prefix>/bin or <prefix>/sbin to > <prefix>/man, as filesystem(5) indicates that add-on software > should use /opt/packagename/man for manual pages. In the > event that <prefix>/man does not exist but <prefix>/share/man > does exist, <prefix>/share/man will be searched. Searching > <prefix>/share/man is intended for legacy compatibility only. > > 4.6.2. catman(1M) manaul page changes > > The catman(1M) manual page will change as follows: > > 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. > > 4.6.3. Related manual pages not changing > > While the behavior of whatis(1) changes in the event that MANPATH > is not set or a relative or absolute 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. > > Similarly, the behavior of apropos(1) changes in the event that > MANPATH is not set. However, the man page for apropos(1) is > sufficiently vague to as to not require any changes to remain > accurate. apropos(1) indicates "apropos is actually just the -k > option to the man(1) command" and as such refers users to more > complete documentation. > >
