{"thread":{"id":"32861","subject":"Improve 'git help' with basic user guide linkss","startedAt":"2013-02-08T20:17:24Z","lastAt":"2013-02-12T11:37:31Z","messageCount":8,"participants":["Philip Oakley","Junio C Hamano","John Keeping"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"209034","messageId":"6D91D31A093D46869F43DD8D1012F0FB@PhilipOakley","threadId":"32861","inReplyTo":null,"subject":"Improve 'git help' with basic user guide linkss","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2013-02-08T20:17:24Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"I'm looking at extending the 'git help' to include some information for \nthe basic user who isn't ready for the extensive man page documentation \nfor the various commands.\n\nIf the user doesn't yet know which is the relevant command then they \nshould also be offered a clue on how to finding the various guides. Many \nusers are stuck on the 'If I were you I wouldn't start from here' step \n(many blog comments on the alleged poor documentation and difficulty of \nunderstanding ...).\n\nI've started on adding a few tweaks to the basic 'git help' message, \nadding an end line indicating that there are guides, such as 'tutorial'. \nInitial hacks at https://github.com/PhilipOakley/git/commits/morehelp \nfor thos interested.\n\nMy real question is on the right approach to generating a list of guides \nand including them into the git help options. I'm planning on extending \nthe command-list.txt file to include 'guides' and then extending the \ngenerate-cmdlist.sh to generate a guides array in common-cmds.h.\n\nI'm thinking of adding -g --guides and -c --commands options to \ncomplement the existing -a --all (becomes both commands and guides) \noption. I'm not yet sure how to determine which other special guides \nshould be listed (api- etc.) and when.\n\nI was expecting to update the user-manual. to become gituser-manual.txt \nso that the existing 'git help user-manual' scheme would discover it. \nThe Tutorial and the User manual obviously(?) being the first port of \ncall for the confused user.\n\nDoes this appear sensible, and should the Documentation/* directories \nalso be searched for 'guides', or is that a step too far [and it's less \ncoding] ?\n\nPhilip Oakley\n"},{"id":"209037","messageId":"7vr4kqzfw5.fsf@alter.siamese.dyndns.org","threadId":"32861","inReplyTo":"6D91D31A093D46869F43DD8D1012F0FB@PhilipOakley","subject":"Re: Improve 'git help' with basic user guide linkss","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-02-08T20:53:30Z","receivedAt":"2013-02-08T20:53:30Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> I'm looking at extending the 'git help' to include some information\n> for the basic user who isn't ready for the extensive man page\n> documentation for the various commands.\n\nWe have pointers at the beginning of \"git(1)\" for that exact reason.\nI am not saying the documents pointed at from there are perfect, but\nshouldn't that approach work?\n\n> My real question is on the right approach to generating a list of\n> guides and including them into the git help options. I'm planning on\n> extending the command-list.txt file to include 'guides' and then\n> extending the generate-cmdlist.sh to generate a guides array in\n> common-cmds.h.\n\nHaving a catalog of guide documents in help.o sounds like a good way\nto go, but I doubt \"command-list\" is a good place to store it. It\nis about git subcommands, \"git help -a\" uses it to show the list of\nthem, and the bash completion support uses the list via \"git help -a\".\n\nThe common-cmds.h does not have to be the only avenue to add your\ncatalog of guide documents to help.o. As a part of the build\nprocedure, you can list Documentation/guides/ and generate an array\ndefinition into \"guides.h\", and add #include \"guides.h\" in help.c,\nfor example.\n\n> I'm thinking of adding -g --guides and -c --commands options to\n> complement the existing -a --all (becomes both commands and guides)\n\nComplement is fine. Contaminating -a with guides is probably not.\n\n> I was expecting to update the user-manual. to become\n> gituser-manual.txt so that the existing 'git help user-manual' scheme\n> would discover it. The Tutorial and the User manual obviously(?) being\n> the first port of call for the confused user.\n\nAgain, we do have pointer to tutorial fairly prominently at the\nbeginning of \"git(1)\". Perhaps we want index.html that redirects to\ngit.html or something?\n"},{"id":"209041","messageId":"6BC280F5827C4098BCB6276232DDE8E4@PhilipOakley","threadId":"32861","inReplyTo":"7vr4kqzfw5.fsf@alter.siamese.dyndns.org","subject":"Re: Improve 'git help' with basic user guide linkss","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2013-02-08T21:10:28Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \nSent: Friday, February 08, 2013 8:53 PM\n> \"Philip Oakley\" writes:\n>\n>> I'm looking at extending the 'git help' to include some information\n>> for the basic user who isn't ready for the extensive man page\n>> documentation for the various commands.\n>\n> We have pointers at the beginning of \"git(1)\" for that exact reason.\n> I am not saying the documents pointed at from there are perfect, but\n> shouldn't that approach work?\n\nThe problem for the new user is to find that page you need to know the\ncommand 'git help git' which is unlikely. We know where to find it, they\ndon't.\n\nMy initial https://github.com/PhilipOakley/git/commit/e6217d simply \nupdates\n- N_(\"See 'git help ' for more information on a specific \ncommand.\");\n+ N_(\"See 'git help ' for more information on a specific \ncommand.\\n\"\n+ \"Or 'git help ', such as 'tutorial' for an introduction to \nGit.\");\nas a starter for the new users.\n\nIt's then a case of providing an option to show the common and other \nguides.\n\n>\n>> My real question is on the right approach to generating a list of\n>> guides and including them into the git help options. I'm planning on\n>> extending the command-list.txt file to include 'guides' and then\n>> extending the generate-cmdlist.sh to generate a guides array in\n>> common-cmds.h.\n>\n> Having a catalog of guide documents in help.o sounds like a good way\n> to go, but I doubt \"command-list\" is a good place to store it. It\n> is about git subcommands, \"git help -a\" uses it to show the list of\n> them, and the bash completion support uses the list via \"git help -a\".\n>\n> The common-cmds.h does not have to be the only avenue to add your\n> catalog of guide documents to help.o. As a part of the build\n> procedure, you can list Documentation/guides/ and generate an array\n> definition into \"guides.h\", and add #include \"guides.h\" in help.c,\n> for example.\nAgreed in the sense I'd been thinking of doubling up the code but making \nuse of the \"command list\" with its categories did appear to kill two \nbirds with one stone. It could be that the shell script could simply \ngenerate the two .h files if appropriate.\n\n>\n>> I'm thinking of adding -g --guides and -c --commands options to\n>> complement the existing -a --all (becomes both commands and guides)\n>\n> Complement is fine. Contaminating -a with guides is probably not.\n\nMy view is that help --all (-a) is essentially incomplete as it \ncurrently doesn't provide all the help.\nThe -c option would provide just the commands for the command completion \ncase.\n\n>\n>> I was expecting to update the user-manual. to become\n>> gituser-manual.txt so that the existing 'git help user-manual' scheme\n>> would discover it. The Tutorial and the User manual obviously(?)\n>> being\n>> the first port of call for the confused user.\n>\n> Again, we do have pointer to tutorial fairly prominently at the\n> beginning of \"git(1)\". Perhaps we want index.html that redirects to\n> git.html or something?\n"},{"id":"209044","messageId":"7v6222za9x.fsf@alter.siamese.dyndns.org","threadId":"32861","inReplyTo":"6BC280F5827C4098BCB6276232DDE8E4@PhilipOakley","subject":"Re: Improve 'git help' with basic user guide linkss","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-02-08T22:54:50Z","receivedAt":"2013-02-08T22:54:50Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> My initial https://github.com/PhilipOakley/git/commit/e6217d simply\n> updates\n> - N_(\"See 'git help ' for more information on a specific\n> command.\");\n> + N_(\"See 'git help ' for more information on a specific\n> command.\\n\"\n> + \"Or 'git help ', such as 'tutorial' for an introduction\n> to Git.\");\n> as a starter for the new users.\n\nYeah, that would be a good change to make to \"git help\"\noutput.\n\n> My view is that help --all (-a) is essentially incomplete as it\n> currently doesn't provide all the help.\n\nIt has always been about \"tell me all subcommands\", not about \"give\nme all the help you could give me\". You are not adding a \"help\"\nsubcommand to a system you wrote last week. Changing the semantics\nthis late feels, eh, too late.\n"},{"id":"209047","messageId":"27C7EA38DDD345F994F01E5B8FB6D278@PhilipOakley","threadId":"32861","inReplyTo":"7v6222za9x.fsf@alter.siamese.dyndns.org","subject":"Re: Improve 'git help' with basic user guide linkss","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2013-02-08T23:04:58Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \nSent: Friday, February 08, 2013 10:54 PM\n> \"Philip Oakley\" writes:\n>\n>> My initial https://github.com/PhilipOakley/git/commit/e6217d simply\n>> updates\n>> - N_(\"See 'git help ' for more information on a specific\n>> command.\");\n>> + N_(\"See 'git help ' for more information on a specific\n>> command.\\n\"\n>> + \"Or 'git help ', such as 'tutorial' for an introduction\n>> to Git.\");\n>> as a starter for the new users.\n>\n> Yeah, that would be a good change to make to \"git help\"\n> output.\n\nI'll sort some patches early next week (the weekend's committed \nelsewhere)\n\n>\n>> My view is that help --all (-a) is essentially incomplete as it\n>> currently doesn't provide all the help.\n>\n> It has always been about \"tell me all subcommands\", not about \"give\n> me all the help you could give me\". You are not adding a \"help\"\n> subcommand to a system you wrote last week. Changing the semantics\n> this late feels, eh, too late.\n\nOK, I'll limit the the follow-ons to just an extra --guides option \n(probably just a list of the common guides initially), and \nleave --all(-a) for just the commands.\n"},{"id":"209360","messageId":"2DFA2C4F62AE484681753EBC3774D222@PhilipOakley","threadId":"32861","inReplyTo":"27C7EA38DDD345F994F01E5B8FB6D278@PhilipOakley","subject":"Re: Improve 'git help' with basic user guide linkss","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2013-02-12T10:33:42Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Philip Oakley\" \nSent: Friday, February 08, 2013 11:16 PM\n> From: \"Junio C Hamano\" \n> Sent: Friday, February 08, 2013 10:54 PM\n>> \"Philip Oakley\" writes:\n>>\n>>> My initial https://github.com/PhilipOakley/git/commit/e6217d simply\n>>> updates\n>>> - N_(\"See 'git help ' for more information on a specific\n>>> command.\");\n>>> + N_(\"See 'git help ' for more information on a specific\n>>> command.\\n\"\n>>> + \"Or 'git help ', such as 'tutorial' for an introduction\n>>> to Git.\");\n>>> as a starter for the new users.\n>>\n>> Yeah, that would be a good change to make to \"git help\"\n>> output.\n>\n> I'll sort some patches early next week (the weekend's committed \n> elsewhere)\n>\n>>\n>>> My view is that help --all (-a) is essentially incomplete as it\n>>> currently doesn't provide all the help.\n>>\n>> It has always been about \"tell me all subcommands\", not about \"give\n>> me all the help you could give me\". You are not adding a \"help\"\n>> subcommand to a system you wrote last week. Changing the semantics\n>> this late feels, eh, too late.\n>\n> OK, I'll limit the the follow-ons to just an extra --guides option \n> (probably just a list of the common guides initially), and \n> leave --all(-a) for just the commands.\n>\nThe Git man page includes the different command types listed by category \n(Main porcelain, Ancillary {manipulators, interrogators}, Interacting \nwith others, etc.).\n\nObviously (?) this is generated from the command-list.txt file, though I \ndon't see a shell script that would generate the \n'cmds-mainporcelain.txt' (etc.) files \n(//github.com/gitster/git-htmldocs). They are also part of the msysgit \ninstall.\n\nWhere should I be looking to see how they are generated?\n\nPhilip \n"},{"id":"209362","messageId":"20130212113731.GA13501@farnsworth.metanate.com","threadId":"32861","inReplyTo":"2DFA2C4F62AE484681753EBC3774D222@PhilipOakley","subject":"Re: Improve 'git help' with basic user guide linkss","fromName":"John Keeping","fromEmail":"john@keeping.me.uk","sentAt":"2013-02-12T11:37:31Z","receivedAt":"2013-02-12T11:37:31Z","isPatch":false,"sender":{"key":"john@keeping.me.uk","avatar":"https://avatars.githubusercontent.com/u/1702081?v=4"},"body":"On Tue, Feb 12, 2013 at 11:11:17AM -0000, Philip Oakley wrote:\n> Obviously (?) this is generated from the command-list.txt file, though I \n> don't see a shell script that would generate the \n> 'cmds-mainporcelain.txt' (etc.) files \n> (//github.com/gitster/git-htmldocs). They are also part of the msysgit \n> install.\n> \n> Where should I be looking to see how they are generated?\n\nDocumentation/cmd-list.perl\n\nIf you look in Documentation/Makefile, cmds-mainporcelain.txt is a\nmember of cmds_txt, which depends on cmd-list.made, which is a stamp\nfile created after invoking cmd-list.perl.\n\n\nJohn\n"},{"id":"209363","messageId":"6A83E216C322496CB2DEDFB2A68FE28F@PhilipOakley","threadId":"32861","inReplyTo":"20130212113731.GA13501@farnsworth.metanate.com","subject":"Re: Improve 'git help' with basic user guide linkss","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":null,"receivedAt":"2013-02-12T11:37:31Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"John Keeping\" \nSent: Tuesday, February 12, 2013 11:37 AM\n> On Tue, Feb 12, 2013 at 11:11:17AM -0000, Philip Oakley wrote:\n>> Obviously (?) this is generated from the command-list.txt file, \n>> though I\n>> don't see a shell script that would generate the\n>> 'cmds-mainporcelain.txt' (etc.) files\n>> (//github.com/gitster/git-htmldocs). They are also part of the \n>> msysgit\n>> install.\n>>\n>> Where should I be looking to see how they are generated?\n>\n> Documentation/cmd-list.perl\n>\n> If you look in Documentation/Makefile, cmds-mainporcelain.txt is a\n> member of cmds_txt, which depends on cmd-list.made, which is a stamp\n> file created after invoking cmd-list.perl.\n>\n>\n> John\n\nMany thanks - some easy reading while unwell ;-) \n"}]}