Re: Git documentation consistency

["Greg A. Woods" <woods@planix.com>]

[-- Attachment #1: Type: text/plain, Size: 2174 bytes --]

At Thu, 3 Dec 2009 18:22:27 +0200, Marko Kreen <markokr@gmail.com> wrote:
Subject: Re: Git documentation consistency
> 
> On 12/3/09, Greg A. Woods <woods@planix.com> wrote:
> > At Wed, 02 Dec 2009 17:34:01 -0800, Junio C Hamano <gitster@pobox.com> 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@planix.com>       +1 416 218 0099        http://www.planix.com/

[-- Attachment #2: Type: application/pgp-signature, Size: 186 bytes --]