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

From: Philip Oakley <philipoakley@iee.email>
Date: May 22, 2020, 09:57 UTC
Message-ID: <da31577b-88d2-9f72-0c76-9f6474dc4e83@iee.email>
In-Reply-To: <xmqqv9korkg0.fsf@gitster.c.googlers.com>

Hi Junio,

On 21/05/2020 23:29, Junio C Hamano wrote:

Show 9 quoted lines

> 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.

Show 7 quoted lines

>  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)

Show 8 quoted lines

>   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