* How do Git on Linux users launch/read the user-manual? @ 2020-05-20 20:58 Philip Oakley 2020-05-20 21:27 ` Junio C Hamano 0 siblings, 1 reply; 8+ messages in thread From: Philip Oakley @ 2020-05-20 20:58 UTC (permalink / raw) To: Git List 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: How do Git on Linux users launch/read the user-manual? 2020-05-20 20:58 How do Git on Linux users launch/read the user-manual? Philip Oakley @ 2020-05-20 21:27 ` Junio C Hamano 2020-05-20 21:50 ` Philip Oakley 0 siblings, 1 reply; 8+ messages in thread From: Junio C Hamano @ 2020-05-20 21:27 UTC (permalink / raw) To: Philip Oakley; +Cc: Git List 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"? ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: How do Git on Linux users launch/read the user-manual? 2020-05-20 21:27 ` Junio C Hamano @ 2020-05-20 21:50 ` Philip Oakley 2020-05-20 23:56 ` Junio C Hamano 0 siblings, 1 reply; 8+ messages in thread From: Philip Oakley @ 2020-05-20 21:50 UTC (permalink / raw) To: Junio C Hamano; +Cc: Git List 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: How do Git on Linux users launch/read the user-manual? 2020-05-20 21:50 ` Philip Oakley @ 2020-05-20 23:56 ` Junio C Hamano 2020-05-21 21:29 ` Philip Oakley 0 siblings, 1 reply; 8+ messages in thread From: Junio C Hamano @ 2020-05-20 23:56 UTC (permalink / raw) To: Philip Oakley; +Cc: Git List 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? ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: How do Git on Linux users launch/read the user-manual? 2020-05-20 23:56 ` Junio C Hamano @ 2020-05-21 21:29 ` Philip Oakley 2020-05-21 22:19 ` Junio C Hamano 0 siblings, 1 reply; 8+ messages in thread From: Philip Oakley @ 2020-05-21 21:29 UTC (permalink / raw) To: Junio C Hamano; +Cc: Git List 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: How do Git on Linux users launch/read the user-manual? 2020-05-21 21:29 ` Philip Oakley @ 2020-05-21 22:19 ` Junio C Hamano 2020-05-21 22:29 ` Junio C Hamano 0 siblings, 1 reply; 8+ messages in thread From: Junio C Hamano @ 2020-05-21 22:19 UTC (permalink / raw) To: Philip Oakley; +Cc: Git List 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. ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: How do Git on Linux users launch/read the user-manual? 2020-05-21 22:19 ` Junio C Hamano @ 2020-05-21 22:29 ` Junio C Hamano 2020-05-22 9:57 ` Philip Oakley 0 siblings, 1 reply; 8+ messages in thread From: Junio C Hamano @ 2020-05-21 22:29 UTC (permalink / raw) To: Philip Oakley; +Cc: Git List 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? ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: How do Git on Linux users launch/read the user-manual? 2020-05-21 22:29 ` Junio C Hamano @ 2020-05-22 9:57 ` Philip Oakley 0 siblings, 0 replies; 8+ messages in thread From: Philip Oakley @ 2020-05-22 9:57 UTC (permalink / raw) To: Junio C Hamano; +Cc: Git List 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2020-05-22 9:58 UTC | newest] Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-05-20 20:58 How do Git on Linux users launch/read the user-manual? Philip Oakley 2020-05-20 21:27 ` Junio C Hamano 2020-05-20 21:50 ` Philip Oakley 2020-05-20 23:56 ` Junio C Hamano 2020-05-21 21:29 ` Philip Oakley 2020-05-21 22:19 ` Junio C Hamano 2020-05-21 22:29 ` Junio C Hamano 2020-05-22 9:57 ` Philip Oakley
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).