What should Python apps do when asked to show help?

[cs at zip.com.au]

On 01May2016 20:55, Steven D'Aprano <steve at pearwood.info> wrote:
>On Sun, 1 May 2016 05:28 pm, cs at zip.com.au wrote:
>> On 01May2016 16:44, Chris Angelico <rosuav at gmail.com> wrote:
>>>So you expect the environment variable to say which of multiple pagers
>>>you might want, but only when you already want a pager. Okay. How is
>>>an app supposed to know whether or not to use a pager? How do you
>>>expect them to mindread?
>>
>> I think for several of us, we do not expect the app to mindread. Don't
>> page for short output!
>
>Is there an environment variable to tell the application what you
>consider "short", or should it read your mind?

We're getting into matters of taste here. It shouldn't read my mind, but of 
course when it differs it shows bad taste!

I am taking the line that usage and help messages should fall into the "short" 
category, both simply by their nature and also as a design/style criterion for 
program authors. Manuals, be they man pages or info or whatever, should be 
"long", with specification and ideally explainations for rationale and some 
examples.

>Personally, I'd rather use a pager for 3 lines than print 30 lines of help
>text directly to the console, but others may feel differently.

And I am very much the opposite. ["foo --help"; "types next command; huh?  I'm 
in a pager, not back at my prompt?"]

However, with "less" configured to quit if the text fits on the screen (which 
is can usually determine by querying the terminal directly, no magic required), 
I get the best of both wolds, possibly to the point that I have rarely noticed 
that Python's help() pages.

And I've got mixed feelings about git. It seems that "git help" and "git 
--help" produces sensible unpaged short help (42 lines of it, but that is ok to 
me). It is "git help <subcommand>" which runs "man git-subcommand", and that is 
somewhat defensible because most of the git subcommands have an outrageous 
number of options.  (And it really does just invoke "man" (by default - that is 
also tunable I see); I can tell because it invokes my personal "man" command 
instead of the system one or some internally sourced text.)

My constrast, Mercurial (hg) always produces unpaged output for "help" and 
"help <subcommand>", and the "help <subcommand>" is succinct and fitting for a 
help text. There is a single large "man hg" for when you want the detailed 
manual. This approach is more to my liking.

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