What should Python apps do when asked to show help?
cs at zip.com.au
cs at zip.com.au
Sun May 1 18:23:39 EDT 2016
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>
More information about the Python-list
mailing list