Hi Junio,
On 21/05/2020 23:29, Junio C Hamano wrote:
> Junio C Hamano <gitster@xxxxxxxxx> 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
