On 29Apr2016 11:40, Steven D'Aprano <st...@pearwood.info> wrote:
On Fri, 29 Apr 2016 07:08 am, Grant Edwards wrote:
On 2016-04-28, Random832 <random...@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 <c...@zip.com.au>
--
https://mail.python.org/mailman/listinfo/python-list
