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

Groups > comp.lang.python > #107801 > unrolled thread

What should Python apps do when asked to show help?

Back to article view | Back to comp.lang.python

Contents

  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

Page 2 of 3 — ← Prev page 1 [2] 3  Next page →

#107827

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)

[toc] | [prev] | [next] | [standalone]

#107832

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.

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

[toc] | [prev] | [next] | [standalone]

#107836

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?


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

[toc] | [prev] | [next] | [standalone]

#107856 — manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?]

Hello,

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

I don't know of a single place where manpage authorship is 
particularly documented.  This seems to be one of the common target 
links.  In addition to introducing the breakdown of manpages by 
type (section) and providing some suggestions for content, it 
introduces the *roff markup:

  http://www.schweikhardt.net/man_page_howto.html

It's been many years since I have written that stuff directly.  I 
prefer one of the lightweight, general documentation or markup 
languages.  So, below, I'll mention and give examples for creating 
manpages from reStructuredtext, AsciiDoc and Plain Old 
Documentation.

With the reStructuredText format [0] [1], you can convert an .rst 
file to a manpage using two different document processors; you can 
use sphinx-build from the sphinx-project [2] or rst2man from the 
docutils project.  The outputs are largely the same (as far as I 
can tell).

There's also the AsciiDoc [3] format, which is a near to text and 
reads like text, but has a clear structure.  With the tooling 
(written in Python), you can produce docbook, latex, html and a 
bunch of other output formats.  Oh, and manpages [4], too.  There is 
a tool called 'asciidoc' which processes AsciiDoc formats into a 
variety of backend formats.  The 'a2x' tool converts AsciiDoc 
sources into some other (x) desired output.

If you don't like .rst or AsciiDoc, there's also the Plain Old 
Documentation (POD) format.  This is the oldest tool (of which I'm 
aware) which other than the direct *roff processing tools.  You run 
'pod2man' (written in Perl) on your .pod file.  POD is another dead 
simple documentation language, supported by the pod2man [5] tool.  
For more on the format, read also 'man 1 perlpod'.

sphinx-build: the sphinx documentation system is geared for 
handling project-scoped documentation and provides many additional 
features to reStructuredText.  It can produce all kinds of output 
formats, HTML single-page, help, multipage, texinfo, latex, text, 
epub and ....oh, yeah, manpages.  It's a rich set of tools.

If you wish to use sphinx, I can give you an example .rst file [6] 
which I recently wrote and the following instructions for how to 
process this with sphinx.  When processing docs with sphinx, a 
'conf.py' file is required.  It can be generated with an ancillary 
tool from the sphinx suite:

I know that I always find an example helpful.  So, here are some 
examples to help you launch.

  mkdir sampledir && cd sampledir
  sphinx-quickstart   # -- and answer a bunch of questions
  # -- examine conf.py and adjust to your heart's content
  #    confirm that master_doc is your single document for a manpage
  #    confirm that there's an entry for your document in man_pages
  sphinx-build -b man -d _build/doctrees . _build/man

  # -- or grab the files from my recent project [6] and try yourself

rst2man: even more simply, if you don't need the kitchen sink...

  wget https://gitlab.com/pdftools/pdfposter/raw/develop/pdfposter.rst
  rst2man < pdfposter.rst  > pdfposter.1
  # -- will complain about this, but still produces a manpage
  # <stdin>:10: (ERROR/3) Undefined substitution referenced: "VERSION".
  man ./pdfposter.1

asciidoc (a randomly selected example asciidoc file [7]):

  wget https://raw.githubusercontent.com/DavidGamba/grepp/master/grepp.adoc
  a2x -f manpage grepp.adoc  
  man ./grepp.1

perlpod:

  wget https://api.metacpan.org/source/RJBS/perl-5.18.1/pod/perlrun.pod
  pod2man --section 1 < perlrun.pod > perlrun.1
  man ./perlrun.1

I know there are other tools for generating manpages; the 
original *roff tools, visual manpage editors, DocBook, 
help2man, manpage generators from argparse.ArgumentParser 
instances, 

And, of course, make sure to use version control for your 
documentation.  These git manpages may be helpful for the 
uninitiated (joke, joke):

  https://git-man-page-generator.lokaltog.net/  # -- humour!

Good luck,

-Martin

 [0] http://docutils.sourceforge.net/docs/user/rst/quickref.html
 [1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
 [2] http://www.sphinx-doc.org/en/stable/rest.html
 [3] http://www.methods.co.nz/asciidoc/
 [4] http://www.methods.co.nz/asciidoc/chunked/ch24.html
 [5] http://perldoc.perl.org/pod2man.html
 [6] https://raw.githubusercontent.com/tLDP/python-tldp/master/docs/ldptool-man.rst
 [7] https://raw.githubusercontent.com/DavidGamba/grepp/master/grepp.adoc

-- 
Martin A. Brown
http://linux-ip.net/

[toc] | [prev] | [next] | [standalone]

#107857 — Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?]

Wow.  Thank you for that very informative post!

--
~Ethan~

[toc] | [prev] | [next] | [standalone]

#107859 — Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?]

On Friday, April 29, 2016 at 7:35:55 PM UTC+5:30, Ethan Furman wrote:
> Wow.  Thank you for that very informative post!
> 
> --
> ~Ethan~

For emacs junkies there is also org-e-man


[1] http://orgmode.org/worg/org-tutorials/org-e-man-documentation.html
[2] https://github.com/tkf/org-mode/blob/master/contrib/lisp/org-e-man.el

[No I havent used this but I use org mode heavily]

[toc] | [prev] | [next] | [standalone]

#107889 — Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?]

"Martin A. Brown" <martin@linux-ip.net> writes:

> Hello [Steven D'Aprano],
>
> >What is a good place where I can find out more about writing manpage?

Writing them directly in GNU troff markup is easy enough
<URL:http://liw.fi/manpages/>.

For writing manual pages programmatically via Python code, I am working
on a ‘manpage’ library. It is not yet at PyPI, but Steven may find
the existing library <URL:https://notabug.org/bignose/python-manpage>
useful. It's free software under the GNU GPL v3 or later.

Steven, if you want to use that library for making manual pages, I'd
love to get feedback. Currently it works on an ArgumentParser instance
(to get the program's name and option help), and a Distutils
distribution (to get the boader metadata about the package).

What ‘manpage’ doesn't yet have is a more generic way to specify the
metadata of a manual page. Everything is done by directly modifying a
Document instance. I have yet to decide a data format for the data which
specifies a manual page.

Getting several more code bases using this library would make it clearer
what use cases are important, and thereby inform a data format for the
specification. Please experiment!

-- 
 \      “The process by which banks create money is so simple that the |
  `\     mind is repelled.” —John Kenneth Galbraith, _Money: Whence It |
_o__)                                       Came, Where It Went_, 1975 |
Ben Finney

[toc] | [prev] | [next] | [standalone]

#107900 — Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?]

On Saturday, April 30, 2016 at 7:55:47 AM UTC+5:30, Ben Finney wrote:
> "Martin A. Brown"  writes:
> 
> > Hello [Steven D'Aprano],
> >
> > >What is a good place where I can find out more about writing manpage?
> 
> Writing them directly in GNU troff markup is easy enough
> <URL:http://liw.fi/manpages/>.
> 
> For writing manual pages programmatically via Python code, I am working
> on a 'manpage' library. It is not yet at PyPI, but Steven may find
> the existing library <URL:https://notabug.org/bignose/python-manpage>
> useful. It's free software under the GNU GPL v3 or later.
> 
> Steven, if you want to use that library for making manual pages, I'd
> love to get feedback. Currently it works on an ArgumentParser instance
> (to get the program's name and option help), and a Distutils
> distribution (to get the boader metadata about the package).
> 
> What 'manpage' doesn't yet have is a more generic way to specify the
> metadata of a manual page. Everything is done by directly modifying a
> Document instance. I have yet to decide a data format for the data which
> specifies a manual page.
> 
> Getting several more code bases using this library would make it clearer
> what use cases are important, and thereby inform a data format for the
> specification. Please experiment!

Some general thoughts and comments:
Documentation in linux is a train-wreck in slow motion -- 30 years of slow motion!!

tl;dr
If you want to be helpful to the community please dont create a new format
Instead try to make existing formats interoperate/work better with each other

In more detail:
First there was man
Then gnu/rms created info to better man with hypertext capabilities
However another hypertext standard beat the gnu standard -- html
[No I am not talking of quality just general acceptance]
As with all things rms, its taking him decades to realize this defeat
[Latest makeinfo is 18 times slower than previous version!!
https://lists.gnu.org/archive/html/bug-texinfo/2013-01/msg00012.html
]

In the meantime the so called lightweight formats have multiplied:
rst, textile, markdown, asciidoc etc
with their own 'stacks'
Alongside siloed, incompatible help systems:
manpages, infodocs, yelp...

[toc] | [prev] | [next] | [standalone]

#107903 — Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?]

Rustom Mody <rustompmody@gmail.com> writes:
> As with all things rms, its taking him decades to realize this defeat
> [Latest makeinfo is 18 times slower than previous version!!
> https://lists.gnu.org/archive/html/bug-texinfo/2013-01/msg00012.html

Wait, what's it written in now?

> In the meantime the so called lightweight formats have multiplied:
> rst, textile, markdown, asciidoc etc

Pandoc can interconvert between most of those... maybe texinfo should
be folded into it if it's not already.

[toc] | [prev] | [next] | [standalone]

#107908 — Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?]

On Saturday, April 30, 2016 at 9:36:42 AM UTC+5:30, Paul Rubin wrote:
> Rustom Mody  writes:
> > As with all things rms, its taking him decades to realize this defeat
> > [Latest makeinfo is 18 times slower than previous version!!
> > https://lists.gnu.org/archive/html/bug-texinfo/2013-01/msg00012.html
> 
> Wait, what's it written in now?

Have you any data that its moved on?

At that point what I gleaned was that original makeinfo was in C
New one was rewritten in perl.
[Yeah they could have taken a leaf out of pandoc -- written in haskell]

[toc] | [prev] | [next] | [standalone]

#107911 — Re: manpage writing [rst, asciidoc, pod] was [Re: What should Python apps do when asked to show help?]

Rustom Mody <rustompmody@gmail.com> writes:
> At that point what I gleaned was that original makeinfo was in C
> New one was rewritten in perl.

The previous one was definitely written in C and I've looked at the code
some.  I hadn't known there was a new one.  The C one was actually the
second one.  The first one was written in Emacs Lisp but it was
painfully slow on the hardware of that era.  The C version was
cumbersome by comparison.  If they wanted to get rid of the C version
now that the hardware is 100x faster or more, it's amusing that they did
a Perl rewrite instead of reviving the Lisp version.  Pandoc has a
significant user base now though, and it looks like it also supports
texinfo.  So I wonder what the new Makeinfo does that pandoc doesn't.
Maybe pandoc doesn't support Info?  That could be added, I'm sure.

[toc] | [prev] | [next] | [standalone]

#107891 — Writing manual pages using Python code (was: manpage writing)

"Martin A. Brown" <martin@linux-ip.net> writes:

> Hello [Steven D'Aprano],
>
> >What is a good place where I can find out more about writing manpage?

Writing manual pages directly in standard GNU troff markup is simple
enough <URL:http://liw.fi/manpages/>. It's not a pretty markup language,
but it's workable.

For writing manual page documents programmatically via Python code, I am
working on a ‘manpage’ library.

It is not yet at PyPI, but Steven may find the existing library
<URL:https://notabug.org/bignose/python-manpage> useful. It's free
software under the GNU GPL v3 or later.

Steven, if you want to use that library for making manual pages, I'd
love to get feedback.

Currently it works on an ArgumentParser instance (to get the program's
name and option help), and a Distutils distribution (to get the boader
metadata about the package).

What ‘manpage’ doesn't yet have is a more generic way to specify the
metadata of a manual page; the above inputs are the only ones that I've
tested. Everything is done by directly modifying a Document instance. I
have yet to decide a data format for the data which specifies a manual
page.

If several more code bases could use this library to generate manual
pages, that would make it clearer what use cases are important, and
thereby inform a data format for the specification. Please experiment!

-- 
 \      “The process by which banks create money is so simple that the |
  `\     mind is repelled.” —John Kenneth Galbraith, _Money: Whence It |
_o__)                                       Came, Where It Went_, 1975 |
Ben Finney

[toc] | [prev] | [next] | [standalone]

#107928

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>

[toc] | [prev] | [next] | [standalone]

#107839

Steven D'Aprano <steve@pearwood.info> writes:
> (1) print the help text to stdout;
> (2) run the help text through a pager;

Stdout unless the PAGER env var is set.  Otherwise, I'd say still stdout
since the person can pipe it through a pager if they want, but you could
use the pager or be fancy and try to detect if stdout is a pty/tty
before using the pager.  Git pages by default and it bugs me because I
tend to use git commands in emacs shell windows and the pager makes a
mess.

[toc] | [prev] | [next] | [standalone]

#107840

On Friday, April 29, 2016 at 7:45:35 AM UTC+5:30, Paul Rubin wrote:
> Steven D'Aprano  writes:
> > (1) print the help text to stdout;
> > (2) run the help text through a pager;
> 
> Stdout unless the PAGER env var is set.  Otherwise, I'd say still stdout
> since the person can pipe it through a pager if they want, but you could
> use the pager or be fancy and try to detect if stdout is a pty/tty
> before using the pager.  Git pages by default and it bugs me because I
> tend to use git commands in emacs shell windows and the pager makes a
> mess.

Quite bewildered by this thread...
Are we in 2016?
[Reminds me of the bizarre claim that world has not moved on from text]
eg I am on on Ubuntu 16.4 (vanilla) right now.
This means that when I pull up a terminal I get gnome-terminal.
Which means that when the screen fills up I get a scroll bar
Now I can get perverse and use xterm/rxvt.
Or a console outside of X (ctrl-Alt-F[1-6] )
And even there Shift-pgup works

Of course there is the 1 in 100 times this does not hold;
- ssh to a remote machine
- Upgraded ubuntu and broke X 
- etc

[What happens in windows on a cmd-box... not sure]

IOW pager functionality is quite builtin in shells nowadays
Why replicate and cause annoyance?

[toc] | [prev] | [next] | [standalone]

#107841

Rustom Mody writes:

> On Friday, April 29, 2016 at 7:45:35 AM UTC+5:30, Paul Rubin wrote:
>> Steven D'Aprano  writes:
>> > (1) print the help text to stdout;
>> > (2) run the help text through a pager;
>> 
>> Stdout unless the PAGER env var is set.  Otherwise, I'd say still stdout
>> since the person can pipe it through a pager if they want, but you could
>> use the pager or be fancy and try to detect if stdout is a pty/tty
>> before using the pager.  Git pages by default and it bugs me because I
>> tend to use git commands in emacs shell windows and the pager makes a
>> mess.
>
> Quite bewildered by this thread...

Yet you seem to agree with everybody else in this thread? Including the
two persons you quote above, if I read them right :)

> Are we in 2016?

$ date '+Yes: %F %T'
Yes: 2016-04-29 08:11:07

> [Reminds me of the bizarre claim that world has not moved on from text]
> eg I am on on Ubuntu 16.4 (vanilla) right now.
> This means that when I pull up a terminal I get gnome-terminal.
> Which means that when the screen fills up I get a scroll bar
> Now I can get perverse and use xterm/rxvt.
> Or a console outside of X (ctrl-Alt-F[1-6] )
> And even there Shift-pgup works
>
> Of course there is the 1 in 100 times this does not hold;
> - ssh to a remote machine
> - Upgraded ubuntu and broke X 
> - etc

Remote shell works fine.

I spend most of my time in a shell on a remote machine over ssh, without
X forwarding. I have turned scrollbars off.

If I need to scroll back the remote shell session a screen or more, I
just slide my index finger along the touchpad edge, or index and middle
finger over the touchpad on the other laptop.

In Emacs in that remote shell, including a shell session in the Emacs, I
use the normal keys to scroll back and forth. There the touchpad doesn't
scroll at all, and I don't expect it to, either.

> [What happens in windows on a cmd-box... not sure]

If that happens to be crippled, there must be other terminal programs
that work.

> IOW pager functionality is quite builtin in shells nowadays
> Why replicate and cause annoyance?

First, more and less do more than just scroll and they may be nicer even
for just scrolling. Second, if things are set up the way that just about
everybody in this thread has been advocating, you have full control over
your use of a pager. If it hurts, don't do it. Does it annoy you that
somebody else is doing it?

It's the *default* paging that is mildly annoying when it works and a
major pain when it doesn't. (Another major pain is a command-line tool
that tries to open a window and can't because I haven't enabled it.
Please don't make this the default either. :)

[toc] | [prev] | [next] | [standalone]

#107845

On Fri, 29 Apr 2016 03:00 pm, Rustom Mody wafted information-rich pheromones
into the air, where they diffused rapidly:

> Quite bewildered by this thread...
> Are we in 2016?
> [Reminds me of the bizarre claim that world has not moved on from text]

(For the benefit of those of us still stuck in the 2000s, I have transcribed
Rustom's pheromones into the obsolete medium of text.)


> eg I am on on Ubuntu 16.4 (vanilla) right now.
> This means that when I pull up a terminal I get gnome-terminal.
> Which means that when the screen fills up I get a scroll bar

Yes. So do I.

Of course, some applications (like screen) interfere with that, but even
when you have a scroll bar, having to scroll back more than a few pages is
a PITA. If you set the number of scrollback lines too low, you run out and
the things you are interested in disappears past the top... and if you set
it too high, it's too hard to locate the section that you actually want.

The bottom line is, screen real estate is a valuable resource, but even more
valuable is human attention, and pagers are a way of managing attention.
Screen space is not necessary rare, but neither is it something that we can
just consume thoughtlessly. Hence we have a whole range of options
available to us, to make the most of screen space:

- multiple windows;
- multiple tabs within each window;
- scroll bars within each tab;
- and pagers.

Think of a pager as being somewhat like a popup window for text: at the very
low cost of a single line of space in your terminal, you can "pop up" the
text, read it, and dismiss it again without using up any of the screen
space in your scrolling text view. (Apart from that one line.)


> IOW pager functionality is quite builtin in shells nowadays

Apart from those where they're not.


> Why replicate and cause annoyance?

If you don't want to use the functionality, don't.



-- 
Steven

[toc] | [prev] | [next] | [standalone]

#107847

On Friday, April 29, 2016 at 3:07:09 PM UTC+5:30, Steven D'Aprano wrote:
> On Fri, 29 Apr 2016 03:00 pm, Rustom Mody wafted information-rich pheromones
> into the air, where they diffused rapidly:
> > Why replicate and cause annoyance?
> 
> If you don't want to use the functionality, don't.

You asked about calling up pagers!!

JFTR I find git behavior annoying -- as it seems do others -- but Ive figured 
getting round it by calling it with -w (show in web browser) is ok (with me)

With python's help I find it annoying and Ive not figured out how to not get paging

[toc] | [prev] | [next] | [standalone]

#107879

On Fri, 29 Apr 2016 07:53 pm, Rustom Mody wrote:

> On Friday, April 29, 2016 at 3:07:09 PM UTC+5:30, Steven D'Aprano wrote:
>> On Fri, 29 Apr 2016 03:00 pm, Rustom Mody wafted information-rich
>> pheromones into the air, where they diffused rapidly:
>> > Why replicate and cause annoyance?
>> 
>> If you don't want to use the functionality, don't.
> 
> You asked about calling up pagers!!

Right. And options -h/--help will behave exactly as people have requested,
by printing to stdout.


> JFTR I find git behavior annoying -- as it seems do others

`git --help` behaves as the Unix standard: it prints help output to stdout.
Is that the annoying behaviour?

`git help <command>` and `git <command> --help` call `man`. Is that the
annoying behaviour? Then presumably `man` is also annoying, and the advise
I was given to just use man pages is bad advice.


> -- but Ive 
> figured getting round it by calling it with -w (show in web browser) is ok
> (with me)

You would rather output be shown in a web browser than paged in your
terminal? That's weird, but okay, whatever floats your boat.


> With python's help I find it annoying and Ive not figured out how to not
> get paging

o_O

Okay, now I'm feeling as if you had said "I find it annoying to be fit and
healthy, I've not found a way to feel sufficiently sick, tired and
out-of-shape all the time."

But I see your point. The pydoc documentation itself is lacking. But from
reading the source code, I see that if you set the PAGER environment
variable to your preferred pager, it will use that. So setting it to "cat"
should work. I've just tested this under Linux, and it works for me:


[steve@ando ~]$ PAGER=cat python3.3
Python 3.3.0rc3 (default, Sep 27 2012, 18:44:58)
[GCC 4.1.2 20080704 (Red Hat 4.1.2-52)] on linux
Type "help", "copyright", "credits" or "license" for more information.
py> help(len)
Help on built-in function len in module builtins:

len(...)
    len(object) -> integer

    Return the number of items of a sequence or mapping.

py>



-- 
Steven

[toc] | [prev] | [next] | [standalone]

#107886

On 04/29/2016 06:20 PM, Steven D'Aprano wrote:
> On Fri, 29 Apr 2016 07:53 pm, Rustom Mody wrote:


>> JFTR I find git behavior annoying -- as it seems do others
>
> `git --help` behaves as the Unix standard: it prints help output to stdout.
> Is that the annoying behaviour?

No.

> `git help <command>` and `git <command> --help` call `man`. Is that the
> annoying behaviour?

Yes.

> Then presumably `man` is also annoying,

No.

> and the advise I was given to just  use man pages is bad advice.

The advice to call man from --help is bad; the advice to have a man page 
for use with man is not.

>> With python's help I find it annoying and Ive not figured out how to not
>> get paging
>
> o_O
>
> Okay, now I'm feeling as if you had said "I find it annoying to be fit and
> healthy, I've not found a way to feel sufficiently sick, tired and
> out-of-shape all the time."

And exactly what is healthy and fit about calling "help(something)" and 
then having that help disappear?  I find that *extremely* annoying.

> But I see your point. The pydoc documentation itself is lacking. But from
> reading the source code, I see that if you set the PAGER environment
> variable to your preferred pager, it will use that. So setting it to "cat"
> should work. I've just tested this under Linux, and it works for me:

So I have to cripple my shell to get pydoc help to work nicely?  Neat! 
Actually, not so much.  :(

--
~Ethan~

[toc] | [prev] | [next] | [standalone]

Page 2 of 3 — ← Prev page 1 [2] 3  Next page →

Back to top | Article view | comp.lang.python

csiph-web