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

From: João Távora <[email-masked]>
Date: Thu, 30 Mar 2023 09:13:56 +0100

Yuan Fu <[email-masked]> 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.

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

João