Re: Git documentation consistency

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

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

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.


>  I somehow doubt your ls
> would respond to "ls -X" any differently from "ls -?", but is giving the
> same canned response to any unknown option.

Indeed.  Whether it is useful for "-?" to give a more detailed summary
than the basic one-line usage message often depends on how complex the
command-line features are.  My preference is for '-?' (and if possible
'-h' as well) to give detailed usage info, though hopefully limited to
just one screen full if possible (though with Git's free use of $PAGER
in many contexts it might be OK to feed longer usage info to $PAGER
too).

So, the basic usage messages for command-line "syntax" problems should
be a one-line summary (following the error message).

If more detail could be useful then '-?' (and if possible '-h') should
display a more detailed usage message.  (and if one line suffices then
'-?' and '-h' don't really have to be treated specially)


> The "usage: ls [-AaBbC...] [file...]" indeed is much better than abstract
> "usage: frotz <options> <args>" that does not list what <options> are, but
> that is a totally different thing.  On that point, I think Peff already
> made a good suggestion of giving the full help text in such a case.

Indeed the abstract content-free "<options>" style message is almost
useless in most cases.

It would also be useful to reflect in the usage message what the driver
program saw as its argv[0], not what the internal command saw:

$ git rebase -X
Usage: /usr/pkg/libexec/git-core//git-rebase [--interactive | -i] [-v] [--onto <newbase>] <upstream> [<branch>]


Or perhaps this could be cleaned up with something as simple as always
stripping off the pathname with the likes of:

     argv0 = (argv0 = strrchr(argv[0], '/')) ? argv0 + 1 : argv[0];

-- 
						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 --]