Re: Readline Documentation

[John Devin]

Hey Chet,

Thanks for getting back so fast. Just a couple points to make.

On Thu, Sep 12, 2024 at 4:38 PM Chet Ramey <chet.ramey@case.edu> wrote:
>
> On 9/11/24 3:19 PM, John Devin wrote:
> > While hunting down some problems on a terminal, I ran across the
> > option 'prefer-visible-bell'. It took me some time looking into this
> > before finding out it was deprecated in favor of 'bell-style' about 20
> > years ago, per:
> > https://lists.gnu.org/archive/html/bug-bash/2016-02/msg00186.html.
>
> As the last line in that message says, it was never documented. Readline
> didn't really even have documentation until version 2.1 in 1997, well
> after bell-style.
>
> >
> > Despite that, it still shows up in stackoverflow answers and reddit
> > threads even from as recently as six months ago:
> > https://www.reddit.com/r/bashonubuntuonwindows/comments/1b55k9f/that_stupid_bell/kt3l0hm/.
> >
> > Could this option be documented in the man page?
>
> As you said, it's been deprecated -- and undocumented -- for over 30 years
> (and remains only for backwards compatibility). There's no reason to
> document it.
>

I understand it's been superseded, but I do want to point this out:
running `bind -v` in bash 5.2.21 right now still lists 'set
prefer-visible-bell on' in its output. I considered that maybe it
would only do this in response to being set directly, but neither
~/.bashrc nor /etc/bash.bashrc on my system include it, nor any other
file I can find. Unless this has been changed between that version and
now, it means bash is currently reporting a variable with no way to
discover what it means or what its effects are without changing it and
testing.

> > It would have saved
> > me a bit of wasted time, and it would give me a resource to point to
> > (other than an old mailing list thread) to authoritatively state it's
> > been superseded.
>
> It's been superseded. It's not just undocumented; it's not supposed to be
> used. But there was no reason to break users' startup files, and that is
> still true.
>
> (Yes, I would have hoped usage would have dried up, but change is hard.)
>

The fact that its usage continues suggests documenting it as
deprecated would be beneficial. Many of the stackoverflow/reddit/etc
discussions I found while looking into this included people using both
'bell-style' and 'prefer-visual-bell' simply because they didn't know
what one meant, and then keeping both in their config once they found
the combination that did what they wanted. Essentially, I think it's
being cargo-culted. The fact that `bind -v` still reports it certainly
doesn't help.

As a comparison, I would like to point out that 'meta-flag' (which
`bind -v` also reports) is still documented as a synonym for
'input-meta' even though it appears that replacement also happened
around the same time as 'bell-style', ie pre-bash 2.0.

> > Additionally, as discussed in the mail link above, I think the
> > 'convert-meta' and 'input-meta' need slightly more description. For
> > example, is this statement accurate: "The convert-meta variable has no
> > effect if input-meta is off." From the manpage I would think so, but
> > I'm just not confident. I also can't tell conclusively whether the
> > output-meta variable is affected by convert-meta, or vice-versa.
>
> Those descriptions have undergone fairly significant changes, the result
> of this thread:
>
> https://lists.gnu.org/archive/html/bug-readline/2024-08/msg00003.html
>

Aw, I see. Thanks for the link.

- John