Feature #16754: Pager for `--help`

• Status: Closed
• Assignee: -
• Target version: -

[nobu (Nobuyoshi Nakada)]

The help message by --help is getting longer and longer, and it often exceeds usual terminal windows.
How about to show the message via pager when running on a tty?

And although the message is sectioned, they are less remarkable in the long text, and should be highlighted more, like as the attached screenshot for example.

https://github.com/ruby/ruby/pull/3000

[nobu (Nobuyoshi Nakada)]

• File deleted (screenshot-help.gif)

[nobu (Nobuyoshi Nakada)]

• File screenshot-help.gif added

[nobu (Nobuyoshi Nakada)]

• File deleted (screenshot-help.gif)

[nobu (Nobuyoshi Nakada)]

• File screenshot-help.gif screenshot-help.gif added

[shevegen (Robert A. Heiler)]

I think the basic idea for the suggestion is fine.

There may be cases where the ruby user may prefer to not use (or depend) on a page
and may be fine with a long message output from --help. This may also depend on
the terminal and shell in use.

For example, I typically use bash + KDE konsole, and I rarely use any pagers at
all (very rarely I pipe towards "more" but I actually try to work in a way so
that I don't need any pager; I am more inclined to write some ruby script that
does re-format any output I may see).

On the other hand, when I use e. g. xterm, and say, perhaps the fish shell,
I may need to use a pager more often, simply because configuring (and using)
xterm is ... not so convenient.

So I think the gist of what I am trying to say is that it may be best to allow
the user to toggle the behaviour, possibly simplest just via a configure
option, and if anyone else needs more then a separate issue could be created.
So perhaps a --no-pager option, if the pager display becomes the default; or
vice versa if it is not the default. (Or perhaps an ENV variable, but this
is probably not really needed; just giving a few suggestions for that
possible case.)

[shevegen (Robert A. Heiler)]

Oh... I just noticed in the code, I think that is the environment variable?

My C knowledge is so bad, but I guess getenv() indicates that. :D

    const char *pager_env = getenv("RUBY_PAGER");

[nobu (Nobuyoshi Nakada)]

Yes, this uses RUBY_PAGER if it is defined, or PAGER if defined.
The pager is used if stdin and stdout are tty both, redirecting stdin stops it.

ruby --help <&-

ruby --help </dev/null

And now empty PAGER value is ignored.

RUBY_PAGER= ruby --help

[matz (Yukihiro Matsumoto)]

I have no objection to the feature. Go ahead.

Matz.

[nobu (Nobuyoshi Nakada)]

• Status changed from Open to Closed

Applied in changeset git|f22c4ff359498ab342e4b6d6feb21af6004ee270.

---

View the help message with PAGER [Feature #16754]

View the help message wth pager designed by RUBY_PAGER or PAGER
environment variable, unless that value is empty.