Re: Clarifying instructions on linking man pages
On Sat, 21 Apr 2001 at 13:45:09 -0500, Chris Waters wrote:
> On Sat, Apr 21, 2001 at 06:57:48PM +0100, Colin Watson wrote:
> > A recent discussion on debian-mentors brought it to my attention
> > that packages frequently rely on an implementation detail of man:
> > that it holds a database of whatis entries and happens to be able to
> > find pages even if the file containing the man page has a different
> > name.
>
> "Implementation detail"? I'm pretty sure that's been a feature of
> every man program on every Unix-like system I've ever used, even such
> bletcherous and broken derivatives as Xenix. I suspect (though I
> haven't checked) that it's required by POSIX.
I don't have a copy of the relevant bit of POSIX; SuS doesn't appear to
specify much of anything about man pages, though.
> > The current implementation of all of this could be improved somewhat,
> > but that's not really the point. Since it's fundamentally a horrible
> > mess, I'd like to deprecate the practice of relying on man working this
> > out (very ... slowly ...)
>
> It is deprecated (albeit mildly). It says, "it is better to use a
> symbolic link than the .so feature".
I'm confused about what you're referring to. I'm not talking about the
.so feature, which is fine and will stay - I'm talking about putting
several names in the .SH NAME section without also putting them in the
filesystem as symlinks.
> In any case, the fact that many upstream (and non-debian) sources seem
> to rely on this means that if we remove the feature from man itself,
> we potentially break locally installed packages. IMO, that's a Very
> Bad Thing.
What I propose is to remove the *guarantee* that whatis references
magically work all the time, and to stop man updating them on the fly.
If the database happens to be up-to-date then I suppose there's no
reason not to use it, although it might cause interesting inconsistency
problems in pathological cases.
> I think the idea of replacing man with something which is similiar,
> but doesn't support all the features that people expect is even worse
> than the FSF's idea of trying to replace and dump man entirely. At
> this point, we're pretty much committed to using man, and not
> standardizing on texinfo. Let's stick with that decision, and support
> man, not a crippled derivative.
(I'm highly committed to keeping man and making it work well! :))
> Now, maybe we should try to encourage packages to use symlinks a
> little more firmly. I'd have no objections to that. What I do object
> to is throwing out the functionality entirely. A little delay once
> in a while may be annoying, but it doesn't actually hurt anyone, and
> it does seem to be standard.
>
> Prove me wrong (that this is standard, or at least widely expected as
> normal behavior) and I'll withdraw my objection.
Unless I'm seriously misreading the source to Andries Brouwer's man
implementation (used by most Linux distributions apart from us, SuSE,
and possibly one or two others), it uses *only* the filesystem when
searching for man pages, and doesn't go near the information held in .SH
NAME sections. In that implementation, only apropos and whatis use the
information in the whatis database, and accept that it might be out of
date; man just globs. In our implementation, man tries to use the whatis
database and guarantee that it's up-to-date all the time, and frankly
makes a total hash of it. I'd like to note that people shouldn't rely on
this behaviour, which I'm almost certain is specific to our
implementation.
Are we both talking about the same thing here?
--
Colin Watson [cjw44@flatline.org.uk]
Reply to: