What should Python apps do when asked to show help?

[Random832]

On Thu, Apr 28, 2016, at 13:06, Chris Angelico wrote:
> On Fri, Apr 29, 2016 at 2:33 AM, Steven D'Aprano <steve at pearwood.info>
> wrote:
> > Many command line tools simply output help to stdout (or stderr, if they're
> > evil),
> 
> I'm not sure stderr is particularly more evil than stdout, but whatever
> :)

When a tool has very long help and sends it to stderr:

$ foo --help
ok, it's scrolled off the top, and I could just scroll up, but it's so
long I'll have to search for what I want anyway.
$ foo --help | less
*help flashes on the screen, then blank ~~~~~~ screen from less*
#@!@#$#$!#$!@#$@#!$@!#$!@#$!@#$!@#$!@#$
$ foo --help 2>&1 | less

Basically the only reason this ever happens is that programmers get lazy
and use the same function for usage errors as for --help. A usage error
message *should* go to stderr (in order to show up if the program's
output has been redirected to null, and so as not to be silently piped
to something that expects the program's normal output), but it should be
short. Help should go to stdout because the user actually requested it.

The obvious exception, and probably the bad example that people are
following, is programs that don't actually *have* --help, but briefly
summarize all their options and the meanings of positional arguments in
the usage error. People start with that, and then expand it to a
full-blown GNU-style --help message, but continue sending it to stderr.