manwhich: Deriving MANPATH from PATH [PSARC/2007/688 FastTrack timeout 12/19/2007]

[Mike Gerdts]

On Dec 13, 2007 2:48 PM, Joseph Kowalski <jek3 at sun.com> wrote:
> Mike Gerdts wrote:
> > On Dec 13, 2007 1:43 PM, Joseph Kowalski <jek3 at sun.com> wrote:
> >
> >> We could just add a link "man -> ./share/man" as needed.
> >>
> >
> > The /usr/man -> share/man link does exist today and is documented in
> > filesystem(5).  I'm not sure that I am ready to take on filesystem(5)
> > today.
> >
> Opps.  I was trying to *not* search "../share/man" based on the PATH
> setting.
> >
> >> That's what I'd like.
> >>
> >> However, I'd accept wording on the man(1) (and related) pages that
> >> highlighted
> >> that the second set above is just a legacy/convenience thing.  We don't
> >> want to
> >> validate the practice of sprinkling "share" directories around.
> >>
> I can't find a clear response here...   :-)

The use of share/man rather than man was on  the recommendation of
Darren Moffat.

http://mail.opensolaris.org/pipermail/opensolaris-code/2007-November/006394.html

Subsequent reading of filesystem(5) suggests that third parties should
be creating /opt/something/man, not /opt/something/share/man.  As
such, it seems to make sense use man as the default and share/man as
the fallback.  share/man as a fallback is an important part because
there is misunderstanding, even among those at Sun, as to where things
really belong.

> >> Also, along this line, shouldn't the algorithm reverse the priority of
> >> steps #2 and #3?
> >>
> >
> > This working in filesystem(5) suggests it may be the right thing to
> > do.  Unfortunately, those that created /usr/gnu/{bin,share/man} didn't
> > take it into consideration:
> >
> >      /usr/share/man
> >
> >          Platform-independent sharable manual pages. An  approved
> >          installation  location for bundled Solaris software. The
> >          analogous location for add-on  system  software  or  for
> >          applications is /opt/packagename/man.
> >
> > Given that there is now more focus on adding to /usr/bin rather than
> > adding more directories like /usr/sfw and /usr/gnu, there should be
> > relatively few *Solaris directories that subscribe to share/man.
> > Since third parties should be installing software to /opt/packagename
> > with /opt/packagename/man as the man directory, reversing the search
> > order to prefer man over share/man seems appropriate.
> >
> Great!  (Now lets resolve if ../share/man should even be in the algorithm.)

Per above, share/man belongs for usability reasons.

> >> Finally, for this proposal to be complete, I think you need to enumerate
> >> the cases
> >> handled by #1 (the explicit translation rules).  I doubt they are
> >> controversial, but
> >> they should be enumerated for completeness.
> >>
> >
> > The mapping is...
> >
> > /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
> >
> I'm not sure I'm getting it.  These are absolute paths.  These
> transforms don't apply to any random PATH/../man searches, right?
>
> To make this clear, given the PATH:
>
>     /usr/bin:/usr/sbin:/usr/ucb
>
> There would be no effective change due to this proposal.

Correct.

>
>     /usr/sbin:/usr/bin:/usr/ucb
>
> Would only change the priority of a page under (1M) over (1) (but
> hopefully we try not to do that).

Hopefully such collisions do not exist.  If they do, the man page you
get will refer to the page for the command in /usr/sbin, assuming a 1m
page exists.

>
>     /usr/ucb:/usr/bin:/usr/sbin
>
> Would display "ucb" pages with preference.

Correct.

>
> The PATH:
>
>     /opt/mumble/bin:/usr/bin
>
> Would be effective:
>
>     /opt/mumble/bin/../man:/opt/mumble/bin/../share/man:/usr/share/man
>
> (with the bin/../share/man entry still being discussed)

No - if stat(/opt/mumble/man, ...) returns 0, /opt/mumble/share/man is
not added.  If /opt/mumble/man exists, the effective MANPATH would be:

/opt/mumble/man:/usr/share/man

If /opt/mumble/man does not exist but /opt/mumble/share/man does:

/opt/mumble/share/man:/usr/share/man

>
> Right?

Amost.  :)
>
> ------- next topic ------
>
> Is the explicit list of /usr/bin subsections a good idea?  Everytime a
> new subsection was added, it would require a change to the man command.
> I also suspect that this limitation may be an incompatible change in
> behavior - currently an empty MANPATH value doesn't restrict the
> subsections.

Suppose:

PATH=/usr/bin:/usr/gnu/bin:/usr/ucb

By listing the sections for /usr/bin:

$ man -l ls
ls (1)  -M /usr/share/man
ls (1)  -M /usr/gnu/share/man
ls (1b) -M /usr/share/man

Similar for "man -a".  Otherwise ls(1b) would show up in the output early.

Thanks for your feedback!

-- 
Mike Gerdts
http://mgerdts.blogspot.com/