Re: [PATCH] Let git-help prefer man-pages installed with this version of git

[Junio C Hamano <gitster@pobox.com>]

Sergei Organov <osv@javad.com> writes:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>
>> On Thu, 6 Dec 2007, Sergei Organov wrote:
>>
>>> Prepend $(prefix)/share/man to the MANPATH environment variable before 
>>> invoking 'man' from help.c:show_man_page().
>>
>> This commit message is severely lacking.  Why would you _ever_ prefer the 
>> installed man pages before invoking "man", which should find them
>> anyway?
>
> Obviously because you want manual pages corresponding to the version of
> git you are invoking, not any random version of man-pages man may find
> by default.

While I almost agree with the rest of your sentence, you have to realize
that it is obviously not obvious if somebody asked you to clarify.

How about this:

    Prepend $(prefix)/share/man to the MANPATH environment variable
    before invoking 'man' from help.c:show_man_page().  There may be
    other git documentation in the user's MANPATH but the user is asking
    a specific instance of git about its own documentation, so we'd
    better show the documentation for _that_ instance of git.

Having written that, it is very tempting to further clarify the above:

    Usually, if a user has his own version of git and regularly uses it
    by having the non-system executable directory (e.g. $HOME/bin/git)
    early in his $PATH, its corresponding documentation would also be in
    a non-system documentation directory (e.g. $HOME/man) early in his
    $MANPATH, and this change is a no-op.  The only case this change
    matters is where the user installs his own git outside of his $PATH
    and $MANPATH, and explicitly runs his git executable
    (e.g. "$HOME/junk/git-1.5.4/bin/git diff").

When you clarify it this way, the change does not look as useful
anymore, does it?  How typical would that use be, to run your git
executable by always naming it by path without relying on $PATH
environment variable?