From: Jeff King <peff@peff.net>
To: Emily Shaffer <emilyshaffer@google.com>
Cc: Philip Oakley <philipoakley@iee.org>,
Git List <git@vger.kernel.org>,
Junio C Hamano <gitster@pobox.com>,
Johannes Schindelin <Johannes.Schindelin@gmx.de>,
Duy Nguyen <pclouds@gmail.com>
Subject: Re: [PATCH] git.c: show usage for accessing the git(1) help page
Date: Tue, 14 May 2019 21:53:31 -0400 [thread overview]
Message-ID: <20190515015331.GC13255@sigill.intra.peff.net> (raw)
In-Reply-To: <20190515001717.GA138048@google.com>
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.
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
next prev parent reply other threads:[~2019-05-15 1:53 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-05-13 20:47 git --help not actually showing the git(1) help page Philip Oakley
2019-05-13 20:53 ` Jeff King
2019-05-13 21:55 ` Philip Oakley
2019-05-13 22:44 ` Junio C Hamano
2019-05-14 14:05 ` Philip Oakley
2019-05-14 15:24 ` [PATCH] git.c: show usage for accessing " Philip Oakley
2019-05-15 0:17 ` Emily Shaffer
2019-05-15 1:53 ` Jeff King [this message]
2019-05-15 6:43 ` Philip Oakley
2019-05-15 8:11 ` [PATCH v2] " Philip Oakley
2019-05-15 8:14 ` Eric Sunshine
2019-05-15 22:47 ` [PATCH v3 0/2] " Philip Oakley
2019-05-15 22:47 ` [PATCH v3 1/2] git.c: show usage for " Philip Oakley
2019-05-15 22:47 ` [PATCH v3 2/2] Doc: git.txt: remove backticks from link and add git-scm.com/docs Philip Oakley
2019-05-16 1:56 ` Junio C Hamano
2019-05-16 11:25 ` Philip Oakley
2019-05-16 22:22 ` Jeff King
2019-05-16 23:09 ` Philip Oakley
2019-05-15 6:36 ` [PATCH] git.c: show usage for accessing the git(1) help page Philip Oakley
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190515015331.GC13255@sigill.intra.peff.net \
--to=peff@peff.net \
--cc=Johannes.Schindelin@gmx.de \
--cc=emilyshaffer@google.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=pclouds@gmail.com \
--cc=philipoakley@iee.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).