Re: [RFC PATCH] git-help: find library man pages again

From: Michael J Gruber <git@drmicha.warpmail.net>
Date: Sep 2, 2010, 09:09 UTC
Message-ID: <4C7F69D7.9030304@drmicha.warpmail.net>
In-Reply-To: <20100902085533.GL29713@burratino>

Jonathan Nieder venit, vidit, dixit 02.09.2010 10:55:

Show 40 quoted lines

> Michael J Gruber wrote:
>> Jonathan Nieder venit, vidit, dixit 02.09.2010 10:16:
> 
>>> Therefore this seems wrong to me (except as a backward-compatibility
>>> measure).
> [...]
>> One heuristic, which I would have left for a later patch because of its
>> radicality (and I think we're in some phase of some rc something), is to
>> simply not do any checks when calling the viewers. This requires that
>> everything is prepended with "git-", which I see you have done in
>> builtin/help.c.
> 
> Yep, I agree with you in all respects, including the need to do
> something else (like the patch you sent) for v1.7.3.
> 
>> Still, none-command help pages will not show up with
>> "git help -a". So it's not a complete solution.
> 
> I think of "git --help -a" as a more complete version of the list
> from "git --help" --- that is, it is explaining what subcommands are
> available for git.
> 
> On the other hand, on platforms where "man -k git" is not available,
> as you mention it is the index to the manual.  Maybe "git help" should
> check GIT_HTML_PATH to provide a more complete index on such platforms.
> 
> Just musing.
> 
>> Alternatively, load_command_list() etc. could simply fill up a third
>> list "other_pages" (with non-executables) so that "git help -a" could
>> list "other help pages" in addition to the commands. I don't think this
>> would require any renaming nor Documentation updates.
> 
> Looks like you had a similar thought.
> 
>> ??? I guess this patch makes sense only after a patch which renames all
>> gitfoo.txt to git-foo.txt.
> 
> Well, there were ulterior motives to that patch: I keep on mistyping
> half-hyphenated manpage names like gitcvs-migration.

That's exactly why I use "git help foo" rather than "man git[-]?foo" and want it to Just Work (TM);)

> I should have included some appropriate Makefile magic for
> compatibility symlinks for the old names.  Hopefully at least the idea
> was clear.

I was just wondering what this patch applies to - you must have all-dashed documentation to begin with. And I actually think this would be fine, unless we want to differentiate between command man pages and other man pages by that. It's just that the shell libraries are half way in between, and "git-remote-helpers.txt" is misnamed by that convention.

Michael