Subsequent to this message I also requested a code review on indiana-discuss[1] and Sam pinged a couple people on his end. Shawn Walker[2] and Stephen Hahn[3] offered some feedback which I have addressed and posted a new webrev[4].
1.http://mail.opensolaris.org/pipermail/indiana-discuss/2008-January/004260.html 2.http://mail.opensolaris.org/pipermail/indiana-discuss/2008-January/004290.html 3.http://mail.opensolaris.org/pipermail/opensolaris-code/2008-January/006770.html 4.http://cr.opensolaris.org/~mgerdts/manpath-from-path/ The latest revision is cstyle clean and introduces no new complaints from lint. Thanks for the reviews! Mike On Jan 6, 2008 7:04 PM, Mike Gerdts <[EMAIL PROTECTED]> wrote: > The timing of my previous code review request was particularly bad due > to the holidays. I would appreciate it if I could get a few eyes on > the code so that it can get integrated. I have not updated the > copyright date from my previous request and am not aware of any other > required changes. > > Thanks in advance, > Mike > > > > On Dec 19, 2007 9:40 PM, Mike Gerdts <[EMAIL PROTECTED]> wrote: > > I have posted an updated webrev for: > > > > PSARC/2007/688 manwhich: Deriving MANPATH from PATH > > 6634079 man should take hints from PATH when MANPATH not set > > > > at http://cr.opensolaris.org/~mgerdts/manpath-from-path/. > > > > I'm posting the code review request just a few hours before the > > FastTrack ARC review expires and as such the case materials have not > > been posted yet. When they are available, they will be at > > http://opensolaris.org/os/community/arc/caselog/2007/688/. > > > > Since there are man page changes, I could use some guidance as to how > > I go about getting them in place. Should I be working with the docs > > community and providing diffs to the *roff source? Or is there some > > magic queue that I submit the relevant spec section to and some *roff > > wizard takes over? > > > > The latest edition of the spec appears below. > > > > 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: > > 4.1.1. Transformations > > The source file man.c will be enhanced to refer to PATH only in the > > absence of MANPATH. Each element of PATH will be transformed based > > into the appropriate MANPATH element based upon the following > > priorities: > > > > - Explicit transformation rule. For example, /usr/ucb in PATH > > transforms 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. > > > > 4.1.2. New option to print effective MANPATH > > To facilitate debugging and to provide a means for users to augment > > the derived MANPATH the -p (mnemonic: print MANPATH) option will be > > added. When "man -p" is invoked with no name options, the output > > will be suitable for use as part of a user's MANPATH environment > > variable. For example a user may choose to have a .profile with > > the following: > > > > PATH=/usr/bin:/usr/gnu/bin:/usr/sbin:/usr/ucb > > export PATH > > unset MANPATH > > MANPATH=`man -p`:$HOME/myman > > export MANPATH > > > > This provides the ability to leverage the derived MANPATH without > > having to sacrifice the ability to use man directories that have no > > associated bin directory or would otherwise be missed by standard > > transformation rules. > > > > 4.1.3. Prototype > > A prototype of this behavior (sans -p option) 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. > > > > OPTIONS > > The following options are supported: > > > > . . . > > > > -M path Specifies an alternate search path for > > . . . > > one for each section. This option over- > > rides the MANPATH environment variable > > and any MANPATH derived from PATH for > > operands that do not have a '/' > > character. > > > > -p Prints the effective MANPATH. If no name > > operands are used, the MANPATH used to > > search for name operands without a '/' > > character is displayed in a format > > suitable for use as the MANPATH > > environment variable. If one or more > > name operands is used, each name operand > > and its associated effective MANPATH are > > printed. One line of output exists for > > each name operand. > > > > . . . > > > > 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. > > > > . . . > > > > EXAMPLES > > > > . . . > > > > Example 3 Displaying the man page for /usr/ucb/ps > > > > The following example displays the man page for > > /usr/ucb/ps, regardless of the values of MANPATH and > > PATH. > > > > man /usr/ucb/ps > > > > This is an alternative to using the -l option to find all > > man pages for ps then selecting the one most likely to > > correspond to /usr/ucb/ps. > > > > Example 4 Setting shell using customized derived MANPATH > > > > The following example shows commands that can be added to > > profile(4) to use the MANPATH derived from PATH in > > addition to man directories not associated with PATH > > directories. > > > > PATH=/usr/bin:/usr/gnu/bin:/usr/ucb > > export PATH > > unset MANPATH > > MANPATH=`man -p`:$HOME/myman > > export MANPATH > > > > The environment created using this example will derive > > MANPATH once and subsequent invocations of man(1) will > > use the value in the MANPATH environment variable. > > > > 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), profile(4), attributes(5), environ(5), > > eqnchar(5), filesystem(5), man(5), sgml(5), standards(5) > > > > NOTES > > > > When deriving 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: > > > > DESCRIPTION > > > > . . . > > > > catman also creates the windex database file in the direc- > > tories specified by the MANPATH, the -M option, or MANPATH > > derived from PATH. The windex database file is a three > > . . . > > > > OPTIONS > > . . . > > > > -M directory Update manual pages located in the > > specified directory (see "Search Path" > > in man(1) for default). If the -M > > option is specified, the directory > > argument must not contain a `,' (comma), > > since a comma is used to delineate > > section numbers. See man(1). > > > > > > 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. > > > > > > -- > > Mike Gerdts > > http://mgerdts.blogspot.com/ > > > > > > -- > Mike Gerdts > http://mgerdts.blogspot.com/ > -- Mike Gerdts http://mgerdts.blogspot.com/ _______________________________________________ opensolaris-code mailing list [email protected] http://mail.opensolaris.org/mailman/listinfo/opensolaris-code
