From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Greg A. Woods" Subject: Re: Git documentation consistency Date: Wed, 09 Dec 2009 14:56:46 -0500 Message-ID: References: <20091129051427.GA6104@coredump.intra.peff.net> <20091202200904.GA7631@coredump.intra.peff.net> <7vaay096ye.fsf@alter.siamese.dyndns.org> Reply-To: The Git Mailing List Mime-Version: 1.0 (generated by SEMI 1.14.6 - "Maruoka") Content-Type: multipart/signed; boundary="pgp-sign-Multipart_Wed_Dec__9_14:56:46_2009-1"; micalg=pgp-sha1; protocol="application/pgp-signature" Content-Transfer-Encoding: 7bit To: The Git Mailing List X-From: git-owner@vger.kernel.org Wed Dec 09 20:56:58 2009 Return-path: Envelope-to: gcvg-git-2@lo.gmane.org Received: from vger.kernel.org ([209.132.176.167]) by lo.gmane.org with esmtp (Exim 4.50) id 1NISef-0003ZF-BZ for gcvg-git-2@lo.gmane.org; Wed, 09 Dec 2009 20:56:57 +0100 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1757560AbZLIT4p (ORCPT ); Wed, 9 Dec 2009 14:56:45 -0500 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1757435AbZLIT4o (ORCPT ); Wed, 9 Dec 2009 14:56:44 -0500 Received: from mail.planix.com ([204.92.254.2]:54019 "EHLO most.weird.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1757392AbZLIT4n (ORCPT ); Wed, 9 Dec 2009 14:56:43 -0500 Received: from once.weird.com ([204.92.254.13] port=55492) by most.weird.com([204.92.254.2] port=25) via TCP with esmtp (4170 bytes) (sender: ) (ident using rfc1413) id for ; Wed, 9 Dec 2009 14:56:49 -0500 (EST) (Smail-3.2.0.122-Pre 2005-Nov-17 #1 built 2009-Feb-3) In-Reply-To: User-Agent: Wanderlust/2.15.7 (Almost Unreal) SEMI/1.14.6 (Maruoka) FLIM/1.14.7 (=?ISO-8859-4?Q?Sanj=F2?=) APEL/10.7 Emacs/22.3 (i386--netbsdelf) MULE/5.0 (SAKAKI) X-Face: ;j3Eth2XV8h1Yfu*uL{<:dQ$#E[DB0gemGZJ"J#4fH*][ lz;@-iwMv_u\6uIEKR0KY"=MzoQH#CrqBN`nG_5B@rrM8,f~Gr&h5a\= X-Mailing-List: git@vger.kernel.org Archived-At: --pgp-sign-Multipart_Wed_Dec__9_14:56:46_2009-1 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable At Thu, 3 Dec 2009 18:22:27 +0200, Marko Kreen wrote: Subject: Re: Git documentation consistency >=20 > On 12/3/09, Greg A. Woods wrote: > > At Wed, 02 Dec 2009 17:34:01 -0800, Junio C Hamano = 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. >=20 > '?' 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); } --=20 Greg A. Woods Planix, Inc. +1 416 218 0099 http://www.planix.com/ --pgp-sign-Multipart_Wed_Dec__9_14:56:46_2009-1 Content-Type: application/pgp-signature Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (NetBSD) iD8DBQBLIAD+Zn1xt3i/9H8RAvlqAJ4//0T26obSk3p/XE4PI/TOj86YjwCdHPxx cpQcoydhvfouLDwO0Z93SFE= =xkog -----END PGP SIGNATURE----- --pgp-sign-Multipart_Wed_Dec__9_14:56:46_2009-1--