Date: Mon, 9 Jan 2012 19:15:30 +1100 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Warren Block <wblock@wonkity.com> 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 Message-ID: <20120109183017.T1220@besplex.bde.org> In-Reply-To: <201201082105.q08L5EXm038909@red.freebsd.org> References: <201201082105.q08L5EXm038909@red.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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 <busnum> -a <devaddr> -i <ifaceindex> [cmds...]" "\n" > "usage: usbconfig -d [ugen]<busnum>.<devaddr> -i <ifaceindex> [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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20120109183017.T1220>