On 11/03/2013 05:03, Junio C Hamano wrote:
Hmm, I feel more confused than convinced after reading the above
three times. Perhaps that is because I am too used to the way how
"git" potty itself behaves, especially the part that "git help git"
is the way to ask "git" (the first token on the command line) to
give me "help" about "git" (the second) itself.
But you are nowhere told that "git help" will give you information on
any topic other than Git commands. Starting from just typing "git", all
you are told is that you can type "git help <command>". Given that
information, you could at least logically deduce that "git help help"
will give you help on "git help". (Not that it would help anyway - even
git-help.txt doesn't say that you can specify anything other than a Git
command, like "git" or "cli". But sounds like Philip's already on there
case there).
If you can figure out "man git" for yourself (and if it's available -
Windows?) then from there you're explicitly told how to directly access
all the other docs using man itself, including gitrevisions(7), etc.
And having gotten to "man gitrevisions", I figured out that "git help
revisions" could get to the HTML equivalent. Not documented, but at
least fits the pattern, give or take a hyphen. But I never figured out
"git help git", until I read the source. Why do I need to add the extra
"git" to the help command for that page, and that page only? "git" isn't
a Git command, and there's no "man gitgit" topic! Even if I explicitly
try to point explicitly that I want a web page with "git help -w", I
don't get it...
I think at the very minimum you need to make it explicitly clear right
up front that "git help git" is available:
See 'git help git' for more information on Git
See 'git help <command>' for more information on a specific command.
Seems ugly though. I'm at a loss to understand why "git help", the
manual launching command, shouldn't by default simply launch the root of
the manual tree, rather than replicate the behaviour of "git"/"git --help".
And something needs to be done to advertise the general existence of
usage on commands. "-h" is currently hidden on page 4 of "man gitcli".
(Is it anywhere else?) I've managed to avoid finding out about it for
years! Checking a few people around me, none of them knew about it either.
At the minute "git" tells you about "git --help", which shows usage, but
"git add --help" launches the manual. (Huh?) Given that, I always
assumed there was no usage available for individual commands - if there
was usage, surely it would be there on --help, like on "git". Never
occurred to me it would be there under "-h" instead.
So how about going further than that patch, and making it even simpler.
Collapse --help and -h to be synonyms. Then under either spelling,
--help|-h always shows usage for "git" or "git <command>", as per GNU
guidelines.
Then the manual launch only happens for "git help ..." and, "git help"
on its own launches the root. And the output of "git [--help]" ends with:
See 'git help [<command>]' for more information.
Kevin
--
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
