[ACCEPTED]-Should the command line "usage" be printed on stdout or stderr?-usage-message

Never thought about it, but why not write 8 the usage instructions to stderr if the 7 program was called with no or wrong arguments, and 6 write it to stdout when called with a --help (or 5 similar) argument? This way, if the usage 4 is shown because of an error, it goes to 3 stderr, and if it's not an error because 2 the user requested it, it goes to stdout. Seems 1 logical, somehow.

I agree that explicitly requested "usage" (through 19 a -h, -? or --help option) should go to 18 stdout while "usage" that is printed 17 in response to incorrect syntax or other 16 errors should go to stderr.

However, note 15 that the increasingly popular popt library 14 (which handles command line parsing; its 13 name stands for "parse options") includes 12 a facility for automatically generated help 11 and that it always sends that to stderr. I quote 10 the popt man page:

When --usage or --help 9 are passed to programs which use popt's automatic 8 help, popt displays the appropriate message 7 on stderr as soon as it finds the option, and 6 exits the program with a return code of 5 0.

I believe this to be a popt bug, but the 4 problem is that POSIX (or ISO C, to which 3 it defers) never defined what was meant 2 by "diagnostic output". Just 1 read 'man stderr' or POSIX.1-2008.

This can only be opinion, but I think writing 4 to stderr is the best thing to do. That 3 way the usage message appears if the user 2 makes a mistake even if the normal output 1 has been re-directed.

I'd use STDERR since simply putting it to 3 STDOUT might cause problems with piped output 2 and it will appear in the logs for cronjobs 1 so you notice the mistake easier.

I'm always bothered by programs that have 14 a lot of options that don't fit on screen, but 13 when run as program --help | less, I can't see anything since 12 the help was actually sent to stderr.

I like the 11 idea of explicitly requested usage (i.e. --help option) should 10 send output to stdout. In case of invalid options 9 I think it's not necessary to display detailed 8 usage information. There definitely should 7 be an error message like Invalid option "--some-option". Run "program --help" for usage information. sent to stderr. If the 6 program decides to output usage information 5 by default on invalid options or when invoked 4 without options, I think there should be 3 a short error message complaining about 2 invalid usage, but the help itself may go 1 to stdout.

if --help then stdout, else stderr. Here's the 1 JCommander code for Java users:

MyOptions myOptions = new MyOptions();
JCommander jCommander = new JCommander(myOptions);

try {
    jCommander.parse(args);
} catch (ParameterException exp) {
    /* print the exp here if you want */
    StringBuilder sb = new StringBuilder();
    jCommander.usage(sb);
    System.err.println(sb.toString());
    System.exit(1);
}

if(myOptions.isHelp()) {
    jCommander.usage();
    System.exit(0);
}

According to me, the criteria is how emergence 5 is the information. If it needs immediate 4 reaction or attention, I put it into stderr 3 (cause it's unbuffered). If it is somehow 2 informative and do not regard any errors 1 it is for stdout.

Should the command line “usage” be printed 74 on stdout or stderr?

I think it depends on 73 the organization's coding standards. Outside 72 an organization, its probably one of those 71 topics that are endlessly debated, like 70 which is the best operating system, which 69 is the best editor, which is the right religion, ...

Browsing 68 Java Code Conventions (SEPT 1997), Java does not specify it. There 67 is no answer, and it will be endlessly debated.

According 66 to GNU's coding standards, it should be printed on standard output:

4.7.2 --help

The 65 standard --help option should output brief 64 documentation for how to invoke the program, on 63 standard output, then exit successfully. Other 62 options and arguments should be ignored 61 once this is seen, and the program should 60 not perform its normal function.

Near the 59 end of the ‘--help’ option’s output, please 58 place lines giving the email address for 57 bug reports, the package’s home page (normally 56 ‘http://www.gnu.org/software/pkg’, and the general page for help using 55 GNU programs. The format should be like 54 this:

Report bugs to: mailing-address
pkg home page: <http://www.gnu.org/software/pkg/>
General help using GNU software: <http://www.gnu.org/gethelp/>

It is ok to mention other appropriate 53 mailing lists and web pages.

Here's the related 52 topic of "version". Its also from the GNU coding 51 guide, and it also writes to standard output:

4.7.1 --version

The 50 standard --version option should direct 49 the program to print information about 48 its name, version, origin and legal status, all 47 on standard output, and then exit successfully. Other 46 options and arguments should be ignored 45 once this is seen, and the program should not 44 perform its normal function.

The first line 43 is meant to be easy for a program to parse; the 42 version number proper starts after the 41 last space. In addition, it contains the 40 canonical name for this program, in this 39 format:

GNU Emacs 19.30

The program’s name should be a constant 38 string; don’t compute it from argv[0]. The 37 idea is to state the standard or canonical 36 name for the program, not its file name. There 35 are other ways to find out the precise 34 file name where a command is found in PATH.

If 33 the program is a subsidiary part of a larger 32 package, mention the package name in parentheses, like 31 this:

emacsserver (GNU Emacs) 19.30

If the package has a version number 30 which is different from this program’s 29 version number, you can mention the package 28 version number just before the close-parenthesis.

If 27 you need to mention the version numbers 26 of libraries which are distributed separately 25 from the package which contains this program, you 24 can do so by printing an additional line 23 of version info for each library you want 22 to mention. Use the same format for these 21 lines as for the first line.

Please do 20 not mention all of the libraries that the 19 program uses “just for completeness”—that 18 would produce a lot of unhelpful clutter. Please 17 mention library version numbers only if 16 you find in practice that they are very 15 important to you in debugging.

The following 14 line, after the version number line or lines, should 13 be a copyright notice. If more than one 12 copyright notice is called for, put each 11 on a separate line.

Next should follow a 10 line stating the license, preferably using 9 one of abbreviations below, and a brief 8 statement that the program is free software, and 7 that users are free to copy and change it. Also 6 mention that there is no warranty, to 5 the extent permitted by law. See recommended 4 wording below.

It is ok to finish the output 3 with a list of the major authors of the program, as 2 a way of giving credit.

Here’s an example 1 of output that follows these rules:

GNU hello 2.3
Copyright (C) 2007 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

...