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

[Philip Oakley <philipoakley@iee.email>]

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