Should the command line “usage” be printed on stdo

Question

When printing the "usage" of an application, should it be done on stdout or on stderr?

Depending on the application I've seen several cases, but there doesn't seem to be one rule. Maybe I'm mistaken and there is one good practice. In that case, what is it?

Answer 1

if --help then stdout, else stderr. Here's the 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);
}

Answer 2

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

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

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

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

4.7.2 --help

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

Near the end of the ‘--help’ option’s output, please place lines giving the email address for bug reports, the package’s home page (normally ‘http://www.gnu.org/software/pkg’, and the general page for help using GNU programs. The format should be like 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 mailing lists and web pages.

---

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

4.7.1 --version

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

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

GNU Emacs 19.30

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

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

emacsserver (GNU Emacs) 19.30

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

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

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

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

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

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

Here’s an example 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.

...