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

Groups > comp.lang.python > #107928

Re: What should Python apps do when asked to show help?

Show key headers only | View raw

On 29Apr2016 11:40, Steven D'Aprano <steve@pearwood.info> wrote:
>On Fri, 29 Apr 2016 07:08 am, Grant Edwards wrote:
>> On 2016-04-28, Random832 <random832@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@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@zip.com.au>

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

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

csiph-web