Re: Improve 'git help' with basic user guide linkss
From: Philip Oakley philipoak...@iee.org
Sent: Friday, February 08, 2013 11:16 PM
From: Junio C Hamano gits...@pobox.com
Sent: Friday, February 08, 2013 10:54 PM
Philip Oakley philipoak...@iee.org writes:
My initial https://github.com/PhilipOakley/git/commit/e6217d simply
updates
- N_(See 'git help command' for more information on a specific
command.);
+ N_(See 'git help command' for more information on a specific
command.\n
+ Or 'git help guide', such as 'tutorial' for an introduction
to Git.);
as a starter for the new users.
Yeah, that would be a good change to make to git helpRETURN
output.
I'll sort some patches early next week (the weekend's committed
elsewhere)
My view is that help --all (-a) is essentially incomplete as it
currently doesn't provide all the help.
It has always been about tell me all subcommands, not about give
me all the help you could give me. You are not adding a help
subcommand to a system you wrote last week. Changing the semantics
this late feels, eh, too late.
OK, I'll limit the the follow-ons to just an extra --guides option
(probably just a list of the common guides initially), and
leave --all(-a) for just the commands.
The Git man page includes the different command types listed by category
(Main porcelain, Ancillary {manipulators, interrogators}, Interacting
with others, etc.).
Obviously (?) this is generated from the command-list.txt file, though I
don't see a shell script that would generate the
'cmds-mainporcelain.txt' (etc.) files
(//github.com/gitster/git-htmldocs). They are also part of the msysgit
install.
Where should I be looking to see how they are generated?
Philip
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Improve 'git help' with basic user guide linkss
On Tue, Feb 12, 2013 at 11:11:17AM -, Philip Oakley wrote: Obviously (?) this is generated from the command-list.txt file, though I don't see a shell script that would generate the 'cmds-mainporcelain.txt' (etc.) files (//github.com/gitster/git-htmldocs). They are also part of the msysgit install. Where should I be looking to see how they are generated? Documentation/cmd-list.perl If you look in Documentation/Makefile, cmds-mainporcelain.txt is a member of cmds_txt, which depends on cmd-list.made, which is a stamp file created after invoking cmd-list.perl. John -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Improve 'git help' with basic user guide linkss
From: John Keeping j...@keeping.me.uk Sent: Tuesday, February 12, 2013 11:37 AM On Tue, Feb 12, 2013 at 11:11:17AM -, Philip Oakley wrote: Obviously (?) this is generated from the command-list.txt file, though I don't see a shell script that would generate the 'cmds-mainporcelain.txt' (etc.) files (//github.com/gitster/git-htmldocs). They are also part of the msysgit install. Where should I be looking to see how they are generated? Documentation/cmd-list.perl If you look in Documentation/Makefile, cmds-mainporcelain.txt is a member of cmds_txt, which depends on cmd-list.made, which is a stamp file created after invoking cmd-list.perl. John Many thanks - some easy reading while unwell ;-) -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Improve 'git help' with basic user guide linkss
I'm looking at extending the 'git help' to include some information for the basic user who isn't ready for the extensive man page documentation for the various commands. If the user doesn't yet know which is the relevant command then they should also be offered a clue on how to finding the various guides. Many users are stuck on the 'If I were you I wouldn't start from here' step (many blog comments on the alleged poor documentation and difficulty of understanding ...). I've started on adding a few tweaks to the basic 'git help' message, adding an end line indicating that there are guides, such as 'tutorial'. Initial hacks at https://github.com/PhilipOakley/git/commits/morehelp for thos interested. My real question is on the right approach to generating a list of guides and including them into the git help options. I'm planning on extending the command-list.txt file to include 'guides' and then extending the generate-cmdlist.sh to generate a guides array in common-cmds.h. I'm thinking of adding -g --guides and -c --commands options to complement the existing -a --all (becomes both commands and guides) option. I'm not yet sure how to determine which other special guides should be listed (api- etc.) and when. I was expecting to update the user-manual. to become gituser-manual.txt so that the existing 'git help user-manual' scheme would discover it. The Tutorial and the User manual obviously(?) being the first port of call for the confused user. Does this appear sensible, and should the Documentation/* directories also be searched for 'guides', or is that a step too far [and it's less coding] ? Philip Oakley -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Improve 'git help' with basic user guide linkss
Philip Oakley philipoak...@iee.org writes: I'm looking at extending the 'git help' to include some information for the basic user who isn't ready for the extensive man page documentation for the various commands. We have pointers at the beginning of git(1) for that exact reason. I am not saying the documents pointed at from there are perfect, but shouldn't that approach work? My real question is on the right approach to generating a list of guides and including them into the git help options. I'm planning on extending the command-list.txt file to include 'guides' and then extending the generate-cmdlist.sh to generate a guides array in common-cmds.h. Having a catalog of guide documents in help.o sounds like a good way to go, but I doubt command-list is a good place to store it. It is about git subcommands, git help -a uses it to show the list of them, and the bash completion support uses the list via git help -a. The common-cmds.h does not have to be the only avenue to add your catalog of guide documents to help.o. As a part of the build procedure, you can list Documentation/guides/ and generate an array definition into guides.h, and add #include guides.h in help.c, for example. I'm thinking of adding -g --guides and -c --commands options to complement the existing -a --all (becomes both commands and guides) Complement is fine. Contaminating -a with guides is probably not. I was expecting to update the user-manual. to become gituser-manual.txt so that the existing 'git help user-manual' scheme would discover it. The Tutorial and the User manual obviously(?) being the first port of call for the confused user. Again, we do have pointer to tutorial fairly prominently at the beginning of git(1). Perhaps we want index.html that redirects to git.html or something? -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Improve 'git help' with basic user guide linkss
From: Junio C Hamano gits...@pobox.com Sent: Friday, February 08, 2013 8:53 PM Philip Oakley philipoak...@iee.org writes: I'm looking at extending the 'git help' to include some information for the basic user who isn't ready for the extensive man page documentation for the various commands. We have pointers at the beginning of git(1) for that exact reason. I am not saying the documents pointed at from there are perfect, but shouldn't that approach work? The problem for the new user is to find that page you need to know the command 'git help git' which is unlikely. We know where to find it, they don't. My initial https://github.com/PhilipOakley/git/commit/e6217d simply updates - N_(See 'git help command' for more information on a specific command.); + N_(See 'git help command' for more information on a specific command.\n + Or 'git help guide', such as 'tutorial' for an introduction to Git.); as a starter for the new users. It's then a case of providing an option to show the common and other guides. My real question is on the right approach to generating a list of guides and including them into the git help options. I'm planning on extending the command-list.txt file to include 'guides' and then extending the generate-cmdlist.sh to generate a guides array in common-cmds.h. Having a catalog of guide documents in help.o sounds like a good way to go, but I doubt command-list is a good place to store it. It is about git subcommands, git help -a uses it to show the list of them, and the bash completion support uses the list via git help -a. The common-cmds.h does not have to be the only avenue to add your catalog of guide documents to help.o. As a part of the build procedure, you can list Documentation/guides/ and generate an array definition into guides.h, and add #include guides.h in help.c, for example. Agreed in the sense I'd been thinking of doubling up the code but making use of the command list with its categories did appear to kill two birds with one stone. It could be that the shell script could simply generate the two .h files if appropriate. I'm thinking of adding -g --guides and -c --commands options to complement the existing -a --all (becomes both commands and guides) Complement is fine. Contaminating -a with guides is probably not. My view is that help --all (-a) is essentially incomplete as it currently doesn't provide all the help. The -c option would provide just the commands for the command completion case. I was expecting to update the user-manual. to become gituser-manual.txt so that the existing 'git help user-manual' scheme would discover it. The Tutorial and the User manual obviously(?) being the first port of call for the confused user. Again, we do have pointer to tutorial fairly prominently at the beginning of git(1). Perhaps we want index.html that redirects to git.html or something? -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Improve 'git help' with basic user guide linkss
Philip Oakley philipoak...@iee.org writes: My initial https://github.com/PhilipOakley/git/commit/e6217d simply updates - N_(See 'git help command' for more information on a specific command.); + N_(See 'git help command' for more information on a specific command.\n + Or 'git help guide', such as 'tutorial' for an introduction to Git.); as a starter for the new users. Yeah, that would be a good change to make to git helpRETURN output. My view is that help --all (-a) is essentially incomplete as it currently doesn't provide all the help. It has always been about tell me all subcommands, not about give me all the help you could give me. You are not adding a help subcommand to a system you wrote last week. Changing the semantics this late feels, eh, too late. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Improve 'git help' with basic user guide linkss
From: Junio C Hamano gits...@pobox.com Sent: Friday, February 08, 2013 10:54 PM Philip Oakley philipoak...@iee.org writes: My initial https://github.com/PhilipOakley/git/commit/e6217d simply updates - N_(See 'git help command' for more information on a specific command.); + N_(See 'git help command' for more information on a specific command.\n + Or 'git help guide', such as 'tutorial' for an introduction to Git.); as a starter for the new users. Yeah, that would be a good change to make to git helpRETURN output. I'll sort some patches early next week (the weekend's committed elsewhere) My view is that help --all (-a) is essentially incomplete as it currently doesn't provide all the help. It has always been about tell me all subcommands, not about give me all the help you could give me. You are not adding a help subcommand to a system you wrote last week. Changing the semantics this late feels, eh, too late. OK, I'll limit the the follow-ons to just an extra --guides option (probably just a list of the common guides initially), and leave --all(-a) for just the commands. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
