Re: What should Python apps do when asked to show help?

Path	csiph.com!feeder.erje.net!1.eu.feeder.erje.net!news2.arglkargh.de!news.karotte.org!fu-berlin.de!uni-berlin.de!not-for-mail
From	Cameron Simpson <cs@zip.com.au>
Newsgroups	comp.lang.python
Subject	Re: What should Python apps do when asked to show help?
Date	Fri, 29 Apr 2016 05:49:36 +1000
Lines	41
Message-ID	<mailman.213.1461874569.32212.python-list@python.org> (permalink)
References	<CAPTjJmo+p7J0wsX_RKBXH43zMDJ0n2NB0mag-LGO6BBzyqv7OQ@mail.gmail.com> <20160428194936.GA19597@cskk.homeip.net>
Mime-Version	1.0
Content-Type	text/plain; charset=us-ascii; format=flowed
X-Trace	news.uni-berlin.de blAsKpKmFZQSR16N8tCLBQGiomEHDElDhKjO0qTT8AbA==
Return-Path	<cameron@cskk.homeip.net>
X-Original-To	python-list@python.org
Delivered-To	python-list@mail.python.org
X-Spam-Status	OK 0.000
X-Spam-Evidence	'H': 1.00; 'S': 0.00; 'subject:Python': 0.05; 'subject:help': 0.07; 'logic': 0.09; 'output,': 0.09; 'stderr': 0.09; 'stdout': 0.09; 'python': 0.10; 'output': 0.13; '"use': 0.16; '--help': 0.16; '-h/--help': 0.16; '2016': 0.16; '>on': 0.16; 'clear.': 0.16; 'enough.': 0.16; 'from:addr:cs': 0.16; 'from:addr:zip.com.au': 0.16; 'from:name:cameron simpson': 0.16; 'message-id:@cskk.homeip.net': 0.16; 'received:211.29': 0.16; 'received:211.29.132': 0.16; 'received:cskk.homeip.net': 0.16; 'received:homeip.net': 0.16; 'received:io': 0.16; 'received:optusnet.com.au': 0.16; 'received:psf.io': 0.16; 'received:syd.optusnet.com.au': 0.16; 'simpson': 0.16; 'subject:show': 0.16; 'subject:when': 0.16; 'sure.': 0.16; 'wrote:': 0.16; "wouldn't": 0.16; 'to:name:python- list@python.org': 0.20; 'cheers,': 0.22; 'am,': 0.23; '(or': 0.23; 'help.': 0.23; 'written': 0.24; 'header:In-Reply-To:1': 0.24; 'header:User-Agent:1': 0.26; 'command': 0.26; '(which': 0.26; 'chris': 0.26; 'error': 0.27; 'fri,': 0.27; 'least': 0.27; 'this.': 0.28; '3-5': 0.29; 'accepts': 0.29; 'allows': 0.30; "i'm": 0.30; 'print': 0.30; 'skip:_ 10': 0.32; 'run': 0.33; 'message.': 0.33; 'usually': 0.33; "d'aprano": 0.33; 'received:com.au': 0.33; 'steven': 0.33; 'stream': 0.33; 'could': 0.35; 'text': 0.35; 'requiring': 0.35; 'text.': 0.35; 'something': 0.35; 'but': 0.36; 'instead': 0.36; '(3)': 0.36; 'to:addr:python- list': 0.36; 'subject:?': 0.36; 'subject:: ': 0.37; '(2)': 0.37; 'desired': 0.37; 'charset:us-ascii': 0.37; '(1)': 0.38; 'sure': 0.39; 'whatever': 0.39; 'application': 0.39; 'to:addr:python.org': 0.40; 'information,': 0.61; 'entire': 0.61; 'personally': 0.61; 'show': 0.62; 'more': 0.63; 'offering': 0.66; 'cameron': 0.66; "they're": 0.66; 'programs,': 0.72; 'topic,': 0.79; 'can:': 0.84; 'flame': 0.84; 'illustrated': 0.84
Content-Disposition	inline
In-Reply-To	<CAPTjJmo+p7J0wsX_RKBXH43zMDJ0n2NB0mag-LGO6BBzyqv7OQ@mail.gmail.com>
User-Agent	Mutt/1.5.24 (2015-08-30)
X-Optus-CM-Score	0
X-Optus-CM-Analysis	v=2.1 cv=c+ZWOkJl c=1 sm=1 tr=0 a=kPLexIa+XrsL4mdc8kxeNA==:117 a=kPLexIa+XrsL4mdc8kxeNA==:17 a=L9H7d07YOLsA:10 a=9cW_t1CCXrUA:10 a=s5jvgZ67dGcA:10 a=kj9zAlcOel0A:10 a=kziv93cY1bsA:10 a=pGLkceISAAAA:8 a=kZ7UWmmPAAAA:8 a=vrnE16BAAAAA:8 a=8zbU8KkEPL18KVOhKvIA:9 a=CjuIK1q_8ugA:10
X-BeenThere	python-list@python.org
X-Mailman-Version	2.1.22
Precedence	list
List-Id	General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe	<https://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive	<http://mail.python.org/pipermail/python-list/>
List-Post	<mailto:python-list@python.org>
List-Help	<mailto:python-list-request@python.org?subject=help>
List-Subscribe	<https://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
X-Mailman-Original-Message-ID	<20160428194936.GA19597@cskk.homeip.net>
X-Mailman-Original-References	<CAPTjJmo+p7J0wsX_RKBXH43zMDJ0n2NB0mag-LGO6BBzyqv7OQ@mail.gmail.com>
Xref	csiph.com comp.lang.python:107831

Show key headers only | View raw

On 29Apr2016 03:06, Chris Angelico <rosuav@gmail.com> wrote:
>On Fri, Apr 29, 2016 at 2:33 AM, Steven D'Aprano <steve@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@zip.com.au>

Back to comp.lang.python | Previous | Next | Find similar | Unroll thread

Thread

Re: What should Python apps do when asked to show help? Cameron Simpson <cs@zip.com.au> - 2016-04-29 05:49 +1000

csiph-web