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

[João Távora]

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.

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

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

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.

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.

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

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.

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

João

[1]:
https://www.masteringemacs.org/article/seamlessly-merge-multiple-documentation-sources-eldoc

[2]: Yes, I know the default is 'truncate-sym-name-if-fit', but that's
the same as the potentially infinite 't' in 99% of the cases.  And we
set it another value like 'truncate-sym-name-but-keep-it-to-one-line' if
that 1% is indeed relevant.