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>