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

Reply via email to