What should Python apps do when asked to show help?

[Cameron Simpson]

On 29Apr2016 03:06, Chris Angelico <rosuav at gmail.com> wrote:
>On Fri, Apr 29, 2016 at 2:33 AM, Steven D'Aprano <steve at pearwood.info> wrote:
>> I have an application written in Python which accepts -h or --help to show
>> help. I can:
>>
>> (1) print the help text to stdout;
>>
>> (2) run the help text through a pager;
>>
>> (3) do something else?
>>
>>
>> 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 :)

I'm sure. If I _ask_ for the help information, it is not an error message.  
Instead it is desired output. The logic is clear.

If I screw up and elicit an error and the usage message (which might be the 
help text), that is an error message. But -h/--help? That is standard output, 
even if it is the same usage text.

And on this topic, let me preemptively flame commands whose entire usage 
message is "use -h/--help for usage". More evil.

>What you could do is run the help text through a pager only if stdout
>is a TTY. That allows it to be grepped conveniently, but also browsed
>easily. But I wouldn't worry about that unless you have at least 3-5
>pages of screed - for most programs, just dumping the text to a
>standard stream is usually enough.

+1 to this. I'm -0 on conditionally offering a pager based on isatty; Marko 
Rauhamaa has illustrated one downside, and personally I find _unexpectedly_ 
paged output to be jarring, requiring me to modeshift my brain.

So I'm for keeping it simple and just sending it to stdout.

Cheers,
Cameron Simpson <cs at zip.com.au>