| Message ID | 20190514152450.15220-1-philipoakley@iee.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | git.c: show usage for accessing the git(1) help page | expand |
On Tue, May 14, 2019 at 04:24:50PM +0100, Philip Oakley wrote: > It is not immediately obvious how to use the `git help` system > to show the git(1) page, with all its background and ccordinating > material, such as environment variables. > > Let's simply list it as the last few words of the last usage line. > > Signed-off-by: Philip Oakley <philipoakley@iee.org> > --- > This follows from the discussion <3cd065d1-9db5-f2e6-ddff-aa539746d45e@iee.org> > --- > git.c | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/git.c b/git.c > index 2324ac0b7e..9a852b09c1 100644 > --- a/git.c > +++ b/git.c > @@ -33,7 +33,7 @@ const char git_usage_string[] = > 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'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...) > > static int use_pager = -1; > > -- > 2.21.0.windows.1.1517.gbad5f960a3.dirty >
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
Hi Emily, On 15/05/2019 01:17, Emily Shaffer wrote: > On Tue, May 14, 2019 at 04:24:50PM +0100, Philip Oakley wrote: >> It is not immediately obvious how to use the `git help` system >> to show the git(1) page, with all its background and ccordinating >> material, such as environment variables. >> >> Let's simply list it as the last few words of the last usage line. >> >> Signed-off-by: Philip Oakley <philipoakley@iee.org> >> --- >> This follows from the discussion <3cd065d1-9db5-f2e6-ddff-aa539746d45e@iee.org> >> --- >> git.c | 2 +- >> 1 file changed, 1 insertion(+), 1 deletion(-) >> >> diff --git a/git.c b/git.c >> index 2324ac0b7e..9a852b09c1 100644 >> --- a/git.c >> +++ b/git.c >> @@ -33,7 +33,7 @@ const char git_usage_string[] = >> 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. True. > > What about, "Or, use 'git help git' for a detailed guide of the Git > system as a whole." I had thought about a longer sentence, but was squeezing it in, given that we (I) had to add in the other parts of that help footnote... > > (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...) It's more that we are updating the system's response to a misunderstood command, hopefully with something that includes a link to our putative top level man page. It's tricky to get to without already knowing it's there. > >> >> static int use_pager = -1; >> >> -- >> 2.21.0.windows.1.1517.gbad5f960a3.dirty >> Philip
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
diff --git a/git.c b/git.c index 2324ac0b7e..9a852b09c1 100644 --- a/git.c +++ b/git.c @@ -33,7 +33,7 @@ const char git_usage_string[] = 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'."); static int use_pager = -1;
It is not immediately obvious how to use the `git help` system to show the git(1) page, with all its background and ccordinating material, such as environment variables. Let's simply list it as the last few words of the last usage line. Signed-off-by: Philip Oakley <philipoakley@iee.org> --- This follows from the discussion <3cd065d1-9db5-f2e6-ddff-aa539746d45e@iee.org> --- git.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)