From: "Greg A. Woods" <woods@planix•com>
To: The Git Mailing List <git@vger•kernel.org>
Subject: Re: Git documentation consistency
Date: Wed, 09 Dec 2009 14:56:46 -0500 [thread overview]
Message-ID: <m1NISeX-000kmuC@most.weird.com> (raw)
In-Reply-To: <e51f66da0912030822ye1541b4gb1b8a3e07eb72484@mail.gmail.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 --]
next prev parent reply other threads:[~2009-12-09 19:56 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
2009-11-29 3:21 "git merge" merges too much! Greg A. Woods
2009-11-29 5:14 ` Jeff King
2009-11-30 18:12 ` Greg A. Woods
2009-11-30 19:22 ` Dmitry Potapov
2009-12-01 18:52 ` Greg A. Woods
2009-12-01 20:50 ` Dmitry Potapov
2009-12-01 21:58 ` Greg A. Woods
2009-12-02 0:22 ` Dmitry Potapov
2009-12-02 10:20 ` Nanako Shiraishi
2009-12-02 20:09 ` Jeff King
2009-12-03 1:21 ` Git documentation consistency (was: "git merge" merges too much!) Greg A. Woods
2009-12-03 1:34 ` Git documentation consistency Junio C Hamano
2009-12-03 7:22 ` Greg A. Woods
2009-12-03 7:45 ` Jeff King
2009-12-03 15:24 ` Uri Okrent
2009-12-03 16:22 ` Marko Kreen
2009-12-09 19:56 ` Greg A. Woods [this message]
2009-12-03 2:07 ` Git documentation consistency (was: "git merge" merges too much!) Jeff King
2009-11-29 5:15 ` "git merge" merges too much! Junio C Hamano
2009-11-30 18:40 ` Greg A. Woods
2009-11-30 20:50 ` Junio C Hamano
2009-11-30 21:17 ` Dmitry Potapov
2009-12-01 0:24 ` Greg A. Woods
2009-12-01 5:47 ` Dmitry Potapov
2009-12-01 17:59 ` multiple working directories for long-running builds (was: "git merge" merges too much!) Greg A. Woods
2009-12-01 18:51 ` Dmitry Potapov
2009-12-01 18:58 ` Greg A. Woods
2009-12-01 21:18 ` Dmitry Potapov
2009-12-01 22:25 ` Jeff Epler
2009-12-01 22:44 ` Greg A. Woods
2009-12-02 0:10 ` Dmitry Potapov
2009-12-03 5:11 ` Greg A. Woods
2009-12-02 2:09 ` multiple working directories for long-running builds Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=m1NISeX-000kmuC@most.weird.com \
--to=woods@planix$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox