Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #107801 > unrolled thread

What should Python apps do when asked to show help?

Back to article view | Back to comp.lang.python

Contents

  What should Python apps do when asked to show help? Steven D'Aprano <steve@pearwood.info> - 2016-04-29 02:33 +1000
    Re: What should Python apps do when asked to show help? alister <alister.ware@ntlworld.com> - 2016-04-28 16:45 +0000
      RE: What should Python apps do when asked to show help? Dan Strohl <D.Strohl@F5.com> - 2016-04-28 17:02 +0000
      Re: What should Python apps do when asked to show help? John Wong <gokoproject@gmail.com> - 2016-04-28 13:05 -0400
      RE: What should Python apps do when asked to show help? Dan Strohl <D.Strohl@F5.com> - 2016-04-28 17:25 +0000
      Re: What should Python apps do when asked to show help? Ethan Furman <ethan@stoneleaf.us> - 2016-04-28 10:27 -0700
    Re: What should Python apps do when asked to show help? Ethan Furman <ethan@stoneleaf.us> - 2016-04-28 09:49 -0700
    Re: What should Python apps do when asked to show help? Chris Angelico <rosuav@gmail.com> - 2016-04-29 03:06 +1000
    Re: What should Python apps do when asked to show help? Irmen de Jong <irmen.NOSPAM@xs4all.nl> - 2016-04-28 19:08 +0200
      Re: What should Python apps do when asked to show help? Marko Rauhamaa <marko@pacujo.net> - 2016-04-28 20:31 +0300
        Re: What should Python apps do when asked to show help? Gregory Ewing <greg.ewing@canterbury.ac.nz> - 2016-04-29 18:04 +1200
      RE: What should Python apps do when asked to show help? Dan Strohl <D.Strohl@F5.com> - 2016-04-28 17:32 +0000
    Re: What should Python apps do when asked to show help? Jussi Piitulainen <jussi.piitulainen@helsinki.fi> - 2016-04-28 20:30 +0300
    Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-28 13:30 -0400
    Re: What should Python apps do when asked to show help? Grant Edwards <grant.b.edwards@gmail.com> - 2016-04-28 17:33 +0000
    RE: What should Python apps do when asked to show help? Dan Strohl <D.Strohl@F5.com> - 2016-04-28 17:39 +0000
    Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-28 13:40 -0400
    Re: What should Python apps do when asked to show help? Grant Edwards <grant.b.edwards@gmail.com> - 2016-04-28 18:14 +0000
      Re: What should Python apps do when asked to show help? Marko Rauhamaa <marko@pacujo.net> - 2016-04-28 21:31 +0300
        Re: What should Python apps do when asked to show help? Grant Edwards <grant.b.edwards@gmail.com> - 2016-04-28 19:39 +0000
        Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-28 15:51 -0400
        Re: What should Python apps do when asked to show help? Grant Edwards <grant.b.edwards@gmail.com> - 2016-04-28 21:08 +0000
          Re: What should Python apps do when asked to show help? Steven D'Aprano <steve@pearwood.info> - 2016-04-29 11:40 +1000
            manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] "Martin A. Brown" <martin@linux-ip.net> - 2016-04-29 06:32 -0700
            Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Ethan Furman <ethan@stoneleaf.us> - 2016-04-29 07:06 -0700
              Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Rustom Mody <rustompmody@gmail.com> - 2016-04-29 08:17 -0700
            Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Ben Finney <ben+python@benfinney.id.au> - 2016-04-30 12:25 +1000
              Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Rustom Mody <rustompmody@gmail.com> - 2016-04-29 20:20 -0700
                Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Paul Rubin <no.email@nospam.invalid> - 2016-04-29 21:06 -0700
                  Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Rustom Mody <rustompmody@gmail.com> - 2016-04-29 23:37 -0700
                    Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?] Paul Rubin <no.email@nospam.invalid> - 2016-04-30 00:44 -0700
            Writing manual pages using Python code (was: manpage writing) Ben Finney <ben+python@benfinney.id.au> - 2016-04-30 12:25 +1000
            Re: What should Python apps do when asked to show help? cs@zip.com.au - 2016-05-01 10:06 +1000
    Re: What should Python apps do when asked to show help? Paul Rubin <no.email@nospam.invalid> - 2016-04-28 19:15 -0700
      Re: What should Python apps do when asked to show help? Rustom Mody <rustompmody@gmail.com> - 2016-04-28 22:00 -0700
        Re: What should Python apps do when asked to show help? Jussi Piitulainen <jussi.piitulainen@helsinki.fi> - 2016-04-29 09:02 +0300
        Re: What should Python apps do when asked to show help? Steven D'Aprano <steve@pearwood.info> - 2016-04-29 19:36 +1000
          Re: What should Python apps do when asked to show help? Rustom Mody <rustompmody@gmail.com> - 2016-04-29 02:53 -0700
            Re: What should Python apps do when asked to show help? Steven D'Aprano <steve@pearwood.info> - 2016-04-30 11:20 +1000
              Re: What should Python apps do when asked to show help? Ethan Furman <ethan@stoneleaf.us> - 2016-04-29 19:09 -0700
              Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-29 22:16 -0400
                Re: What should Python apps do when asked to show help? Rustom Mody <rustompmody@gmail.com> - 2016-04-29 19:27 -0700
                  Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-29 22:36 -0400
                    Re: What should Python apps do when asked to show help? Rustom Mody <rustompmody@gmail.com> - 2016-04-29 19:46 -0700
                      Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-29 23:14 -0400
                  Re: What should Python apps do when asked to show help? Ben Finney <ben+python@benfinney.id.au> - 2016-04-30 12:49 +1000
                    Re: What should Python apps do when asked to show help? Steven D'Aprano <steve@pearwood.info> - 2016-04-30 13:23 +1000
                      Re: What should Python apps do when asked to show help? Ben Finney <ben+python@benfinney.id.au> - 2016-04-30 14:06 +1000
                      Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-30 00:16 -0400
                        Re: What should Python apps do when asked to show help? Rustom Mody <rustompmody@gmail.com> - 2016-04-29 21:34 -0700
                      Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-30 01:20 -0400
                      Re: What should Python apps do when asked to show help? cs@zip.com.au - 2016-05-01 09:51 +1000
                        Re: What should Python apps do when asked to show help? Steven D'Aprano <steve@pearwood.info> - 2016-05-01 14:28 +1000
                      Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-30 20:41 -0400
                      Re: What should Python apps do when asked to show help? Grant Edwards <grant.b.edwards@gmail.com> - 2016-05-01 02:30 +0000
                      Re: What should Python apps do when asked to show help? Random832 <random832@fastmail.com> - 2016-04-30 23:46 -0400

Page 1 of 3  [1] 2 3  Next page →

#107801 — What should Python apps do when asked to show help?

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), which makes it easy to redirect the help to a file, pass it to grep,
etc. For example:

[steve@ando ~]$ wget --help | wc -l
136

Other tools automatically launch a pager, e.g. man. (Admittedly, man --help
does not use a pager.) The Python help system, pydoc, does the same.

I was thinking that my application could use pydoc:

def do_help():
    import pydoc
    pydoc.pager(HELPTEXT)

or just print the help text:

def do_help():
    # Do I really need to show this???
    print(HELPTEXT)


but I was thinking of doing both: give my application a subcommand or an
option to display help directly in a pager, while -h and --help print to
stdout as normal.

What do you think? Too clever?



-- 
Steven

[toc] | [next] | [standalone]

#107802

On Fri, 29 Apr 2016 02:33:56 +1000, Steven D'Aprano 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), which makes it easy to redirect the help to a file, pass
> it to grep,
> etc. For example:
> 
> [steve@ando ~]$ wget --help | wc -l 136
> 
> Other tools automatically launch a pager, e.g. man. (Admittedly, man
> --help does not use a pager.) The Python help system, pydoc, does the
> same.
> 
> I was thinking that my application could use pydoc:
> 
> def do_help():
>     import pydoc pydoc.pager(HELPTEXT)
> 
> or just print the help text:
> 
> def do_help():
>     # Do I really need to show this???
>     print(HELPTEXT)
> 
> 
> but I was thinking of doing both: give my application a subcommand or an
> option to display help directly in a pager, while -h and --help print to
> stdout as normal.
> 
> What do you think? Too clever?

Send it to stdout, this gives the user the most choice.

if there is enough that I want it paged then I will pipe it to a pager.

do one job, do it well and don't reinvent the wheel unnecessarily. 



-- 
Nobody shot me.
		-- Frank Gusenberg, his last words, when asked by police
		who had shot him 14 times with a machine gun in the Saint
		Valentine's Day Massacre.

Only Capone kills like that.
		-- George "Bugs" Moran, on the Saint Valentine's Day 
Massacre

The only man who kills like that is Bugs Moran.
		-- Al Capone, on the Saint Valentine's Day Massacre

[toc] | [prev] | [next] | [standalone]

#107807

I would suggest using argparse https://docs.python.org/3/library/argparse.html as it handles all of that natively... including validating arguments, showing errors, help, etc... however, assuming you don't want to;

Send it to stdout, that allows the user to redirect it if they want to (and plays better with other dev-ops tools)

Don't run it through a pager, the user can do that if needed... HOWEVER
- If you have enough help that you need to page it, consider moving much of it to application documentation (either hosted, or as a doc / txt file).  The command line help should simply be enough hints to remember what the various parameters are, not a full explanation about what it can do (unless the app is really simple).
- Alternatively, you can have a multi-level help approach where the user can type "app_name argument /help" and get more detailed information about that specific argument.


> -----Original Message-----
> From: Python-list [mailto:python-list-bounces+d.strohl=f5.com@python.org]
> On Behalf Of alister
> Sent: Thursday, April 28, 2016 9:45 AM
> To: python-list@python.org
> Subject: Re: What should Python apps do when asked to show help?
> 
> On Fri, 29 Apr 2016 02:33:56 +1000, Steven D'Aprano 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), which makes it easy to redirect the help to a file,
> > pass it to grep, etc. For example:
> >
> > [steve@ando ~]$ wget --help | wc -l 136
> >
> > Other tools automatically launch a pager, e.g. man. (Admittedly, man
> > --help does not use a pager.) The Python help system, pydoc, does the
> > same.
> >
> > I was thinking that my application could use pydoc:
> >
> > def do_help():
> >     import pydoc pydoc.pager(HELPTEXT)
> >
> > or just print the help text:
> >
> > def do_help():
> >     # Do I really need to show this???
> >     print(HELPTEXT)
> >
> >
> > but I was thinking of doing both: give my application a subcommand or
> > an option to display help directly in a pager, while -h and --help
> > print to stdout as normal.
> >
> > What do you think? Too clever?
> 
> Send it to stdout, this gives the user the most choice.
> 
> if there is enough that I want it paged then I will pipe it to a pager.
> 
> do one job, do it well and don't reinvent the wheel unnecessarily.
> 
> 
> 
> --
> Nobody shot me.
> 		-- Frank Gusenberg, his last words, when asked by police
> 		who had shot him 14 times with a machine gun in the Saint
> 		Valentine's Day Massacre.
> 
> Only Capone kills like that.
> 		-- George "Bugs" Moran, on the Saint Valentine's Day
> Massacre
> 
> The only man who kills like that is Bugs Moran.
> 		-- Al Capone, on the Saint Valentine's Day Massacre
> --
> https://mail.python.org/mailman/listinfo/python-list

[toc] | [prev] | [next] | [standalone]

#107808

On Thu, Apr 28, 2016 at 1:02 PM, Dan Strohl via Python-list <
python-list@python.org> wrote:

> I would suggest using argparse
> https://docs.python.org/3/library/argparse.html as it handles all of that
> natively... including validating arguments, showing errors, help, etc...
> however, assuming you don't want to;
>
> Totally agree with this approach. Command line should stick with argparse.
Personally I'd stick with argparse and not other open source projects which
is built on argparse (or optparse, the one you don't want to use, but eh
some people decided to do that anyway because of some limitations in
argparse).

In fact you shouldn't need to implement -h/--help when you use argparse. If
a user is going to use the command line, you can almost always assume the
user can use -h/--help, or for those familiar with Linux just provide a man
page.

After all, what you need is a very clear documentation upfront prior to the
installation so your users can refer to that for ultimate help.

[toc] | [prev] | [next] | [standalone]

#107811

Yeah, if I am handling arguments from the command line, I use argparse, if I am doing a cli based app (so, going back and forth in interacting with the command line), I would look at clint (https://github.com/kennethreitz/clint)

As many people have said here, don’t reinvent the wheel.

Dan


From: John Wong [mailto:gokoproject@gmail.com]
Sent: Thursday, April 28, 2016 10:06 AM
To: Dan Strohl <D.Strohl@F5.com>
Cc: alister <alister.ware@ntlworld.com>; python-list@python.org
Subject: Re: What should Python apps do when asked to show help?



On Thu, Apr 28, 2016 at 1:02 PM, Dan Strohl via Python-list <python-list@python.org<mailto:python-list@python.org>> wrote:
I would suggest using argparse https://docs.python.org/3/library/argparse.html as it handles all of that natively... including validating arguments, showing errors, help, etc... however, assuming you don't want to;
Totally agree with this approach. Command line should stick with argparse. Personally I'd stick with argparse and not other open source projects which is built on argparse (or optparse, the one you don't want to use, but eh some people decided to do that anyway because of some limitations in argparse).

In fact you shouldn't need to implement -h/--help when you use argparse. If a user is going to use the command line, you can almost always assume the user can use -h/--help, or for those familiar with Linux just provide a man page.

After all, what you need is a very clear documentation upfront prior to the installation so your users can refer to that for ultimate help.

[toc] | [prev] | [next] | [standalone]

#107812

On 04/28/2016 10:02 AM, Dan Strohl via Python-list wrote:

> I would suggest using argparse https://docs.python.org/3/library/argparse.html as it handles all of that natively...

On the other hand, if you feel that argparse is akin to using a canon to 
kill a mosquito, you can try scription*:

- not argparse based
- simple to use
- supports flags, options, multioptions
- supports --help (and -h if no other parameter uses that abbreviation)
- supports --verbose (and -v of no other . . .)
- supports --version
- script parameters are global
- (sub)command parameters are local

--
~Ethan~

* https://pypi.python.org/pypi/scription

P.S.  Yes, my package.  ;)  Created both for the learning, and because I 
feel like argparse is overpowered, complicated, and un-fun for scripts.

[toc] | [prev] | [next] | [standalone]

#107806

On 04/28/2016 09:33 AM, Steven D'Aprano 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?

I think if the user is proficient enough to:

a) run the program from the command line, and

b) use the -h / --help switch

that they are proficient enough to efficiently use said help when output 
to stdout.

--
~Ethan~

[toc] | [prev] | [next] | [standalone]

#107809

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 :)

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.

ChrisA

[toc] | [prev] | [next] | [standalone]

#107810

On 28-4-2016 18:33, Steven D'Aprano wrote:


> but I was thinking of doing both: give my application a subcommand or an
> option to display help directly in a pager, while -h and --help print to
> stdout as normal.
> 
> What do you think? Too clever?

An idea: Use just one help option, then

if sys.stdout.isatty():
    #....use a pager to display help text
else:
    #....print all help text normally


Irmen

[toc] | [prev] | [next] | [standalone]

#107815

Irmen de Jong <irmen.NOSPAM@xs4all.nl>:

> An idea: Use just one help option, then
>
> if sys.stdout.isatty():
>     #....use a pager to display help text
> else:
>     #....print all help text normally

I've seen that used, but I find it annoying:

========================================================================
$ man ls
WARNING: terminal is not fully functional
-  (press RETURN)
========================================================================

========================================================================
$ git diff
WARNING: terminal is not fully functional
-  (press RETURN)
========================================================================

when run in emacs' Shell Mode.

Even Ctrl-C doesn't get me out of it. I curse to myself and run again:

========================================================================
$ git diff | cat
...
========================================================================


Marko

[toc] | [prev] | [next] | [standalone]

#107842

> Irmen de Jong <irmen.NOSPAM@xs4all.nl>:
> 
>>if sys.stdout.isatty():
>>    #....use a pager to display help text
>>else:
>>    #....print all help text normally

I think nowadays it's an anti-pattern for programs to
do their own pagination. Very often the "terminal" is
a GUI application with its own facilities for scrolling
and searching that are much nicer to use. I prefer the
program to just give me the output and get out of the
way. If I want a clunky tty-oriented pager I'll pipe
it to "more".

-- 
Greg

[toc] | [prev] | [next] | [standalone]

#107816

I would hesitate to take this approach unless the tool was one that only I was going to be using, and I knew exactly what environments it was going to be in.

I know that many of the system items in python work differently in different operating systems, and different os's report things differently as well as different ways of launching things.  So, for example, I have seen cases where tools such as webmin will try to run a command line tool, and end up hung because they are waiting on a keypress for the next screen... 

While I might do it as a way of setting a default, I would still want to have the ability to force a pager, or force no pager.  I've been bit too many times by programmers doing things automatically for me that I didn't want.

I think that most people who use command line tools these days will be able to figure out how to pipe it to "more" if needed (or whatever).

Dan


> -----Original Message-----
> From: Python-list [mailto:python-list-bounces+d.strohl=f5.com@python.org]
> On Behalf Of Irmen de Jong
> Sent: Thursday, April 28, 2016 10:08 AM
> To: python-list@python.org
> Subject: Re: What should Python apps do when asked to show help?
> 
> On 28-4-2016 18:33, Steven D'Aprano wrote:
> 
> 
> > but I was thinking of doing both: give my application a subcommand or
> > an option to display help directly in a pager, while -h and --help
> > print to stdout as normal.
> >
> > What do you think? Too clever?
> 
> An idea: Use just one help option, then
> 
> if sys.stdout.isatty():
>     #....use a pager to display help text
> else:
>     #....print all help text normally
> 
> 
> Irmen
> 
> --
> https://mail.python.org/mailman/listinfo/python-list

[toc] | [prev] | [next] | [standalone]

#107813

Steven D'Aprano writes:

> 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), which makes it easy to redirect the help to a file,
> pass it to grep, etc. For example:
>
> [steve@ando ~]$ wget --help | wc -l
> 136
>
> Other tools automatically launch a pager, e.g. man. (Admittedly, man
> --help does not use a pager.) The Python help system, pydoc, does the
> same.
>
> I was thinking that my application could use pydoc:
>
> def do_help():
>     import pydoc
>     pydoc.pager(HELPTEXT)
>
> or just print the help text:
>
> def do_help():
>     # Do I really need to show this???
>     print(HELPTEXT)
>
>
> but I was thinking of doing both: give my application a subcommand or
> an option to display help directly in a pager, while -h and --help
> print to stdout as normal.
>
> What do you think? Too clever?

Keep --help, -h reasonably short and print it to stdout. That's what I
expect and then I know what to do with it.

An actual man page is the obvious place for more documentation.

The --help text can tell where more information is available.

[toc] | [prev] | [next] | [standalone]

#107814

On Thu, Apr 28, 2016, at 13:06, Chris Angelico wrote:
> On Fri, Apr 29, 2016 at 2:33 AM, Steven D'Aprano <steve@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.

[toc] | [prev] | [next] | [standalone]

#107817

On 2016-04-28, 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;

Yep: just write it to stdout.

> (2) run the help text through a pager;

If you do (1), and I can do that myself if that's what I want.

> (3) do something else?

Nope (at least not by default).

> Many command line tools simply output help to stdout (or stderr, if
> they're evil),

Yep, writing help output to stderr is annoying.

> which makes it easy to redirect the help to a file, pass it to grep,
> etc.

Exactly.

> but I was thinking of doing both: give my application a subcommand or an
> option to display help directly in a pager, while -h and --help print to
> stdout as normal.
>
> What do you think? Too clever?

As long as -? -h --help just write stuff to stdout you can add
whatever other options you like that run pagers, start up web
browsers, or show mp4 movies on the wall without annoying grouchy old
Unix users like me.  ;)

-- 
Grant Edwards               grant.b.edwards        Yow! FOOLED you!  Absorb
                                  at               EGO SHATTERING impulse
                              gmail.com            rays, polyester poltroon!!

[toc] | [prev] | [next] | [standalone]

#107818

Yup.. another reason to use something like argparse... you define the argument descriptions, help, and when you raise an error, it automatically handles the output, sending it to the right place (stderr/stdout)... as well as allowing you to define different levels of verbosity easily... (or not if you don't want)

Argparse isn't the best tool in the world, and there are some things that annoy me about it sometimes, but it works pretty well within its boundaries.

(and if the code's already written, I'm not suggesting that it be re-written just to move it to a common library.

> -----Original Message-----
> From: Python-list [mailto:python-list-bounces+d.strohl=f5.com@python.org]
> On Behalf Of Random832
> Sent: Thursday, April 28, 2016 10:30 AM
> To: python-list@python.org
> Subject: Re: What should Python apps do when asked to show help?
> 
> On Thu, Apr 28, 2016, at 13:06, Chris Angelico wrote:
> > On Fri, Apr 29, 2016 at 2:33 AM, Steven D'Aprano <steve@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.
> --
> https://mail.python.org/mailman/listinfo/python-list

[toc] | [prev] | [next] | [standalone]

#107819

On Thu, Apr 28, 2016, at 13:33, Grant Edwards wrote:
> As long as -? -h --help just write stuff to stdout you can add
> whatever other options you like that run pagers, start up web
> browsers, or show mp4 movies on the wall without annoying grouchy old
> Unix users like me.  ;)

One disadvantage is that you have to compose two forms of documentation.
I suspect this is why git [command] --help just opens the manpage. (It
helps that man itself just sends output to stdout when not outputting to
a tty... though it's very annoying that on Windows it opens it in a web
browser instead.)

[toc] | [prev] | [next] | [standalone]

#107820

On 2016-04-28, Random832 <random832@fastmail.com> wrote:
>
>
> On Thu, Apr 28, 2016, at 13:33, Grant Edwards wrote:
>> As long as -? -h --help just write stuff to stdout you can add
>> whatever other options you like that run pagers, start up web
>> browsers, or show mp4 movies on the wall without annoying grouchy old
>> Unix users like me.  ;)
>
> One disadvantage is that you have to compose two forms of documentation.

Only if you want two forms of documentation.

If you add an option to run the help info through a pager, I don't see
how that requires you to compose two forms for documentation.  If you
want both plaintext and video help, then yes you'll have to prepare
two forms of documentation.

> I suspect this is why git [command] --help just opens the
> manpage. (It helps that man itself just sends output to stdout when
> not outputting to a tty... though it's very annoying that on Windows
> it opens it in a web browser instead.)

I don't understand.

If you want your comand-line help info to be in manpage format, that
doesn't mean you have to run it through a pager or open a new window
running the man command, just write the formatted text to stdout.

-- 
Grant Edwards               grant.b.edwards        Yow! My mind is making
                                  at               ashtrays in Dayton ...
                              gmail.com            

[toc] | [prev] | [next] | [standalone]

#107821

Grant Edwards <grant.b.edwards@gmail.com>:

> On 2016-04-28, Random832 <random832@fastmail.com> wrote:
>> One disadvantage is that you have to compose two forms of
>> documentation.
>
> Only if you want two forms of documentation.
>
> If you add an option to run the help info through a pager, I don't see
> how that requires you to compose two forms for documentation. If you
> want both plaintext and video help, then yes you'll have to prepare
> two forms of documentation.

I wouldn't want --help to output a reference manual.

Consider GNU tar:

  tar --help   ==>   a list of options
  man tar      ==>   a description of the command and the options
  info tar     ==>   a user manual


Marko

[toc] | [prev] | [next] | [standalone]

#107826

On 2016-04-28, Marko Rauhamaa <marko@pacujo.net> wrote:
> Grant Edwards <grant.b.edwards@gmail.com>:
>
>> On 2016-04-28, Random832 <random832@fastmail.com> wrote:
>>> One disadvantage is that you have to compose two forms of
>>> documentation.
>>
>> Only if you want two forms of documentation.
>>
>> If you add an option to run the help info through a pager, I don't see
>> how that requires you to compose two forms for documentation. If you
>> want both plaintext and video help, then yes you'll have to prepare
>> two forms of documentation.
>
> I wouldn't want --help to output a reference manual.
>
> Consider GNU tar:
>
>   tar --help   ==>   a list of options
>   man tar      ==>   a description of the command and the options
>   info tar     ==>   a user manual

That's fine.  If you want two or three forms of documentation then you
prepare two or three forms of documentation.

Adding an option to run the default 'help' output through a pager or
display it in a web browser doesn't somehow force you "to compose two
forms of documentation" unless you want two forms of documentation.

-- 
Grant Edwards               grant.b.edwards        Yow! A dwarf is passing out
                                  at               somewhere in Detroit!
                              gmail.com            

[toc] | [prev] | [next] | [standalone]

Page 1 of 3  [1] 2 3  Next page →

Back to top | Article view | comp.lang.python

csiph-web