What should Python apps do when asked to show help?

Sat Apr 30 20:06:28 EDT 2016

On 29Apr2016 11:40, Steven D'Aprano <steve at pearwood.info> wrote:
>On 2016年4月29日 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?

"man 5 man"? Describes the internal format of man pages (the [ntg]roff -man 
macro set). Many people use an intermediate more human friendly format and use 
a tool to transcribe -man format text. For standalone things I find Perl's 
"POD" format fairly easy to use (the pod2man tool itself does have shortcomings 
though).
>> 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.

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

Yes, it is nonportable. Presumes groff possibly, and GNU "man".
>However, this almost works:
>>man -Pcat rm
>>appears to output unformatted, plain text to stdout.

As should:
 man rm | cat
without obscure options.
>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...

Yes.
>instead of
>>NAME
> rm - remove files or directories
[...]
>>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?

That is what Grant Edwards' "col -bx" does. (Actually, col can do more, because 
tables also do funky things; let us not go there.)
But removing the overstriking is pretty easy even without col. My "unbs" script 
does it, and its core operation is this:
 s/[^^H]^H//g
Those ^Hs are literal backspace characters: remove any non-backspace followed 
by a backspace. Full script here:
 https://bitbucket.org/cameron_simpson/css/src/tip/bin/unbs
>> 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)

Aye, but what is wanted by some of us is an easy incantation to tune that to 
plain old sys.stdout.write in some flavour.
Cheers,
Cameron Simpson <cs at zip.com.au>