What should Python apps do when asked to show help?

[Steven D'Aprano]

On Fri, 29 Apr 2016 07:08 am, Grant Edwards wrote:

> 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.


What manpage? I don't have a manpage. The only help my application has is
whatever it outputs (which it gets from its docstring).

What is a good place where I can find out more about writing manpages?


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

Agree. The -h/--help option will output plain text to stdout.


> 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");

That doesn't work for me: 

[steve at ando ~]$ man -Tasciii rm
man: invalid option -- T



However, this almost works:

man -Pcat rm

appears to output unformatted, plain text to stdout. However, if you capture
the output (say, to a file) you'll see it is full of backspaces, e.g.:

N^HNA^HAM^HME^HE
       rm - remove files or directories

S^HSY^HYN^HNO^HOP^HPS^HSI^HIS^HS
       r^Hrm^Hm [_^HO_^HP_^HT_^HI_^HO_^HN]... _^HF_^HI_^HL_^HE...


instead of 

NAME
        rm - remove files or directories

SYNOPSIS
       rm [OPTION]... FILE...


Apparently `less` understands overstriking and displays it as bold (or
underlining in the case of _^H. That's very clever, but how do I get actual
plain text out of `man` without the backspaces?



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

Easy enough to say for Linux/Unix users, but there are those who might not
have a pager that is easy to use, or at all. pydoc goes to considerable
trouble to work out the best pager available for your platform, falling
back to its own if needed. To use that is literally a two liner:

import pydoc
pydoc.pager(HELPTEXT)




-- 
Steven