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

[Dmitry Gutov <dmitry@gutov.dev>]

On 13/04/2023 12:50, João Távora wrote:
> Dmitry Gutov <dmitry@gutov.dev> writes:
> 
>>>> I have applied it. What should I be looking at?
>>> Right. That's a good sign it itself.  Here, have some more patch:
>>>     (setq-default eldoc-documentation-strategy
>>> 'eldoc-documentation-compose)
>>>     (add-hook 'emacs-lisp-mode-hook
>>>       (lambda () (setq-local eldoc-echo-area-use-multiline-p 1)))
>>> Then go on with elisp your life and maybe peek into M-x
>>> eldoc-doc-buffer
>>> once in a while.
>>
>> 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.

>> One obvious downside is that if the user customizes it to some
>> different value (e.g. 2, limiting the height of the window below), it
>> won't be honored by Elisp without some extra work on the part of the
>> user. So if we want to do that, we'd need some strong argument for why
>> Elisp is different from everyone else.
> 
> Apparently it is.  The working assumption here is that Elisp users never
> ever want to see more than one line of ElDoc documentation in the mode
> line, even though the default value of eldoc-echo-area-use-multiline-p
> is t [2] .  These users, presumably, won't mind and could even
> appreciate larger snippets of documentation in the *eldoc* buffer and in
> Yuan's eldoc-box popup, though.  We're currently working on the pretty
> formatting of this buffer, and this bug you're reading is primarily
> about that.

We might discuss and re-consider that.

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.

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

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

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

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

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

> 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 after we 
ensure that the flickering and bouncing situation has improved.

In particular, bouncing shouldn't happen on every user input. Echo area 
resizing is probably unavoidable when moving point between totally 
different contexts (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.

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.

>> But in Elisp -- even if I just move the cursor with arrows or C-f/C-b,
>> 1 times out of 2 the echo are window will blink.
>>
>> It's trivially reproduced even with 'emacs -Q': just add somewhere
>> inside an Elisp buffer:
>>
>>    (remove-hook asd)
>>
>> when flymake-mode is enabled and eldoc-documentation-strategy is
>> 'eldoc-documentation-compose, and eldoc-echo-area-use-multiline-p is
>> not 1, and move around 'asd' with C-f and C-b.
>>
>> Is that bug Elisp-specific? That would seem odd.
> 
> You seem to be describing a separate problem that I never noticed or was
> bothered with (and I do use company and multi-line echo areas
> liberally).  I'll try your recipe but would you describe exactly what to
> look for?

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.