What should Python apps do when asked to show help?

[Grant Edwards]

On 2016-04-28, Random832 <random832 at fastmail.com> wrote:
> On Thu, Apr 28, 2016, at 15:39, Grant Edwards wrote:
>> 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.
>
> The point is that having "help" output at all (beyond either a cursory
> "see the manpage") implies two forms of documentation (given you already
> have a manpage), and some people choose not to do that, instead
> launching directly into the manpage (which implies using a pager)

But I'm saying that having --help output the manpage should not imply
using a pager.

If --help is going to output the manpage, then I'm saying it can (and
should) be written to stdout without use of pager (and it shouldn't
have escape sequences or backspaces in it either).  The Unix way is
that the output from whatever --help should be plain text written to
stdout (regardless of length).

If you want to output the man page, this can be accomplished simply by
doing someting like:

  os.environ["GROFF_NO_SGR"] = "1";
  os.system("man -Tascii mycmd | col -bx");

If I want the --help output run through a pager, I'll do it myself.

I agree that a good argument can be made that the --help output should
be a concise summary, and that a separate longer man page might be a
good idea.  But whatever you decide to provide when invoked with
--help it should be plaintext written to stdout.  No pagers, no
colors, no HTML.

[if you're really going to invoke the 'man' command, you should do it
with the subprocess module with shell=False -- but examples with
os.system() are easier to grok]

-- 
Grant Edwards               grant.b.edwards        Yow! Sometime in 1993
                                  at               NANCY SINATRA will lead a
                              gmail.com            BLOODLESS COUP on GUAM!!