git --help not actually showing the git(1) help page..

git --help not actually showing the git(1) help page..

[Philip Oakley]

Is there a cli way, especially on Git for Windows bash, to get the html 
man page of git(1)? I have it on my system, so can go via another page but..

All the `git <cmd> --help` appear to work, but I can't determine the 
correct invocation for bringing up the stupid content tracker's page in 
the browser. Previously I'd have expected either `git --help` or `git 
git --help` to work (can't remember which). The former only produces the 
short form -h help in the bash window, the latter says 'git' isn't a 
command.

cc'ing Dscho and Duy who have had recent contact with that area who may 
know.
-- 
Philip

Re: git --help not actually showing the git(1) help page..

[Jeff King]

On Mon, May 13, 2019 at 09:47:27PM +0100, Philip Oakley wrote:

> Is there a cli way, especially on Git for Windows bash, to get the html man
> page of git(1)? I have it on my system, so can go via another page but..
> 
> All the `git <cmd> --help` appear to work, but I can't determine the correct
> invocation for bringing up the stupid content tracker's page in the browser.
> Previously I'd have expected either `git --help` or `git git --help` to work
> (can't remember which). The former only produces the short form -h help in
> the bash window, the latter says 'git' isn't a command.

Try "git help git".

It might be worth mentioning it in the paragraph at the end of "git
help".

-Peff

Re: git --help not actually showing the git(1) help page..

[Philip Oakley]

Hi Peff
On 13/05/2019 21:53, Jeff King wrote:
> On Mon, May 13, 2019 at 09:47:27PM +0100, Philip Oakley wrote:
>
>> Is there a cli way, especially on Git for Windows bash, to get the html man
>> page of git(1)? I have it on my system, so can go via another page but..
>>
>> All the `git <cmd> --help` appear to work, but I can't determine the correct
>> invocation for bringing up the stupid content tracker's page in the browser.
>> Previously I'd have expected either `git --help` or `git git --help` to work
>> (can't remember which). The former only produces the short form -h help in
>> the bash window, the latter says 'git' isn't a command.
> Try "git help git".
Ahh, that's the one. I'd totally forgot about that method.
>
> It might be worth mentioning it in the paragraph at the end of "git
> help".
True. I'll stick on my todo list, along with adding to the general usage 
message. Possibly "Or `git help git`."

On GfW I commonly use the `git <cmd> --help` when things go wrong, so 
making the response to that give the right advice would be good. (It's 
almost the same isue as `git --version`).

> --
Philip

Re: git --help not actually showing the git(1) help page..

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

> On GfW I commonly use the `git <cmd> --help` when things go wrong, so
> making the response to that give the right advice would be good.

There are three levels of details ;-) "git --help" is meant as a
shorter and sweeter version of "git help git" that is more detailed
than "git -h".

It is conceivable for an enterprising developer to write a set of
documentation with medium level details and make "git add --help"
give such a medium level doc, more detailed than "git add -h" but
more concice than "git help add".  Those who did "git <cmd> --help"
did not bother doing so.

Re: git --help not actually showing the git(1) help page..

[Philip Oakley]

Hi Junio,
On 13/05/2019 23:44, Junio C Hamano wrote:
> Philip Oakley <philipoakley@iee.org> writes:
>
>> On GfW I commonly use the `git <cmd> --help` when things go wrong, so
>> making the response to that give the right advice would be good.
> There are three levels of details ;-) "git --help" is meant as a
> shorter and sweeter version of "git help git" that is more detailed
> than "git -h".
Though that's not what happens at the moment. For the plain `git --help` 
case it simply defaults to the `-h` case, while for any other `git cmd 
--help` it does pop up the git-for-windows configured web browser manual 
page.
> It is conceivable for an enterprising developer to write a set of
> documentation with medium level details and make "git add --help"
> give such a medium level doc, more detailed than "git add -h" but
> more concice than "git help add".
I'd agree that there's a need for some typical usage/teaching level 
documentation to _complement_ the reference manual nature of the man 
pages. It's a chicken - egg situation for some users we/they need the 
bit of education before they can know they need to refer to, and 
understand, the respective man pages.

> Those who did "git <cmd> --help"
> did not bother doing so.
>
I tend to go with including the complementary usage/teaching aspects in 
a distinct section of the man pages, though some of this is based on 
examples from other software, e.g. Matlab for design/systems engineers.

A simplistic patch for just the 'usage' message to follow.

Philip

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

[Philip Oakley]

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'.");
 
 static int use_pager = -1;
 
-- 
2.21.0.windows.1.1517.gbad5f960a3.dirty

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

[Emily Shaffer]

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
> 

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

[Jeff King]

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

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

[Philip Oakley]

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

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

[Philip Oakley]

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

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

[Philip Oakley]

It is not immediately obvious how to use the `git help` system to show
the git(1) page, with its overview and its background and coordinating
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 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/git.c b/git.c
index 2324ac0b7e..4797941dfd 100644
--- a/git.c
+++ b/git.c
@@ -33,7 +33,8 @@ 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.\n"
+	   "Use 'git help git' for an overview of the system.");
 
 static int use_pager = -1;
 
-- 
2.21.0.windows.1.1517.gbad5f960a3.dirty

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

[Eric Sunshine]

On Wed, May 15, 2019 at 4:11 AM Philip Oakley <philipoakley@iee.org> wrote:
> It is not immediately obvious how to use the `git help` system to show
> the git(1) page, with its overview and its background and coordinating
> 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>
> ---
> diff --git a/git.c b/git.c
> @@ -33,7 +33,8 @@ 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.\n"
> +          "Use 'git help git' for an overview of the system.");

If you want to be consistent with the wording shown for "git help
<...>", you might want s/Use/See/.

[PATCH v3 0/2] accessing the git(1) help page

[Philip Oakley]

This hopefully is a final version of the usage message to
show how to access the git(1) manual page.

The V3 change is Eric's suggestion to use 'See'.

I have also taken the opportunity [Patch 2/2] to pick up peff's suggestion
to include the git-scm doc link, and also correct the mis-quoting
of a link to the html formatted github doc pages.

Philip Oakley (2):
  git.c: show usage for accessing the git(1) help page
  Doc: git.txt: remove backticks from link and add git-scm.com/docs

 Documentation/git.txt | 3 ++-
 git.c                 | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

-- 
2.21.0.windows.1.1517.gbad5f960a3.dirty

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

[Philip Oakley]

It is not immediately obvious how to use the `git help` system to show
the git(1) page, with its overview and its background and coordinating
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 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/git.c b/git.c
index 2324ac0b7e..9e24de43d7 100644
--- a/git.c
+++ b/git.c
@@ -33,7 +33,8 @@ 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.\n"
+	   "See 'git help git' for an overview of the system.");
 
 static int use_pager = -1;
 
-- 
2.21.0.windows.1.1517.gbad5f960a3.dirty

[PATCH v3 2/2] Doc: git.txt: remove backticks from link and add git-scm.com/docs

[Philip Oakley]

While checking the html formatted git(1) manual page, it was noted
that the link to https://git.github.io/htmldocs/git.html was formatted
as code. Remove the backticks.

While at it, add the https://git-scm.com/docs link which one reviewer
noted had linkable section headings.

Helped-by: Jeff King <peff@peff.net>
Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/git.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index dbf92f6ac6..edcb9936b5 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -33,7 +33,8 @@ individual Git commands with "git help command".  linkgit:gitcli[7]
 manual page gives you an overview of the command-line command syntax.
 
 A formatted and hyperlinked copy of the latest Git documentation
-can be viewed at `https://git.github.io/htmldocs/git.html`.
+can be viewed at https://git.github.io/htmldocs/git.html
+or https://git-scm.com/docs.
 
 
 OPTIONS
-- 
2.21.0.windows.1.1517.gbad5f960a3.dirty

Re: [PATCH v3 2/2] Doc: git.txt: remove backticks from link and add git-scm.com/docs

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

> While checking the html formatted git(1) manual page, it was noted
> that the link to https://git.github.io/htmldocs/git.html was formatted
> as code. Remove the backticks.

Good.  I just ran

	$ git grep '`https*://' Documentation/

to see if any hits I see are for the real URL the user may want to
click on.  There are some that are pointing at real sites, but I do
not think users would want to clickon  many of them while reading the
documentation.

Except perhaps for these to see what's there:

Documentation/git-archimport.txt:	Attempt to auto-register archives at `http://mirrors.sourcecontrol.net`
Documentation/git-cvsimport.txt:* cvs2git (part of cvs2svn), `http://subversion.apache.org/`

Re: [PATCH v3 2/2] Doc: git.txt: remove backticks from link and add git-scm.com/docs

[Philip Oakley]

On 16/05/2019 02:56, Junio C Hamano wrote:
> Philip Oakley <philipoakley@iee.org> writes:
>
>> While checking the html formatted git(1) manual page, it was noted
>> that the link to https://git.github.io/htmldocs/git.html was formatted
>> as code. Remove the backticks.
> Good.  I just ran
>
> 	$ git grep '`https*://' Documentation/
>
> to see if any hits I see are for the real URL the user may want to
> click on.  There are some that are pointing at real sites, but I do
> not think users would want to clickon  many of them while reading the
> documentation.
I'd had a quick brows and mainly found example.com ;-) Any other excepts 
were at the other end of the doc relative to git(1)...
>
> Except perhaps for these to see what's there:
>
> Documentation/git-archimport.txt:	Attempt to auto-register archives at `http://mirrors.sourcecontrol.net`
That domain is gone. Whole line should probably be removed.

> Documentation/git-cvsimport.txt:* cvs2git (part of cvs2svn), `http://subversion.apache.org/`
>
Still there. Still updated - last news 2019-04-24. Could remove backticks.

Philip

Re: [PATCH v3 2/2] Doc: git.txt: remove backticks from link and add git-scm.com/docs

[Jeff King]

On Thu, May 16, 2019 at 12:25:47PM +0100, Philip Oakley wrote:

> > Except perhaps for these to see what's there:
> > 
> > Documentation/git-archimport.txt:	Attempt to auto-register archives at `http://mirrors.sourcecontrol.net`
> That domain is gone. Whole line should probably be removed.

Heh, see:

  https://public-inbox.org/git/20170420203441.mrlwbkqinub7m225@sigill.intra.peff.net/

I left it to people who actually care about arch to clean up that line
and figure out if there is some useful alternative.

-Peff

Re: [PATCH v3 2/2] Doc: git.txt: remove backticks from link and add git-scm.com/docs

[Philip Oakley]

On 16/05/2019 23:22, Jeff King wrote:
> On Thu, May 16, 2019 at 12:25:47PM +0100, Philip Oakley wrote:
>
>>> Except perhaps for these to see what's there:
>>>
>>> Documentation/git-archimport.txt:	Attempt to auto-register archives at `http://mirrors.sourcecontrol.net`
>> That domain is gone. Whole line should probably be removed.
> Heh, see:
>
>    https://public-inbox.org/git/20170420203441.mrlwbkqinub7m225@sigill.intra.peff.net/
>
> I left it to people who actually care about arch to clean up that line
> and figure out if there is some useful alternative.
>
Thanks. I'll sit on my hands on that one then (i.e. do nothing).
-- 
Philip