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

[Dmitry Gutov <dmitry@gutov.dev>]

On 14/04/2023 02:01, João Távora wrote:
> 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

Pretty much. If I also did 3 (change the value of 
eldoc-echo-area-use-multiline-p in emacs-lisp-mode only), I wouldn't be 
able to reproduce most of the problematic behavior described previously.

> 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.

I'm still vague on what your patch to elisp-mode.el does, but at least 
I'm not seeing any particular breakage.

>> 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.

In theory, yes.

> Elisp
> in de facto an exception.

Do we have some sort of statistics or overview on that issue? E.g. if we 
take only eldoc functions that are relatively old-ish (crossing out 
lsp-mode and eglot, I mean).

> 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.

This is something to ask the users, I think. Maybe by trying an 
experiment at some point.

> 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.

In the latter case, I would say that it probably should. But if we can 
streamline things for the enjoyment of everybody, that would be better.

>>> 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.

I imagine you or Yuan, or somebody with similar expectations but not 
either of you exactly would customize eldoc-echo-area-use-multiline-p to 
4, for example. And eldoc-documentation-strategy - to 
eldoc-documentation-compose.

Or, if we change the default value of eldoc-documentation-strategy, 
someone with the diametrically opposite preferences from you would 
customize eldoc-echo-area-use-multiline-p to 1 and have that work in all 
modes. Or set it to 2, to have some middle ground. Etc.

>>>> 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.

I've described a scenario in the bug you filed (bug#62816) which uses 
company-mode. With a screencast. Again, in a basic default configuration 
of everything.

>>> 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.

Personally, I'd rather people also tried to explore ways to show some of 
this info that doesn't put it all in Eldoc. There are a lot of examples 
of signature help interfaces that put it closer to the input.

But for the time being, Eldoc could be an intermediate step.

The "hover info" is fine for Eldoc OTOH, I guess.

>> 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.

I'd say bouncing is about the echo area bounds, and flickering is about 
the contents.

>> 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.

That's also "bouncing", but with a passably low frequency, in my book. 
Bouncing hurts the most when it happens with every button press (or 
close to that).

>> (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).

Why isn't this stuff noticeable on TTY? Lower refresh rate or something?

>> 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)))

Cool. Which of the functions are used, could be decided by a pref in 
elisp-mode.

And for flymake, there could be a preference for how many (maximum) 
lines of errors to show at once.

> 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.

Yep. (As long as that "you" wasn't about myself in particular.)

> 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.

That reminds me of some of my older messages where I insisted the 
eldoc-buffer thingy should have its own separate hook. Oh well.