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

[Yuan Fu <casouri@gmail.com>]

> On Mar 30, 2023, at 1:13 AM, João Távora <joaotavora@gmail.com> wrote:
> 
> Yuan Fu <casouri@gmail.com> writes:
> 
>>>> 
>>>> Looks good to me (except for the “documentatiok” ;-) eldoc-box can
>>>> also benefit from this (right now if you use it in emacs-lisp-mode,
>>>> it just shows a thin strip of text, not very exciting).
>>>> 
>>>> I’ll experiment with the title thing in eldoc-box. Does eglot and
>>>> flymake already pass a :source cookie? Those two displaying stuff
>>>> together is the most possible case I can think of.
>>> 
>>> 
>>>> it just shows a thin strip of text, not very exciting).
>>> 
>>> Indeed.  I'll present my patch soon in emacs-devel.
>>> There's one thing I don't like about it which is that
>>> is re-does a lot of complicated parsing for both *Help*
>>> and *eldoc* forms.  Could be slow, or could be meaningless.
>>> Another aspect is that function documentation looks great
>>> because there is this nifty describe-function-1 helper, but
>>> variable documentation looks poor because there is
>>> no such thing.
>> 
>> Cool! The whole help system would benefit from some renovation, but I don’t think anyone is excited to do it ;-)
>> 
>>> 
>>>> Does eglot and flymake already pass a :source cookie?
>>> 
>>> You mean ':origin', not ':source'.  Though the latter name is
>>> acceptable and there's plently of time to change to it if you
>>> think it's better or more consistent with other parts of Emacs.
>>> 
>>> Yes they do.  This cookie is automatic.  Maybe I should state that
>>> in the documentatiok.
>> 
>> Yeah, I think it’ll be good to mentioned them in the documentatiok.
>> 
>>> 
>>>> Those two displaying stuff together is the most possible case
>>>> I can think of.
>>> 
>>> In Eglot it's very usual to have three sources, and in Emacs
>>> Lisp you can also have three (function, variable and flymake).
>>> 
>>> You do need to set eldoc-documentation-strategy to
>>> eldoc-documentation-compose though (this should really
>>> be the default).
>> 
>> Huh, I wonder why I can see both flymake + eglot in the eldoc doc
>> buffer when my eldoc-documentation-strategy is the default value?
> 
> Because Eglot changes eldoc-documentation-strategy automatically.  It
> shouldn't but the default value is really bad.

Ah, I see.

> The reason the default value is historic.  Previously, there was a
> single producer of ElDoc, and only in Emacs Lisp.  It would decide
> whether to show variable _or_ function doc, even if a given symbol had
> more than one meaning.  So what's the problem with setting
> eldoc-documentation-strategy something like e-d-compose, you ask.
> 
> Well, because of the default value of eldoc-echo-area-use-multiline-p,
> people would be seeing "bouncing" in the echo area while editing Elisp,
> which is something they are not used to.
> 
> I think a very good solution is to set e-d-strategy to e-d-compose
> globally and e-e-a-use-multiline-p to 1 in emacs-lisp-mode.

I like it. I tried setting e-e-a-use-multiline to a larger value (like 2), but set it back to one after a while, because I don’t like all the skipping. I just need to see the signatures in the echo area, if I want to know more, I can always bringup eldoc doc buffer (or in my case an eldoc-box childframe) to see the full doc.

> 
> I once proposed this in this bug tracker, but the message was garbled by
> some side discussion, and I gave up.  And ElDoc wasn't so powerful then.

That happens all too often :-) Well, at least the current situation isn’t too bad.

Yuan