What should Python apps do when asked to show help?

[cs at zip.com.au]

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

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