What should Python apps do when asked to show help?

[Jussi Piitulainen]

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.