bug#62029: 29.0.60; Allow users to customize eldoc buffer separator

["João Távora" <joaotavora@gmail.com>]

Dmitry Gutov <dmitry@gutov.dev> writes:

>>> What is the reason to have a special value for Elisp again?
>> Try to take it out and see for yourself.  It'd be a good test.
>
> That's what I did, hence the report.

You lost me.  What did you do exactly?  I'm assuming you:

1. Applied the patch I gave to Yuan Fu
2. Set only eldoc-documentation-strategy to eldoc-documentation-compose

And you liked the result with no problems?  If so, that's a good
datapoint.  You will have seen "bouncing" of the echo area, I presume.

> Anyway, from what I remember, Elisp and "we've always done it this
> way" has been used as an argument for not changing the default. But
> nobody stated that Elisp is different from most other modes, and thus
> should have forced settings different from the default.

There could be a misunderstanding here.  Note that the default for
eldoc-echo-area-use-multiline-p _is_ practically "show a lot of lines if
need be".  Whoever added it added it like so.  But it just so happens
that Elisp has "forever" only ever produced a single line of doc to the
echo area.  And that remains today, _unless_ e-d-strategy is set to
e-d-compose.

So there are and have been conflicting settings for a long time.  Elisp
in de facto an exception.  OT1H e-e-a-use-multiline-p says "show a lot
of lines, no problem" by default, OTOH if you show more than one line in
Elisp mode _only_, Elisp modes will think you're making a breaking
change and disrespecting their ElDoc echo area expectations, when in
fact you're not.

So a decision has to be made on what we really want for Elisp's echo
area.  If that decision is "yes, we Elisp users, override the default
e-e-a-use-multiline-p", then it must somehow be recorded in code (hook
or not, I don't care).  If the decision is "OK, we accept a little
bouncing to 2-3 lines as per the e-e-a-u-multiline-p we have" then
nothing needs to change.

Of course, in this argument I'm assuming that changing
eldoc-documentation-strategy to eldoc-documentation-compose is a good
thing, even a very good thing.  But even if it is just an "average"
thing for a couple of fanboys it shouldn't be blocked by the Elisp
exception.

>> Now, Elisp has three different ElDoc backends, two of them added to
>> eldoc-documentation-functions by default, which already contains one for
>> flymake-mode (if that is enabled).
>
> Doesn't sound too different from the situation with Eglot.

It doesn't, sure.  But in when you turn on Eglot mode you don't have
this expectation of single-lineness, and in Elisp mode you do (or at
some old-timers do, I assume).

>> So the patch I've given you is the only way that I know that:
>>    (setq-default eldoc-documentation-strategy
>> 'eldoc-documentation-compose)
>> can coexist with what I understand to be a 1-line-echo-in-elisp
>> requirement.  This is the main point: that value is a vastly better
>> default for the e-d-strategy variable, and not just in my opinion [1].
>> I was under the impression the 1-line-echo-in-elisp is a hard
>> requirement, especially to the old-timers.  I'd love to be mistaken.
>
> I can't answer this one way or the other myself. There are some
> backward compatibility expectations, probably, and some expectations
> of stability. But these probably extend to all modes (which have also
> lived with the given defaults until now), not just Elisp.

I see the change of e-d-strategy's default to e-d-compose has having 0
impact on the "expectations" of any other major-mode _other_ than Elisp.
If you know some other mode, please tell me.

>> But let's say I'm not.  Then there's no actual "obvious downside" as you
>> state.  Let's say the user does customize
>> 'eldoc-echo-area-use-multiline-p' away from its default infinite [2]
>> value to '42'.  It shouldn't have any effect in elisp-mode because of
>> the hard requirement.  It won't have today and won't have after my
>> proposed change.  And if the user does want to override that requirement
>> and see lots of echo lines in Elisp, there are hooks for that.  And if
>> the user doesn't like hooks (but why is she doing Elisp then?) then
>> there could be an extra customization variable (not my cup of tea, but I
>> won't mind).
>> But this is all possibly too complicated.  I do think that just
>> setting
>>     (setq-local eldoc-echo-area-use-multiline-p 1)
>> In Elisp-mode's major-mode function would have absolutely minimal
>> impact.  It's a great time to experiment in master.
>
> At the moment people who don't like the default can easily change it
> across modes. Setting the var in elisp-mode would change that.

What person with exactly what wishes are you describing.  Can you give
an example?  What does that user want to do that he does today, but
won't be able tomorrow if we install this change.

>>> And the thing with window jumping/blinking seems common enough across
>>> the modes.
>> We have to define the concepts.  I thought what was hitherto called
>> "bouncing" merely referred to the fact that sometimes ElDoc displays 1
>> line, and sometimes more.  And that causes the echo are to be resized.
>
> Let's call "bouncing" the occurrence when the windows resize,
> frequently enough. In this case, due to the echo area resizing.

OK.  Though "frequently enough" is very subjective.  I'd prefer to call
"bouncing" to _any_ ElDoc-motivated resizing.

> And "flickering" is when the echo area contents change, sometimes
> twice per user command (first to blank, and then either to new
> message, or even to the previous one).

OK.  I follow.  This has, AFAICT, been completely erradicated.  If you
still see it, please describe a reproducer.

>> Is this concept of "bouncing" acceptable to you in elisp-mode?  Do you
>> think it will ever be accepted by other Emacs lisp developers that
>> sometimes, when standing over a symbol with both a function and variable
>> definition the two things will be documented in two separate lines?  I
>> assume it won't, thus the Elisp setting of
>> eldoc-echo-area-use-multiline-p to 1.
> I suggest you put it up for the discussion on emacs-devel

I'll only bring it up if I when I gather 2 or 3 devs with a good
perspective of what ElDoc is today for Elisp and also modes other than
Elisp.  There have to be alternatives on offer, so the effort doesn't
fizzle when someone obstinately (and predictably) refuses even the
smallest echo-area resizing.  If anyone have better ideas leading to a
eldoc-documentation-strategy being e-d-compose everywhere, I'm all ears.
That's ultimately what I'm interested in, because it enables a rich
*eldoc* buffer experience by default.  Mickey's article helps explain
this.

> after we ensure that the flickering and bouncing situation has
> improved.

You mean only "flickering" here, right?  "Bouncing" is by design if
e-e-a-use-multiline-p is t and e-d-strategy is e-d-compose.

> In particular, bouncing shouldn't happen on every user input. 

I don't follow.  If it did, it'd be "flickering", according to your
definition.

> Echo area resizing is probably unavoidable when moving point between
> totally different contexts 

Exactly.  That's "bouncing", to me.  Is there a third concept to you?  I
hope not.

> (e.g. one without a flymake error and one
> with it), but at least the display should be stable while the same
> things are displayed.

Of course.  Agreed.  And as far as I understand, that has always
happened (modulo flickering, which is imperceptible in TTY Emacs).

> And regarding flickering, we can try to ensure that the change in the
> echo are happens just once per user command, at most. No flickering to
> blank, if we can help it.

That's taken care of, at least AFAICT.  

> It seems you've reproduced it already and even pushed out a fix to master.
>
> I believe I've mentioned these things a few times when the change in
> eldoc-documentation-strategy. They seemed obvious enough not to
> warrant an extra detailed explanation, so I guess that's on me.

A little Emacs -Q goes a long way, at least for me.  I'm vaguely recall
reading these complaints, but they never rang a bell and i couldn't see
them, so I just assumed they were misunderstandings and forgot.

> E.g. personally, I would perhaps prefer it there was a failover from
> elisp-eldoc-funcall to elisp-eldoc-var-docstring, but that was
> composed in parallel with flymake-eldoc-function, to also show the
> compilation error when available. But that doesn't seem like it is
> provided by any of the existing options.

Intersting.  It's trivial to do that failover function.

  (defun elisp-eldoc-failover-function-to-var (callback &rest _ignored)
    (or (elisp-eldoc-funcall callback)
        (elisp-eldoc-var-docstring callback)))

It could be the start of an idea that doesn't require changing
e-e-a-use-multiline-p, because if you use it and don't turn on Flymake
mode (which I suspect the older crowd doesn't), then it's like nothing
ever changed: no bouncing whatsoever.  Starting from there, we could
modify it so that this e-d-function only echoes and doesn't send
anything to the *eldoc* buffer, while elisp-eldoc-fucall and
elisp-eldoc-var-docstring to the inverse.

João