What should Python apps do when asked to show help?

Thu Apr 28 13:30:04 EDT 2016

Steven D'Aprano writes:
> I have an application written in Python which accepts -h or --help to
> show help. I can:
>> (1) print the help text to stdout;
>> (2) run the help text through a pager;
>> (3) do something else?
>>> Many command line tools simply output help to stdout (or stderr, if
> they're evil), which makes it easy to redirect the help to a file,
> pass it to grep, etc. For example:
>> [steve at ando ~]$ wget --help | wc -l
> 136
>> Other tools automatically launch a pager, e.g. man. (Admittedly, man
> --help does not use a pager.) The Python help system, pydoc, does the
> same.
>> I was thinking that my application could use pydoc:
>> def do_help():
> import pydoc
> pydoc.pager(HELPTEXT)
>> or just print the help text:
>> def do_help():
> # Do I really need to show this???
> print(HELPTEXT)
>>> but I was thinking of doing both: give my application a subcommand or
> an option to display help directly in a pager, while -h and --help
> print to stdout as normal.
>> What do you think? Too clever?

Keep --help, -h reasonably short and print it to stdout. That's what I
expect and then I know what to do with it.
An actual man page is the obvious place for more documentation.
The --help text can tell where more information is available.