At Thu, 3 Dec 2009 18:22:27 +0200, Marko Kreen <markokr@xxxxxxxxx> wrote:
Subject: Re: Git documentation consistency
>
> On 12/3/09, Greg A. Woods <woods@xxxxxxxxxx> wrote:
> > At Wed, 02 Dec 2009 17:34:01 -0800, Junio C Hamano <gitster@xxxxxxxxx> wrote:
> > Subject: Re: Git documentation consistency
> > > I think you are showing ignorance here, as -? is *not* even close to
> > > standard, nor even widely used practice at all.
> >
> > I think I should know something about Unix command line and option
> > parsers, having used them for some 25 years or so now. In fact I've
> > used most every kind of unix that ever was, and I've worked on the
> > source to more than a few.
>
> '?' is what getopt(3) is supposed to return for unknown options.
Indeed, which is why it cannot ever, in general, be used as a valid
option with some command-specific meaning, and so why the one-line form
of the usage message should always be displayed when the user explicitly
gives a '-?' option (i.e. in the same way as if any unknown option is
given).
If the one-line usage message is too terse to explain more complex
command line syntax then '-h' (and --help) should display a short
multi-line summary of the command's usage.
I guess what I should have suggested in the first place is that all Git
sub-commands should respond with a one-line[*] usage message when they
encounter an unknown option, such as '-?', and that they should (only)
display a more detailed multi-line help summary when given '-h' or
'--help' options.
I was most surprised when I didn't get a one-line usage summary from
"git log -?", just getopt(3)'s error message.
[*] commands which have multiple distinct modes of operation with
separate and unique command-line syntax for each mode, should of course
display a one-line summary for each command mode, such as in this
example:
void
usage(void)
{
fprintf(stderr, "Usage: %s [-abcdef]\n", getprogname());
fprintf(stderr, " %s [-l]\n", getprogname());
exit(2);
}
--
Greg A. Woods
Planix, Inc.
<woods@xxxxxxxxxx> +1 416 218 0099 http://www.planix.com/
Attachment:
pgplhri0GEArc.pgp
Description: PGP signature