From owner-freebsd-bugs@FreeBSD.ORG Mon Jan 9 08:15:36 2012 Return-Path: Delivered-To: freebsd-bugs@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 43EF01065675; Mon, 9 Jan 2012 08:15:36 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from mail08.syd.optusnet.com.au (mail08.syd.optusnet.com.au [211.29.132.189]) by mx1.freebsd.org (Postfix) with ESMTP id D5FC08FC16; Mon, 9 Jan 2012 08:15:35 +0000 (UTC) Received: from c211-30-171-136.carlnfd1.nsw.optusnet.com.au (c211-30-171-136.carlnfd1.nsw.optusnet.com.au [211.30.171.136]) by mail08.syd.optusnet.com.au (8.13.1/8.13.1) with ESMTP id q098FUp5009185 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 9 Jan 2012 19:15:33 +1100 Date: Mon, 9 Jan 2012 19:15:30 +1100 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Warren Block In-Reply-To: <201201082105.q08L5EXm038909@red.freebsd.org> Message-ID: <20120109183017.T1220@besplex.bde.org> References: <201201082105.q08L5EXm038909@red.freebsd.org> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Cc: freebsd-bugs@freebsd.org, freebsd-gnats-submit@freebsd.org Subject: Re: bin/163934: [patch] usbconfig(8) sends help output to stderr instead of stdout X-BeenThere: freebsd-bugs@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Bug reports List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 09 Jan 2012 08:15:36 -0000 On Sun, 8 Jan 2012, Warren Block wrote: >> Description: > usbconfig(8)'s -h option prints output to stderr. This output is not due to an error, and is already 28 lines line. A typical terminal will not display it all, so the user has to redirect stderr to view it with less or other utilities. >> How-To-Repeat: > usbconfig -h | less (then try to scroll back) >> Fix: > Apply attached patch. > > Patch attached with submission follows: > > Index: usbconfig.c > =================================================================== > --- usbconfig.c (revision 229822) > +++ usbconfig.c (working copy) > @@ -265,7 +265,7 @@ > static void > usage(void) > { > - fprintf(stderr, "" > + fprintf(stdout, "" > "usbconfig - configure the USB subsystem" "\n" > "usage: usbconfig -u -a -i [cmds...]" "\n" > "usage: usbconfig -d [ugen]. -i [cmds...]" "\n" This breaks the normal use of usage() for usage errors. Other, older bugs in usbconfig in this area are: - its usage message is verbose - its usage message doesn't match its man page synopsis (since that is actually a synopsis, so it is not verbose) A verbose usage message is especially not needed when there is a help option. I recently noticed even a gnu Configure script written in 2009 sending output for --help to stderr. The gnu standard has been for help to be given by `--help' and not by some random flag, and to go to stdout, since long before 2009. OTOH, for FreeBSD, there is usually no help option, and you had better get used to typing "... 2>&1 |less" or scrolling back to see verbose messages, or better yet, reading the man page. The man page for usbconfig is only 2.5 times longer than the usage messages, but that is because it is too short. It gives some examples, but it doesn't give a summary of the commands like the usage message does. It doesn't even mention most of commands. Some other commands with very verbose, but useful, usage messages that go to stderr are: - newfs (30 lines). As for usbconfig, the usage message doesn't resemble the man page synopsis, and the man page doesn't give a summary of the options (except in the synopsis where the summary is too short and hard to read since it is still long but not in a bullet point organization, though unlike for usbconfig, it is complete). Use of this style in newer commands is a style bug. - atacontrol (14 lines). Now the usage message matches the synopsis. This makes the synopsis too verbose but is otherwise good in the man page. The commands are sorted in "logical" order and 14 lines is just short enough for them to be easy to find (by reading the whole list). Normal programs have options and not so many commands, and normal man pages sort the options alphabetically. The style of the usage message was churned back and forth. In some versions of FreeBSD, it is reduced to a normal-looking 1-line usage message. In the same versions, it doesn't match the synopsis, since the synopsis has a summary of commands. A command that handles this quite differently, and probably best, is gnu tar. At least in the version that used to be in FreeBSD, the usage message for this goes to stderr and is: tar: invalid option -- ? Try `tar --help' for more information. and `tar --help' goes to stdout. Well, this is not very good either: - this takes more typing than "2>&1" - if we're going to switch the option, then we may as well switch the command to "man tar". This takes even less typing than "tar --help". - `tar --help' s so verbose that things are hard to find in it. Its style is gnuish and the man page's style is BSDish, so these outputs don't resemble each other. The man page output provides highlighting and alphabetical sorting of options which may make things easier to find in it, although it is 2.5 times as larger as the help output. Bruce