From: Philip Oakley <philipoakley@iee.org>
Date: Wed, 15 May 2019 06:43:28 GMT
Subject: Re: [PATCH] git.c: show usage for accessing the git(1) help page
Message-ID: <7bd330d7-81f1-52b4-52d3-b74b128af83a@iee.org>
In-Reply-To: <20190515015331.GC13255@sigill.intra.peff.net>

Hi Peff,

On 15/05/2019 02:53, Jeff King wrote:
> On Tue, May 14, 2019 at 05:17:17PM -0700, Emily Shaffer wrote:
>
>>>   const char git_more_info_string[] =
>>>   	N_("'git help -a' and 'git help -g' list available subcommands and some\n"
>>>   	   "concept guides. See 'git help <command>' or 'git help <concept>'\n"
>>> -	   "to read about a specific subcommand or concept.");
>>> +	   "to read about a specific subcommand or concept. Or use 'git help git'.");
>> I'm not sure the wording makes sense here. It sounds like you're saying,
>> "Or use 'git help git' to read about specific subcommands or concepts."
>> which isn't really what I think you're trying to say.
>>
>> What about, "Or, use 'git help git' for a detailed guide of the Git
>> system as a whole."
> I had a similar reaction on reading Philip's patch. I think your
> suggestion is better. We could even shorten it to just:
>
>    Use 'git help git' for an overview of the system.
That is a lot better. I like it. Concise and effective. I'll create a v2.
>
> Looking at "git help git" I actually think the DESCRIPTION section could
> do a better job of being a first entry-point for new readers of the
> documentation. But I don't think that needs to be a blocker for what
> we're discussing here.
I'd agree for both points.
>
>> (I'm still not sure that's quite it - since `git help git` mostly
>> details the flags you can pass to git before invoking a subcommand. But
>> I'm not sure that `git --help` is the place to say that...)
> Yeah, I almost suggested something like:
>
>    Use 'git help git' for options and environment variables that affect
>    all subcommands.
>
> I'm not sure if that points people in a useful direction, or if it is
> getting too much into the weeds (again, probably the description section
> of git(1) could talk about how to find which documentation where.
>
> I also think it should point to git-scm.com for the hyper-linked
> documentation, since it's less ugly than the stuff at git.github.io, but
> that's really getting off-topic. :)
>
> -Peff
Interestingly, try seeing if you can use tab completion to type in 'git 
help git'. It's nearly as hard to find as the user-manual, which isn't a 
man(1) page ;-)

Philip