Junio C Hamano <gitster@xxxxxxxxx> writes: > Sergei Organov <osv@xxxxxxxxx> writes: > >> Johannes Schindelin <Johannes.Schindelin@xxxxxx> 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. Probably. > > 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. This sounds nice to me. Do you want me to re-submit the patch with modified commit message? > > 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"). First, I don't think you need to clarify like this. It is just implementation detail of git-help that it uses 'man', and thus implicitly relies on MANPATH. The essential thing has been already stated above: git-help should show correct documentation. Second, the change is still useful even if user did put custom path to 'git' into its PATH, but didn't even thought of customizing MANPATH. Besides, a user could be entirely unaware of 'man' the utility. > When you clarify it this way, the change does not look as useful > anymore, does it? Yes, it still does, I think. I doubt it's that obvious that 'git help' uses MANPATH at all. Besides, it's not 'git man', isn't it? To further emphasize my point, we don't require user to tweak MANPATH in order to get corresponding 'git --help' output, isn't it? Also, please look here: $ ~/git/bin/git help -a | head -n 3 | tail -n 1 available git commands in '/home/osv/git/bin' $ git help -a | head -n 3 | tail -n 1 git commands available in '/usr/bin' $ And the last, basing on the same arguments, it's not that useful that 'git xxx' invokes correct 'git-xxx' command by prepending installation path to the PATH, isn't it? Overall, I just want 'git help' to behave consistently. > How typical would that use be, to run your git executable by always > naming it by path without relying on $PATH environment variable? To tell the truth, I'd prefer to just use -M option of man and don't rely on MANPATH at all, so that 'git help' will issue error if there is no documentation installed for this particular version of git. [BTW, git-help lacks his own man page, so I can't actually argue on a ground of some documentation of git-help.] -- Sergei. - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
