Re: [PATCH] git.c: show usage for accessing the git(1) help page

From: Jeff King <peff@peff.net>
Date: May 15, 2019, 01:53 UTC
Message-ID: <20190515015331.GC13255@sigill.intra.peff.net>
In-Reply-To: <20190515001717.GA138048@google.com>

On Tue, May 14, 2019 at 05:17:17PM -0700, Emily Shaffer wrote:

Show 12 quoted lines

> >  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.

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'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