{"thread":{"id":"53516","subject":"How do Git on Linux users launch/read the user-manual?","startedAt":"2020-05-20T20:58:16Z","lastAt":"2020-05-22T09:58:03Z","messageCount":8,"participants":["Philip Oakley","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"398298","messageId":"8142f64b-9b5e-3637-21a2-3671dd65a42e@iee.email","threadId":"53516","inReplyTo":null,"subject":"How do Git on Linux users launch/read the user-manual?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2020-05-20T20:58:12Z","receivedAt":"2020-05-20T20:58:16Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"As a Windows user, when I want to look at the Git user-manual, I tend to\n`git help git`, which on Git for Windows opens the users  default\nbrowser. For me, it's at C:/Program\nFiles/Git/mingw64/share/doc/git-doc/git.html.\n\nI can then browse that directory to find user-manual.html and open it\nfrom there (because I know it is there!).\n\nHow do Git on Linux users launch/read the user-manual?\n\nEssentially the user manual isn't accessible from Git, and really it\nshould be.\n\nHowever it's not a formatted as a man page so some other access\nmechanism is needed, compatible with Linux, and Windows users. It would\nbe nice if it was part of the `git help -g` list.\n\nExcuse my ignorance for not knowing how linux users should access this\nusefully curated doc.\n\nQuestion promoted by Philippe's recent inclusion of the FAQ to the doc\nlist [1]\n\nPhilip\n\n[1] https://lore.kernel.org/git/xmqqimgqwqif.fsf@gitster.c.googlers.com/T/#t\n"},{"id":"398302","messageId":"xmqqtv0athz5.fsf@gitster.c.googlers.com","threadId":"53516","inReplyTo":"8142f64b-9b5e-3637-21a2-3671dd65a42e@iee.email","subject":"Re: How do Git on Linux users launch/read the user-manual?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-20T21:27:26Z","receivedAt":"2020-05-20T21:27:49Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley <philipoakley@iee.email> writes:\n\n> I can then browse that directory to find user-manual.html and open it\n> from there (because I know it is there!).\n>\n> How do Git on Linux users launch/read the user-manual?\n\nStart from the same starting point\n\n$ git help -w git\n\nand then navigate to the link to \"Git User Manual\"?\n\n"},{"id":"398304","messageId":"6dd15666-1e3e-e9b2-d98b-396d58f241cd@iee.email","threadId":"53516","inReplyTo":"xmqqtv0athz5.fsf@gitster.c.googlers.com","subject":"Re: How do Git on Linux users launch/read the user-manual?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2020-05-20T21:50:24Z","receivedAt":"2020-05-20T21:50:28Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Junio,\n\nOn 20/05/2020 22:27, Junio C Hamano wrote:\n> Philip Oakley <philipoakley@iee.email> writes:\n>\n>> I can then browse that directory to find user-manual.html and open it\n>> from there (because I know it is there!).\n>>\n>> How do Git on Linux users launch/read the user-manual?\n> Start from the same starting point\n>\n> $ git help -w git\n>\n> and then navigate to the link to \"Git User Manual\"?\n>\nAnd then what? Is it always some .html viewer, or viewing the raw .txt\nfile, or something else? (it isn't the man view..)\n--\nPhilip\n"},{"id":"398309","messageId":"xmqqpnaytb31.fsf@gitster.c.googlers.com","threadId":"53516","inReplyTo":"6dd15666-1e3e-e9b2-d98b-396d58f241cd@iee.email","subject":"Re: How do Git on Linux users launch/read the user-manual?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-20T23:56:18Z","receivedAt":"2020-05-20T23:56:26Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley <philipoakley@iee.email> writes:\n\n> Hi Junio,\n>\n> On 20/05/2020 22:27, Junio C Hamano wrote:\n>> Philip Oakley <philipoakley@iee.email> writes:\n>>\n>>> I can then browse that directory to find user-manual.html and open it\n>>> from there (because I know it is there!).\n>>>\n>>> How do Git on Linux users launch/read the user-manual?\n>> Start from the same starting point\n>>\n>> $ git help -w git\n>>\n>> and then navigate to the link to \"Git User Manual\"?\n>>\n> And then what? Is it always some .html viewer, or viewing the raw .txt\n> file, or something else? (it isn't the man view..)\n\n\"git help -w\" is showing stuff in the web browser, and when you open\ngit(1), which is rendered in HTML, and visit \"Git User's Manual\"\nlink in it, the experience would be no different from those viewing\nvia the browser on Windows---$(htmldir)/user-manual.html is where\nthe rendered HTML version of the user-manual is.\n\nOr are you asking something else?\n\n"},{"id":"398400","messageId":"ecac8516-e536-80e8-fc72-098406592fd5@iee.email","threadId":"53516","inReplyTo":"xmqqpnaytb31.fsf@gitster.c.googlers.com","subject":"Re: How do Git on Linux users launch/read the user-manual?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2020-05-21T21:29:35Z","receivedAt":"2020-05-21T21:29:40Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 21/05/2020 00:56, Junio C Hamano wrote:\n> Philip Oakley <philipoakley@iee.email> writes:\n>\n>> Hi Junio,\n>>\n>> On 20/05/2020 22:27, Junio C Hamano wrote:\n>>> Philip Oakley <philipoakley@iee.email> writes:\n>>>\n>>>> I can then browse that directory to find user-manual.html and open it\n>>>> from there (because I know it is there!).\n>>>>\n>>>> How do Git on Linux users launch/read the user-manual?\n>>> Start from the same starting point\n>>>\n>>> $ git help -w git\n>>>\n>>> and then navigate to the link to \"Git User Manual\"?\n>>>\n>> And then what? Is it always some .html viewer, or viewing the raw .txt\n>> file, or something else? (it isn't the man view..)\n> \"git help -w\" is showing stuff in the web browser, and when you open\n> git(1), which is rendered in HTML, and visit \"Git User's Manual\"\n> link in it, the experience would be no different from those viewing\n> via the browser on Windows---$(htmldir)/user-manual.html is where\n> the rendered HTML version of the user-manual is.\n>\n> Or are you asking something else?\n>\nI was more coming at the question from the other direction, that is,\nabout accessing, normally, the git manuals, and discovering the desired\ninformation, both for existing and new users.\n\nIn your example, you needed to include the extra -w option, specific to\nthis 'special' manual, while all the other hundreds of man pages would\nbe accessed without it (even on Windows, as the config is set by default).\n\nI also get the impression that many linux users may be using 'man' just\nas much as much as 'git help' but neither (without realising the need\nfor the extra option) would show the user-manual (.txt|.html).\n\nWe do have the advised `git help -g` to list the concept guides, but\nthat doesn't advise about the user-manual, which surely we should\nmention to those asking for help (without them needing a long journey of\ndiscovery). The list does include `git everyday`...\n\nI appreciate that, for some, there is a view that new users are other\npeoples problems and that knowledgable users already know, roughly, \nwhich command they wish to use and thus then peruse the appropriate\nreference manual to confirm the correct form for their command. I'd\nrather we direct uncertain users to their appropriate guide quickly,\nusing their expected viewer method. Hence the question.\n\nPhilip\n"},{"id":"398404","messageId":"xmqqzha1q6co.fsf@gitster.c.googlers.com","threadId":"53516","inReplyTo":"ecac8516-e536-80e8-fc72-098406592fd5@iee.email","subject":"Re: How do Git on Linux users launch/read the user-manual?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-21T22:19:03Z","receivedAt":"2020-05-21T22:19:09Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley <philipoakley@iee.email> writes:\n\n>> Or are you asking something else?\n>>\n> I was more coming at the question from the other direction, that is,\n> about accessing, normally, the git manuals, and discovering the desired\n> information, both for existing and new users.\n>\n> In your example, you needed to include the extra -w option, specific to\n> this 'special' manual, while all the other hundreds of man pages would\n> be accessed without it (even on Windows, as the config is set by default).\n\nFor those who have help.format set to html, it is no \"extra\" thing\nrequired.  I said \"git help -w\" so that people would understand what\nI meant regardless of their personal settings are.\n\nOr are you saying that nobody on Linux uses the html format?  I\nshould stop keeping the git-htmldocs.git repository up to date,\nif that is the case, but I suspect it is not.\n\n> We do have the advised `git help -g` to list the concept guides, but\n> that doesn't advise about the user-manual, which surely we should\n> mention to those asking for help (without them needing a long journey of\n> discovery). The list does include `git everyday`...\n>\n> I appreciate that, for some, there is a view that new users are other\n> peoples problems and that knowledgable users already know, roughly,\n> which command they wish to use and thus then peruse the appropriate\n> reference manual to confirm the correct form for their command. I'd\n> rather we direct uncertain users to their appropriate guide quickly,\n> using their expected viewer method. Hence the question.\n\nOr are you volunteering to update the mark-up (if necessary) so that\nuser-manual would become part of \"man\" (\"man git-user-manual\",\nperhaps) suite?  That would be an excellent suggestion.\n\nWhatever proposal/volunteering comes from you after your question is\nanswered would be quite interesting.  Hopefully that would be one\nthat is beneficial to the project as a whoel ;-)\n\nThanks.\n\n"},{"id":"398405","messageId":"xmqqv9korkg0.fsf@gitster.c.googlers.com","threadId":"53516","inReplyTo":"xmqqzha1q6co.fsf@gitster.c.googlers.com","subject":"Re: How do Git on Linux users launch/read the user-manual?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-21T22:29:19Z","receivedAt":"2020-05-21T22:29:24Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Or are you saying that nobody on Linux uses the html format?  I\n> should stop keeping the git-htmldocs.git repository up to date,\n> if that is the case, but I suspect it is not.\n> ...\n> Or are you volunteering to update the mark-up (if necessary) so that\n> user-manual would become part of \"man\" (\"man git-user-manual\",\n> perhaps) suite?  That would be an excellent suggestion.\n\nHaving said that, I am not sure the way the material covered by the\nuser-manual is presented in is a good match for the manpage format\nin the first place.  Don't modern manpage viewers, or generic pagers\nthat can display textual contents (which may happen to be the \"man 1\ngit\" output), or even a terminal enumrator that may happen to be\nshowing the output of such a pager, notice a URL and allow users to\nactivate on it (i.e. visit the HTML document the URL points at, by\nopening the URL in an already-running browser, or in a new instance\nof a browser)?  So perhaps a better solution for those who live in a\ntext terminal and view our documentation via \"git help -m git\" or\neven \"man git\" would be to write a full URL to reach a version of\nuser manual available to the user, perhaps with file:/// URL \"as\ntext\" in the man output?  Then you do not have to reformat the user\nmanual in the manpage format or anything silly like that.\n\nHmm?\n"},{"id":"398413","messageId":"da31577b-88d2-9f72-0c76-9f6474dc4e83@iee.email","threadId":"53516","inReplyTo":"xmqqv9korkg0.fsf@gitster.c.googlers.com","subject":"Re: How do Git on Linux users launch/read the user-manual?","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2020-05-22T09:57:51Z","receivedAt":"2020-05-22T09:58:03Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Junio,\n\nOn 21/05/2020 23:29, Junio C Hamano wrote:\n> Junio C Hamano <gitster@pobox.com> writes:\n>\n>> Or are you saying that nobody on Linux uses the html format?  I\n>> should stop keeping the git-htmldocs.git repository up to date,\n>> if that is the case, but I suspect it is not.\n>> ...\n>> Or are you volunteering to update the mark-up (if necessary) so that\n>> user-manual would become part of \"man\" (\"man git-user-manual\",\n>> perhaps) suite?  That would be an excellent suggestion.\nNo, I wasn't volunteering to update the user-manual to man format ;-)\n\nI had previously suggested that an intermediate man page could provide\nthe user link to the user-manual proper [1] but it wasn't really accepted.\n\n> Having said that, I am not sure the way the material covered by the\n> user-manual is presented in is a good match for the manpage format\n> in the first place. \nTrue. A man page has a different focus.\n\n>  Don't modern manpage viewers, or generic pagers\n> that can display textual contents (which may happen to be the \"man 1\n> git\" output), or even a terminal enumrator that may happen to be\n> showing the output of such a pager, notice a URL and allow users to\n> activate on it (i.e. visit the HTML document the URL points at, by\n> opening the URL in an already-running browser, or in a new instance\n> of a browser)?\nThis was the same question I was asking at the beginning (given that I'm\n97.7% on Windows). Would a modern man viewer, if given the none existent\nuser-manual man page path, try for the an html equivalent - I'm not\nthinking it does:\n\nroot@Philip-Win10:~# git help git             #works!\n\nroot@Philip-Win10:~# git help user-manual\nNo manual entry for gituser-manual\nroot@Philip-Win10:~#\n\n(WSL - Ubuntu - git v2.23.0)\n\n>   So perhaps a better solution for those who live in a\n> text terminal and view our documentation via \"git help -m git\" or\n> even \"man git\" would be to write a full URL to reach a version of\n> user manual available to the user, perhaps with file:/// URL \"as\n> text\" in the man output?  Then you do not have to reformat the user\n> manual in the manpage format or anything silly like that.\n>\n> Hmm?\nMaybe the help code (when using the -m code path) should test for the\nman file existence first, and revert to the -w code path as a fall back\n(with warning/advice)?  Just a thought.\n\nIt could provide a fall through for lots of other potential html help\nfiles, when stored in the correct path (if that's sensible for the\nvarious OS usages).\n\n--\nPhilip\n\n[1]\nhttps://lore.kernel.org/git/5561391C5EED4114A90C35518558A267@PhilipOakley/T/#u\n"}]}