From: "Junio C Hamano" <gitster@xxxxxxxxx>
Sent: Friday, February 08, 2013 8:53 PM
"Philip Oakley" <philipoakley@xxxxxxx> 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 majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html