From nobody@FreeBSD.org  Sun Jan  8 21:05:14 2012
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 4C515106564A
	for <freebsd-gnats-submit@FreeBSD.org>; Sun,  8 Jan 2012 21:05:14 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from red.freebsd.org (red.freebsd.org [IPv6:2001:4f8:fff6::22])
	by mx1.freebsd.org (Postfix) with ESMTP id 378868FC12
	for <freebsd-gnats-submit@FreeBSD.org>; Sun,  8 Jan 2012 21:05:14 +0000 (UTC)
Received: from red.freebsd.org (localhost [127.0.0.1])
	by red.freebsd.org (8.14.4/8.14.4) with ESMTP id q08L5EM3038910
	for <freebsd-gnats-submit@FreeBSD.org>; Sun, 8 Jan 2012 21:05:14 GMT
	(envelope-from nobody@red.freebsd.org)
Received: (from nobody@localhost)
	by red.freebsd.org (8.14.4/8.14.4/Submit) id q08L5EXm038909;
	Sun, 8 Jan 2012 21:05:14 GMT
	(envelope-from nobody)
Message-Id: <201201082105.q08L5EXm038909@red.freebsd.org>
Date: Sun, 8 Jan 2012 21:05:14 GMT
From: Warren Block <wblock@wonkity.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: [patch] usbconfig(8) sends help output to stderr instead of stdout
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         163934
>Category:       bin
>Synopsis:       [patch] usbconfig(8) sends help output to stderr instead of stdout
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    eadler
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          sw-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Jan 08 21:10:14 UTC 2012
>Closed-Date:    Sun Jan 08 21:31:01 UTC 2012
>Last-Modified:  Tue Jan 10 12:40:09 UTC 2012
>Originator:     Warren Block
>Release:        8-STABLE
>Organization:
>Environment:
FreeBSD lightning 8.2-STABLE FreeBSD 8.2-STABLE #0: Sun Jan  8 08:18:21 MST 2012     root@lightning:/usr/obj/usr/src/sys/LIGHTNING  i386
>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"


>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-bugs->eadler 
Responsible-Changed-By: eadler 
Responsible-Changed-When: Sun Jan 8 21:12:26 UTC 2012 
Responsible-Changed-Why:  
I'll take it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=163934 
State-Changed-From-To: open->closed 
State-Changed-By: eadler 
State-Changed-When: Sun Jan 8 21:30:59 UTC 2012 
State-Changed-Why:  
style(9) says to keep usage() text on stderr 

http://www.freebsd.org/cgi/query-pr.cgi?pr=163934 

From: Bruce Evans <brde@optusnet.com.au>
To: Warren Block <wblock@wonkity.com>
Cc: freebsd-gnats-submit@freebsd.org, freebsd-bugs@freebsd.org
Subject: Re: bin/163934: [patch] usbconfig(8) sends help output to stderr
 instead of stdout
Date: Mon, 9 Jan 2012 19:15:30 +1100 (EST)

 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

From: Warren Block <wblock@wonkity.com>
To: Bruce Evans <brde@optusnet.com.au>
Cc: freebsd-gnats-submit@freebsd.org, freebsd-bugs@freebsd.org
Subject: Re: bin/163934: [patch] usbconfig(8) sends help output to stderr
 instead of stdout
Date: Mon, 9 Jan 2012 17:54:55 -0700 (MST)

 On Mon, 9 Jan 2012, Bruce Evans wrote:
 
 > 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.
 
 Yes.  My fault, I hadn't thought of that, er, usage of usage().  If 
 usage() output is caused by an error, it should go to stderr, to keep it 
 "out of band" of stdout.
 
 The user can request usage() output with -h or --help or something
 equivalent, and that output should go to stdout because it's not an 
 error and that data is what was requested.  IMO, of course.
 
 usbconfig doesn't actually have a -h option, usage() output is just a 
 default fall-through.

From: Bruce Evans <brde@optusnet.com.au>
To: Warren Block <wblock@wonkity.com>
Cc: Bruce Evans <brde@optusnet.com.au>, freebsd-bugs@freebsd.org,
        freebsd-gnats-submit@freebsd.org
Subject: Re: bin/163934: [patch] usbconfig(8) sends help output to stderr
 instead of stdout
Date: Tue, 10 Jan 2012 23:30:54 +1100 (EST)

 On Mon, 9 Jan 2012, Warren Block wrote:
 
 > The user can request usage() output with -h or --help or something
 > equivalent, and that output should go to stdout because it's not an error and 
 > that data is what was requested.  IMO, of course.
 
 This should probably be implemented by passing a FILE pointer to usage().
 
 > usbconfig doesn't actually have a -h option, usage() output is just a default 
 > fall-through.
 
 Ugh.  It documents -h in its man page.  Its code doesn't even use getopt().
 It uses a home made parser that accepts almost any random character as an
 equivalent for -h.
 
 Bruce
>Unformatted:
