How do Git on Linux users launch/read the user-manual?

How do Git on Linux users launch/read the user-manual?

[Philip Oakley]

As a Windows user, when I want to look at the Git user-manual, I tend to
`git help git`, which on Git for Windows opens the users  default
browser. For me, it's at C:/Program
Files/Git/mingw64/share/doc/git-doc/git.html.

I can then browse that directory to find user-manual.html and open it
from there (because I know it is there!).

How do Git on Linux users launch/read the user-manual?

Essentially the user manual isn't accessible from Git, and really it
should be.

However it's not a formatted as a man page so some other access
mechanism is needed, compatible with Linux, and Windows users. It would
be nice if it was part of the `git help -g` list.

Excuse my ignorance for not knowing how linux users should access this
usefully curated doc.

Question promoted by Philippe's recent inclusion of the FAQ to the doc
list [1]

Philip

[1] https://lore.kernel.org/git/xmqqimgqwqif.fsf@gitster.c.googlers.com/T/#t

Re: How do Git on Linux users launch/read the user-manual?

[Junio C Hamano]

Philip Oakley <philipoakley@iee.email> writes:

> I can then browse that directory to find user-manual.html and open it
> from there (because I know it is there!).
>
> How do Git on Linux users launch/read the user-manual?

Start from the same starting point

$ git help -w git

and then navigate to the link to "Git User Manual"?

Re: How do Git on Linux users launch/read the user-manual?

[Philip Oakley]

Hi Junio,

On 20/05/2020 22:27, Junio C Hamano wrote:
> Philip Oakley <philipoakley@iee.email> writes:
>
>> I can then browse that directory to find user-manual.html and open it
>> from there (because I know it is there!).
>>
>> How do Git on Linux users launch/read the user-manual?
> Start from the same starting point
>
> $ git help -w git
>
> and then navigate to the link to "Git User Manual"?
>
And then what? Is it always some .html viewer, or viewing the raw .txt
file, or something else? (it isn't the man view..)
--
Philip

Re: How do Git on Linux users launch/read the user-manual?

[Junio C Hamano]

Philip Oakley <philipoakley@iee.email> writes:

> Hi Junio,
>
> On 20/05/2020 22:27, Junio C Hamano wrote:
>> Philip Oakley <philipoakley@iee.email> writes:
>>
>>> I can then browse that directory to find user-manual.html and open it
>>> from there (because I know it is there!).
>>>
>>> How do Git on Linux users launch/read the user-manual?
>> Start from the same starting point
>>
>> $ git help -w git
>>
>> and then navigate to the link to "Git User Manual"?
>>
> And then what? Is it always some .html viewer, or viewing the raw .txt
> file, or something else? (it isn't the man view..)

"git help -w" is showing stuff in the web browser, and when you open
git(1), which is rendered in HTML, and visit "Git User's Manual"
link in it, the experience would be no different from those viewing
via the browser on Windows---$(htmldir)/user-manual.html is where
the rendered HTML version of the user-manual is.

Or are you asking something else?

Re: How do Git on Linux users launch/read the user-manual?

[Philip Oakley]

On 21/05/2020 00:56, Junio C Hamano wrote:
> Philip Oakley <philipoakley@iee.email> writes:
>
>> Hi Junio,
>>
>> On 20/05/2020 22:27, Junio C Hamano wrote:
>>> Philip Oakley <philipoakley@iee.email> writes:
>>>
>>>> I can then browse that directory to find user-manual.html and open it
>>>> from there (because I know it is there!).
>>>>
>>>> How do Git on Linux users launch/read the user-manual?
>>> Start from the same starting point
>>>
>>> $ git help -w git
>>>
>>> and then navigate to the link to "Git User Manual"?
>>>
>> And then what? Is it always some .html viewer, or viewing the raw .txt
>> file, or something else? (it isn't the man view..)
> "git help -w" is showing stuff in the web browser, and when you open
> git(1), which is rendered in HTML, and visit "Git User's Manual"
> link in it, the experience would be no different from those viewing
> via the browser on Windows---$(htmldir)/user-manual.html is where
> the rendered HTML version of the user-manual is.
>
> Or are you asking something else?
>
I was more coming at the question from the other direction, that is,
about accessing, normally, the git manuals, and discovering the desired
information, both for existing and new users.

In your example, you needed to include the extra -w option, specific to
this 'special' manual, while all the other hundreds of man pages would
be accessed without it (even on Windows, as the config is set by default).

I also get the impression that many linux users may be using 'man' just
as much as much as 'git help' but neither (without realising the need
for the extra option) would show the user-manual (.txt|.html).

We do have the advised `git help -g` to list the concept guides, but
that doesn't advise about the user-manual, which surely we should
mention to those asking for help (without them needing a long journey of
discovery). The list does include `git everyday`...

I appreciate that, for some, there is a view that new users are other
peoples problems and that knowledgable users already know, roughly, 
which command they wish to use and thus then peruse the appropriate
reference manual to confirm the correct form for their command. I'd
rather we direct uncertain users to their appropriate guide quickly,
using their expected viewer method. Hence the question.

Philip

Re: How do Git on Linux users launch/read the user-manual?

[Junio C Hamano]

Philip Oakley <philipoakley@iee.email> writes:

>> Or are you asking something else?
>>
> I was more coming at the question from the other direction, that is,
> about accessing, normally, the git manuals, and discovering the desired
> information, both for existing and new users.
>
> In your example, you needed to include the extra -w option, specific to
> this 'special' manual, while all the other hundreds of man pages would
> be accessed without it (even on Windows, as the config is set by default).

For those who have help.format set to html, it is no "extra" thing
required.  I said "git help -w" so that people would understand what
I meant regardless of their personal settings are.

Or are you saying that nobody on Linux uses the html format?  I
should stop keeping the git-htmldocs.git repository up to date,
if that is the case, but I suspect it is not.

> We do have the advised `git help -g` to list the concept guides, but
> that doesn't advise about the user-manual, which surely we should
> mention to those asking for help (without them needing a long journey of
> discovery). The list does include `git everyday`...
>
> I appreciate that, for some, there is a view that new users are other
> peoples problems and that knowledgable users already know, roughly,
> which command they wish to use and thus then peruse the appropriate
> reference manual to confirm the correct form for their command. I'd
> rather we direct uncertain users to their appropriate guide quickly,
> using their expected viewer method. Hence the question.

Or are you volunteering to update the mark-up (if necessary) so that
user-manual would become part of "man" ("man git-user-manual",
perhaps) suite?  That would be an excellent suggestion.

Whatever proposal/volunteering comes from you after your question is
answered would be quite interesting.  Hopefully that would be one
that is beneficial to the project as a whoel ;-)

Thanks.

Re: How do Git on Linux users launch/read the user-manual?

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Or are you saying that nobody on Linux uses the html format?  I
> should stop keeping the git-htmldocs.git repository up to date,
> if that is the case, but I suspect it is not.
> ...
> Or are you volunteering to update the mark-up (if necessary) so that
> user-manual would become part of "man" ("man git-user-manual",
> perhaps) suite?  That would be an excellent suggestion.

Having said that, I am not sure the way the material covered by the
user-manual is presented in is a good match for the manpage format
in the first place.  Don't modern manpage viewers, or generic pagers
that can display textual contents (which may happen to be the "man 1
git" output), or even a terminal enumrator that may happen to be
showing the output of such a pager, notice a URL and allow users to
activate on it (i.e. visit the HTML document the URL points at, by
opening the URL in an already-running browser, or in a new instance
of a browser)?  So perhaps a better solution for those who live in a
text terminal and view our documentation via "git help -m git" or
even "man git" would be to write a full URL to reach a version of
user manual available to the user, perhaps with file:/// URL "as
text" in the man output?  Then you do not have to reformat the user
manual in the manpage format or anything silly like that.

Hmm?

Re: How do Git on Linux users launch/read the user-manual?

[Philip Oakley]

Hi Junio,

On 21/05/2020 23:29, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> Or are you saying that nobody on Linux uses the html format?  I
>> should stop keeping the git-htmldocs.git repository up to date,
>> if that is the case, but I suspect it is not.
>> ...
>> Or are you volunteering to update the mark-up (if necessary) so that
>> user-manual would become part of "man" ("man git-user-manual",
>> perhaps) suite?  That would be an excellent suggestion.
No, I wasn't volunteering to update the user-manual to man format ;-)

I had previously suggested that an intermediate man page could provide
the user link to the user-manual proper [1] but it wasn't really accepted.

> Having said that, I am not sure the way the material covered by the
> user-manual is presented in is a good match for the manpage format
> in the first place. 
True. A man page has a different focus.

>  Don't modern manpage viewers, or generic pagers
> that can display textual contents (which may happen to be the "man 1
> git" output), or even a terminal enumrator that may happen to be
> showing the output of such a pager, notice a URL and allow users to
> activate on it (i.e. visit the HTML document the URL points at, by
> opening the URL in an already-running browser, or in a new instance
> of a browser)?
This was the same question I was asking at the beginning (given that I'm
97.7% on Windows). Would a modern man viewer, if given the none existent
user-manual man page path, try for the an html equivalent - I'm not
thinking it does:

root@Philip-Win10:~# git help git             #works!

root@Philip-Win10:~# git help user-manual
No manual entry for gituser-manual
root@Philip-Win10:~#

(WSL - Ubuntu - git v2.23.0)

>   So perhaps a better solution for those who live in a
> text terminal and view our documentation via "git help -m git" or
> even "man git" would be to write a full URL to reach a version of
> user manual available to the user, perhaps with file:/// URL "as
> text" in the man output?  Then you do not have to reformat the user
> manual in the manpage format or anything silly like that.
>
> Hmm?
Maybe the help code (when using the -m code path) should test for the
man file existence first, and revert to the -w code path as a fall back
(with warning/advice)?  Just a thought.

It could provide a fall through for lots of other potential html help
files, when stored in the correct path (if that's sensible for the
various OS usages).

--
Philip

[1]
https://lore.kernel.org/git/5561391C5EED4114A90C35518558A267@PhilipOakley/T/#u