From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Greg A. Woods" Subject: Re: Git documentation consistency Date: Thu, 03 Dec 2009 02:22:41 -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_Thu_Dec__3_02:22:41_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 Thu Dec 03 08:22:55 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 1NG61b-0002GT-BK for gcvg-git-2@lo.gmane.org; Thu, 03 Dec 2009 08:22:51 +0100 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752465AbZLCHWj (ORCPT ); Thu, 3 Dec 2009 02:22:39 -0500 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1751635AbZLCHWj (ORCPT ); Thu, 3 Dec 2009 02:22:39 -0500 Received: from mail.robohack.planix.com ([204.92.254.2]:53370 "EHLO most.weird.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751341AbZLCHWi (ORCPT ); Thu, 3 Dec 2009 02:22:38 -0500 Received: from once.weird.com ([204.92.254.13] port=57303) by most.weird.com([204.92.254.2] port=25) via TCP with esmtp (4281 bytes) (sender: ) (ident using rfc1413) id for ; Thu, 3 Dec 2009 02:22:44 -0500 (EST) (Smail-3.2.0.122-Pre 2005-Nov-17 #1 built 2009-Feb-3) In-Reply-To: <7vaay096ye.fsf@alter.siamese.dyndns.org> User-Agent: Wanderlust/2.15.6 (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_Thu_Dec__3_02:22:41_2009-1 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable At Wed, 02 Dec 2009 17:34:01 -0800, Junio C Hamano wrot= e: Subject: Re: Git documentation consistency >=20 > 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 " that does not list what 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 "" 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] [--o= nto ] [] Or perhaps this could be cleaned up with something as simple as always stripping off the pathname with the likes of: argv0 =3D (argv0 =3D strrchr(argv[0], '/')) ? argv0 + 1 : argv[0]; --=20 Greg A. Woods Planix, Inc. +1 416 218 0099 http://www.planix.com/ --pgp-sign-Multipart_Thu_Dec__3_02:22:41_2009-1 Content-Type: application/pgp-signature Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (NetBSD) iD8DBQBLF2dBZn1xt3i/9H8RAgHmAJ44wa9Md+hcNlQGj735HzqmRYdAkACeMnBF OtEGp0BPN4tZyuiusBS/qWM= =q3s2 -----END PGP SIGNATURE----- --pgp-sign-Multipart_Thu_Dec__3_02:22:41_2009-1--