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

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

[Yuan Fu]

Eldoc can combine documentation from multiple sources and display them
together, however, if I’m not mistaken, it separates them with newline. It would be nice
if users can customize the separator to be some other things, like a
horizontal bar, eg,

(setq eldoc-source-separator
      (propertize "----------"
                  'display '(space :width text)
                  'face '(:stike-through t)))

Maybe even allow it to be a function so we can draw an appropriate
number of "-" in terminals.

Prompted by this report: https://github.com/casouri/eldoc-box/issues/61

I can do it, if everyone agrees that this is a good idea, and can come
up with a good name for the variable ;-)

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

[Yuan Fu]

Yuan Fu <casouri@gmail.com> writes:

> Eldoc can combine documentation from multiple sources and display them
> together, however, if I’m not mistaken, it separates them with newline. It would be nice
> if users can customize the separator to be some other things, like a
> horizontal bar, eg,
>
> (setq eldoc-source-separator
>       (propertize "----------"
>                   'display '(space :width text)
>                   'face '(:stike-through t)))
>
> Maybe even allow it to be a function so we can draw an appropriate
> number of "-" in terminals.
>
> Prompted by this report: https://github.com/casouri/eldoc-box/issues/61
>
> I can do it, if everyone agrees that this is a good idea, and can come
> up with a good name for the variable ;-)

Sorry, not sure why is the report duplicated. Closing this one.

Yuan

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

[João Távora]

[-- Attachment #1: Type: text/plain, Size: 722 bytes --]

Hi Yuan,

Mostly just replying so I'm kept in the loop.

I'm preparing a proposal for and Eldoc enhancements that could link with
this.

For example, i don't think that the eldoc function that displays in the
echo area should piggy-back on the contents of the eldoc doc buffer used by
the other display function. This was a misdesign (by me). Each display
function should be given as much information as possible and then decide
how and where to render without affecting other members of
'eldoc-display-functions'.

I think it's important to decide if things like line separation are
properties of a given member of 'eldoc-display-function' or if eldoc in
general. I strongly lean to the former.

João

[-- Attachment #2: Type: text/html, Size: 988 bytes --]

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

[Yuan Fu]

> On Mar 8, 2023, at 9:14 AM, João Távora <joaotavora@gmail.com> wrote:
> 
> Hi Yuan,
> 
> Mostly just replying so I'm kept in the loop.
> 
> I'm preparing a proposal for and Eldoc enhancements that could link with this.
> 
> For example, i don't think that the eldoc function that displays in the echo area should piggy-back on the contents of the eldoc doc buffer used by the other display function. This was a misdesign (by me). Each display function should be given as much information as possible and then decide how and where to render without affecting other members of 'eldoc-display-functions'.

I agree. It would be nice if eldoc can expose a variable containing the original value (a list of (doc :key :val…)). That’s essentially what the function in eldoc-box (eldoc-box-help-at-point) needed. Eldoc-box-help-at-point currently just copies the buffer text of eldoc--doc-buffer but it can be easily changed to copy from the aforementioned variable instead, and do it’s own formatting. (Alternatively eldoc-box-hel-at-point could TRT and invoke eldoc and get its output and show it, but simply using eldoc-doc-buffer is so easy and reliable ;-)

> 
> I think it's important to decide if things like line separation are properties of a given member of 'eldoc-display-function' or if eldoc in general. I strongly lean to the former.

I agree. But in the same time, eldoc’s rendering should be customizable too. If someone uses eldoc-doc-buffer and want to use fancier separators, they should be able to. That’ll be easier than writing another displayer that does everything the same as eldoc-doc-buffer except for using a different separator.

Yuan

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

[João Távora]

Yuan Fu <casouri@gmail.com> writes:

> I agree. But in the same time, eldoc’s rendering should be
> customizable too. If someone uses eldoc-doc-buffer and want to use
> fancier separators, they should be able to. That’ll be easier than
> writing another displayer that does everything the same as
> eldoc-doc-buffer except for using a different separator.

I've pushed two commits to master that address the design shortcoming I
was referring to.  Here they are summarized:

commit e19994fe8c000b0ed2dbc667cdec26cf54356907
    ElDoc: rework rendering of echo area (bug#62029)
    
    Previously, the display function 'eldoc-display-in-echo-area' reused
    the same buffer as 'eldoc-display-in-doc-buffer', but that made it
    harder to render documentation items differently depending on the
    specific constraints of each display functions.

commit 9b18407c7fd91313544acfb3457be5447987e20a
    ElDoc: remember origin backend in doc snippets (bug#62029)
    
    This lays groundwork for discriminating between different
    documentation providers in ElDoc display outlets, i.e. members
    of eldoc-display-functions

The first commit detaches eldoc-display-in-echo-area from
eldoc-display-in-doc-buffer (It also allows the backend to control the
display in the echo area specifically).  For the purposes of this bug,
it should allow eldoc-display-in-doc-buffer to more freely structure the
*eldoc* buffer with separators, etc.

The second commit adds a :origin cookie to each doc item passed to
eldoc-display-functions.  The origin is the name of the backend itself.
It could allow for better separators in the *eldoc* buffer where each
section is titled according to the backend that produced the
documentation.

So I guess what's missing for this bug is a customizable *eldoc* buffer
separator with a good default value, like one of those resize-resisting
horizontal separators.  Also, for customization, maybe `format-spec' can
be used?

João

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

[Yuan Fu]

> On Mar 23, 2023, at 2:33 PM, João Távora <joaotavora@gmail.com> wrote:
> 
> Yuan Fu <casouri@gmail.com> writes:
> 
>> I agree. But in the same time, eldoc’s rendering should be
>> customizable too. If someone uses eldoc-doc-buffer and want to use
>> fancier separators, they should be able to. That’ll be easier than
>> writing another displayer that does everything the same as
>> eldoc-doc-buffer except for using a different separator.
> 
> I've pushed two commits to master that address the design shortcoming I
> was referring to.  Here they are summarized:
> 
> commit e19994fe8c000b0ed2dbc667cdec26cf54356907
>    ElDoc: rework rendering of echo area (bug#62029)
> 
>    Previously, the display function 'eldoc-display-in-echo-area' reused
>    the same buffer as 'eldoc-display-in-doc-buffer', but that made it
>    harder to render documentation items differently depending on the
>    specific constraints of each display functions.
> 
> commit 9b18407c7fd91313544acfb3457be5447987e20a
>    ElDoc: remember origin backend in doc snippets (bug#62029)
> 
>    This lays groundwork for discriminating between different
>    documentation providers in ElDoc display outlets, i.e. members
>    of eldoc-display-functions
> 
> The first commit detaches eldoc-display-in-echo-area from
> eldoc-display-in-doc-buffer (It also allows the backend to control the
> display in the echo area specifically).  For the purposes of this bug,
> it should allow eldoc-display-in-doc-buffer to more freely structure the
> *eldoc* buffer with separators, etc.
> 
> The second commit adds a :origin cookie to each doc item passed to
> eldoc-display-functions.  The origin is the name of the backend itself.
> It could allow for better separators in the *eldoc* buffer where each
> section is titled according to the backend that produced the
> documentation.
> 
> So I guess what's missing for this bug is a customizable *eldoc* buffer
> separator with a good default value, like one of those resize-resisting
> horizontal separators.  Also, for customization, maybe `format-spec' can
> be used?

Brilliant! On top of format-spec, maybe also a face for the title, like eldoc-source-title.

For separator, maybe something like

(insert “Title" (propertize "-" 'display
                            '(space :align-to right)
                            'font-lock-face '(:strike-through t)
                            'face '(:strike-through t)))

for GUI, and use underline for terminal.

Yuan

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

[João Távora]

Yuan Fu <casouri@gmail.com> writes:

> For separator, maybe something like
>
> (insert “Title" (propertize "-" 'display
>                             '(space :align-to right)
>                             'font-lock-face '(:strike-through t)
>                             'face '(:strike-through t)))
>
> for GUI, and use underline for terminal.

I've now pushed a commit to master introducing the user variable
eldoc-doc-buffer-separator.  It's not a defcustom yet, as I'm not too
familiar with those, but feel free to change it.

  (defvar eldoc-doc-buffer-separator
    "String used to separate items in Eldoc documentation buffer."
    (concat "\n" (propertize "\n" 'face '(:inherit separator-line :extend t)) "\n"))

There is a difference between a separator and a title.  I've stopped
short of adding titles, as I fear it would be confusing unless the
content allows it.  To be investigated later for
eldoc-display-in-echo-area or maybe you can try it in eldoc-box.

Also, I've been testing with these unpushed changes to elisp-mode.el,
which render more of the docstring in emacs-lisp-mode.

The use case here is navigating around in an .el file while having a
window open with the *eldoc* buffer.

João


diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index 45e3848362e..054da900616 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -1779,11 +1779,22 @@ 'elisp-eldoc-documentation-function
 
 (defun elisp-eldoc-funcall (callback &rest _ignored)
   "Document function call at point by calling CALLBACK.
-Intended for `eldoc-documentation-functions' (which see)."
+Intended for `eldoc-documentatiok-functions' (which see)."
   (let* ((sym-info (elisp--fnsym-in-current-sexp))
-         (fn-sym (car sym-info)))
+         (fn-sym (car sym-info))
+         (echo (and fn-sym
+                    (apply #'elisp-get-fnsym-args-string sym-info)))
+         (fulldoc
+          (and echo
+               (with-temp-buffer
+                 (let ((standard-output (current-buffer)))
+                   (describe-function-1 fn-sym)
+                   (help-make-xrefs)
+                   (buffer-string))))))
     (when fn-sym
-      (funcall callback (apply #'elisp-get-fnsym-args-string sym-info)
+      (funcall callback
+               fulldoc
+               :echo echo
                :thing fn-sym
                :face (if (functionp fn-sym)
                          'font-lock-function-name-face
@@ -1794,9 +1805,18 @@ elisp-eldoc-var-docstring
 Intended for `eldoc-documentation-functions' (which see).
 Also see `elisp-eldoc-var-docstring-with-value'."
   (let* ((sym (elisp--current-symbol))
-         (docstring (and sym (elisp-get-var-docstring sym))))
+         (docstring (and sym (elisp-get-var-docstring sym)))
+         (rawdoc (and docstring
+                      (documentation-property
+                       sym 'variable-documentation t)))
+         (fulldoc (and rawdoc
+                       (with-temp-buffer
+                         (insert rawdoc)
+                         (help-make-xrefs)
+                         (buffer-string)))))
     (when docstring
-      (funcall callback docstring
+      (funcall callback fulldoc
+               :echo docstring
                :thing sym
                :face 'font-lock-variable-name-face))))
 

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

[Yuan Fu]

> On Mar 24, 2023, at 10:44 AM, João Távora <joaotavora@gmail.com> wrote:
> 
> Yuan Fu <casouri@gmail.com> writes:
> 
>> For separator, maybe something like
>> 
>> (insert “Title" (propertize "-" 'display
>>                             '(space :align-to right)
>>                             'font-lock-face '(:strike-through t)
>>                             'face '(:strike-through t)))
>> 
>> for GUI, and use underline for terminal.
> 
> I've now pushed a commit to master introducing the user variable
> eldoc-doc-buffer-separator.  It's not a defcustom yet, as I'm not too
> familiar with those, but feel free to change it.
> 
>  (defvar eldoc-doc-buffer-separator
>    "String used to separate items in Eldoc documentation buffer."
>    (concat "\n" (propertize "\n" 'face '(:inherit separator-line :extend t)) "\n"))
> 
> There is a difference between a separator and a title.  I've stopped
> short of adding titles, as I fear it would be confusing unless the
> content allows it.  To be investigated later for
> eldoc-display-in-echo-area or maybe you can try it in eldoc-box.
> 
> Also, I've been testing with these unpushed changes to elisp-mode.el,
> which render more of the docstring in emacs-lisp-mode.
> 
> The use case here is navigating around in an .el file while having a
> window open with the *eldoc* buffer.
> 
> João

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.

Yuan

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

[João Távora]

On Sat, Mar 25, 2023 at 3:05 AM Yuan Fu <casouri@gmail.com> wrote:
>
>
>
> > On Mar 24, 2023, at 10:44 AM, João Távora <joaotavora@gmail.com> wrote:
> >
> > Yuan Fu <casouri@gmail.com> writes:
> >
> >> For separator, maybe something like
> >>
> >> (insert “Title" (propertize "-" 'display
> >>                             '(space :align-to right)
> >>                             'font-lock-face '(:strike-through t)
> >>                             'face '(:strike-through t)))
> >>
> >> for GUI, and use underline for terminal.
> >
> > I've now pushed a commit to master introducing the user variable
> > eldoc-doc-buffer-separator.  It's not a defcustom yet, as I'm not too
> > familiar with those, but feel free to change it.
> >
> >  (defvar eldoc-doc-buffer-separator
> >    "String used to separate items in Eldoc documentation buffer."
> >    (concat "\n" (propertize "\n" 'face '(:inherit separator-line :extend t)) "\n"))
> >
> > There is a difference between a separator and a title.  I've stopped
> > short of adding titles, as I fear it would be confusing unless the
> > content allows it.  To be investigated later for
> > eldoc-display-in-echo-area or maybe you can try it in eldoc-box.
> >
> > Also, I've been testing with these unpushed changes to elisp-mode.el,
> > which render more of the docstring in emacs-lisp-mode.
> >
> > The use case here is navigating around in an .el file while having a
> > window open with the *eldoc* buffer.
> >
> > João
>
> 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.

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

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

João

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

[Yuan Fu]

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

Yuan

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

[João Távora]

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.

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

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

[Yuan Fu]

> 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

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

[Dmitry Gutov]

[-- Attachment #1: Type: text/plain, Size: 1544 bytes --]

On 30/03/2023 11:13, João Távora wrote:

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

Last time I tested Eglot's behavior (recently), Eldoc took away half the 
window to display the overloads of a function's signature. Screenshot 
attached.

That doesn't look like good behavior to me, no matter the language or 
IDE package used.

And then there's bouncing, yes.

[-- Attachment #2: Screenshot from 2023-04-11 02-58-58.png --]
[-- Type: image/png, Size: 275012 bytes --]

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

[João Távora]

Dmitry Gutov <dmitry@gutov.dev> writes:

> On 30/03/2023 11:13, João Távora wrote:
>
>>>> 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.
>
> Last time I tested Eglot's behavior (recently), 

How "recently"?  Does it have this commit?

commit d00e05daa96700860dbb9dc6527105e464ffb960
Author: João Távora <joaotavora@gmail.com>
Date:   Sat Mar 25 19:53:14 2023 +0000

    Eglot: take advantage of new Eldoc options for signature doc
    
    Only echo the "active signature", send all the other signatures for
    the *eldoc* buffer.
    
    * lisp/progmodes/eglot.el (eglot--sig-info): Rework protocol.
    (eglot-signature-eldoc-function): Rework.

This is also in the latest released Eglot 1.14, btw.

> Eldoc took away half the window to display the overloads of a
> function's signature. Screenshot attached.

This is exactly what I've been working on and discussing with Yuan and
others, so I'm pretty familiar with the situation.

> That doesn't look like good behavior to me, no matter the language or
> IDE package used.

I agree, and this is why I changed it.  Let's hope noone complains
(unlikely, but possible, as this changed longstanding behaviour).  

But here I was describing something not related to Eglot at all, rather
elisp-mode.el.  Do you have something to say about that?  Did you try
the patch I showed Yuan?

João

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

[Dmitry Gutov]

On 11/04/2023 14:25, João Távora wrote:
> Dmitry Gutov <dmitry@gutov.dev> writes:
> 
>> On 30/03/2023 11:13, João Távora wrote:
>>
>>>>> 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.
>>
>> Last time I tested Eglot's behavior (recently),
> 
> How "recently"?  Does it have this commit?
> 
> commit d00e05daa96700860dbb9dc6527105e464ffb960
> Author: João Távora <joaotavora@gmail.com>
> Date:   Sat Mar 25 19:53:14 2023 +0000
> 
>      Eglot: take advantage of new Eldoc options for signature doc
>      
>      Only echo the "active signature", send all the other signatures for
>      the *eldoc* buffer.
>      
>      * lisp/progmodes/eglot.el (eglot--sig-info): Rework protocol.
>      (eglot-signature-eldoc-function): Rework.
> 
> This is also in the latest released Eglot 1.14, btw.

I retested it just yesterday (and now as well), to take that screenshot.

But that was Emacs 29. With current master, it is indeed better.

>> Eldoc took away half the window to display the overloads of a
>> function's signature. Screenshot attached.
> 
> This is exactly what I've been working on and discussing with Yuan and
> others, so I'm pretty familiar with the situation.

>> That doesn't look like good behavior to me, no matter the language or
>> IDE package used.
> 
> I agree, and this is why I changed it.  Let's hope noone complains
> (unlikely, but possible, as this changed longstanding behaviour).
> 
> But here I was describing something not related to Eglot at all, rather
> elisp-mode.el.  Do you have something to say about that?  Did you try
> the patch I showed Yuan?

I have applied it. What should I be looking at?

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

[João Távora]

Dmitry Gutov <dmitry@gutov.dev> writes:

> On 11/04/2023 14:25, João Távora wrote:

>> protocol.
>>      (eglot-signature-eldoc-function): Rework.
>> This is also in the latest released Eglot 1.14, btw.
>
> I retested it just yesterday (and now as well), to take that screenshot.
>
> But that was Emacs 29. With current master, it is indeed better.

In Emacs 29, if you somehow manage to upgrade Eglot to >= 1.14 (cough
bug#62720 cough), you'll find it's also better.

>> elisp-mode.el.  Do you have something to say about that?  Did you try
>> the patch I showed Yuan?
>
> 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.

João

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

[Dmitry Gutov]

On 12/04/2023 14:06, João Távora wrote:
>>> elisp-mode.el.  Do you have something to say about that?  Did you try
>>> the patch I showed Yuan?
>> 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?

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.

And the thing with window jumping/blinking seems common enough across 
the modes. It's easiest to reproduce when just using Eglot with Company 
(for some reason or other, the blinking seems absent without the latter; 
but I only tested one simple scenario in one configuration).

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.

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

[Yuan Fu]

> On Apr 12, 2023, at 5:20 PM, Dmitry Gutov <dmitry@gutov.dev> wrote:
> 
> On 12/04/2023 14:06, João Távora wrote:
>>>> elisp-mode.el.  Do you have something to say about that?  Did you try
>>>> the patch I showed Yuan?
>>> 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?

I think it’s just meant to be a user customization. (setq-local eldoc-echo-area-use-multiline-p 1) basically means “don’t blink” (only display one line of doc). But I’m not sure why we need to customize it for elisp buffers, the default value should work more or less the same, no?

Yuan

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.

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

[João Távora]

On Thu, Apr 13, 2023 at 10:48 AM João Távora <joaotavora@gmail.com> wrote:

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

I've reproduced the bug with your recipe.  I don't normally notice
because I use a TTY emacs for the most part and it's absent there.
But in a graphical frame it is noticeable.  I'm having a look.

You could create a new bug report or point me to an existing one
I might have missed.

João

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

[João Távora]

[-- Attachment #1: Type: text/plain, Size: 823 bytes --]

On Thu, Apr 13, 2023 at 11:11 AM João Távora <joaotavora@gmail.com> wrote:
>
> On Thu, Apr 13, 2023 at 10:48 AM João Távora <joaotavora@gmail.com> wrote:
>
> > > 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?
>
> I've reproduced the bug with your recipe.  I don't normally notice
> because I use a TTY emacs for the most part and it's absent there.
> But in a graphical frame it is noticeable.  I'm having a look.
>
> You could create a new bug report or point me to an existing one
> I might have missed.

In the meantime, please try this patch.

João

[-- Attachment #2: 0001-Eldoc-don-t-overdisplay-if-using-eldoc-documentation.patch --]
[-- Type: text/x-patch, Size: 3647 bytes --]

From 5ea3b210a9f86b25e4999d3e55ec6bda4f6469af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20T=C3=A1vora?= <joaotavora@gmail.com>
Date: Thu, 13 Apr 2023 11:46:12 +0100
Subject: [PATCH] Eldoc: don't overdisplay if using eldoc-documentation-compose

This is about a particular value for eldoc-documentation-strategy.
'eldoc--documentation-compose-1' for the "patient"
'eldoc-documentation-compose' strategy was buggy.  It created and
callback and arranged so that it could potentially be invoked
immediately and trigger display, half-defeating the purpose of the
"patience" and causing blinking in the echo area.

Now it creates all the callbacks beforehand and only then passes them
to the corresponding members of eldoc-documentation-functions.  This
sets up the correct state in eldoc--invoke-strategy.

* lisp/emacs-lisp/eldoc.el (eldoc--documentation-compose-1):
Delete.
(eldoc-documentation-compose)
(eldoc-documentation-compose-eagerly): Rework.
---
 lisp/emacs-lisp/eldoc.el | 37 +++++++++++++++++++++----------------
 1 file changed, 21 insertions(+), 16 deletions(-)

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 1eb0d38c5ce..55fb518f990 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -681,29 +681,34 @@ eldoc-documentation-default
                     (lambda (f)
                       (funcall f (eldoc--make-callback :eager f)))))
 
-(defun eldoc--documentation-compose-1 (eagerlyp)
-  "Helper function for composing multiple doc strings.
-If EAGERLYP is non-nil show documentation as soon as possible,
-else wait for all doc strings."
-  (run-hook-wrapped 'eldoc-documentation-functions
-                    (lambda (f)
-                      (let* ((callback (eldoc--make-callback
-                                        (if eagerlyp :eager :patient)
-                                        f))
-                             (str (funcall f callback)))
-                        (if (or (null str) (stringp str)) (funcall callback str))
-                        nil)))
-  t)
-
 (defun eldoc-documentation-compose ()
   "Show multiple documentation strings together after waiting for all of them.
 This is meant to be used as a value for `eldoc-documentation-strategy'."
-  (eldoc--documentation-compose-1 nil))
+  (let (fns-and-callbacks)
+    ;; Make all the callbacks, this sets up state inside
+    ;; `eldoc--invoke-strategy' to know how many to wait for before
+    ;; displaying (bug#xxxxx)
+    (run-hook-wrapped 'eldoc-documentation-functions
+                      (lambda (f)
+                        (push (cons f (eldoc--make-callback :patient f))
+                              fns-and-callbacks)
+                        nil))
+    ;; Now call them.  The last one will trigger the display.
+    (cl-loop for (f . callback) in fns-and-callbacks
+             for str = (funcall f callback)
+             when (or (null str) (stringp str)) do (funcall callback str)))
+  t)
 
 (defun eldoc-documentation-compose-eagerly ()
   "Show multiple documentation strings one by one as soon as possible.
 This is meant to be used as a value for `eldoc-documentation-strategy'."
-  (eldoc--documentation-compose-1 t))
+  (run-hook-wrapped 'eldoc-documentation-functions
+                    (lambda (f)
+                      (let* ((callback (eldoc--make-callback :eager f))
+                             (str (funcall f callback)))
+                        (if (or (null str) (stringp str)) (funcall callback str))
+                        nil)))
+  t)
 
 (defun eldoc-documentation-enthusiast ()
   "Show most important documentation string produced so far.
-- 
2.39.2

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

[Dmitry Gutov]

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.

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

[Dmitry Gutov]

On 14/04/2023 00:53, Dmitry Gutov wrote:
>> 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.

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.

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

[João Távora]

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

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.

> 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.  Elisp
in de facto an exception.  OT1H e-e-a-use-multiline-p says "show a lot
of lines, no problem" by default, OTOH if you show more than one line in
Elisp mode _only_, Elisp modes will think you're making a breaking
change and disrespecting their ElDoc echo area expectations, when in
fact you're not.

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.

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.

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

It doesn't, sure.  But in when you turn on Eglot mode you don't have
this expectation of single-lineness, and in Elisp mode you do (or at
some old-timers do, I assume).

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

I see the change of e-d-strategy's default to e-d-compose has having 0
impact on the "expectations" of any other major-mode _other_ than Elisp.
If you know some other mode, please tell me.

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

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.

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

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

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

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

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

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

That's taken care of, at least AFAICT.  

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

A little Emacs -Q goes a long way, at least for me.  I'm vaguely recall
reading these complaints, but they never rang a bell and i couldn't see
them, so I just assumed they were misunderstandings and forgot.

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

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

João

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

[Dmitry Gutov]

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.

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

[João Távora]

Dmitry Gutov <dmitry@gutov.dev> writes:

> On 14/04/2023 02:01, João Távora wrote:

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

My patch to elisp-mode.el that I showed Yuan Fu makes the two function
elisp-eldoc-funcall and elisp-eldoc-var-docstring send very rich
information to the *eldoc* buffer, but only summarized information to
the echo area, via the new :echo option in newer ElDoc 1.14.0.  This
allows users who have eldoc-documentation-compose as the strategy to
have the buffer on the side and see it update with full docstrings of
the things they are navigating, organized with a suitable separator.
This is why I suggested you try M-x eldoc-doc-buffer along with your
tests.

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

I'm not aware of many.  SLY has a eldoc-documentation-function that
prints multiline content, and SLY users have never complained about it.

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

The problem is that "asking users" is really an impossibility.  Best one
can do is present this in Emacs devel and hope the knees don't jerk too
much.  If you have better ideas, please put them forth and help
implement them.

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

Agreed.

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

OK I see.  Well I don't think it's a tragedy to do that with
emacs-lisp-mode-hook instead.  We're only talking about the people
familiar with "new" ElDoc features, which is arguably a very small
group, because -- unless they are using my patch to Yuan Fu -- these
features aren't yet very developed in Elisp-mode.  So the likelyhood of
that backlash is very low.

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

At first sight, I think that's primarily a problem in Company mode.
Let's continue in that bug.

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

If I understand your preference for "put it closer to the input", that'd
just be another function in eldoc-display-functions.  Yuan Fu's
eldoc-box is such an example.

[ BTW, today I've pushed a Flymake feature
flymake-show-diagnostics-at-end-of-line that puts diagnostics "closer to
the input" (though not via Eldoc, of course) ]

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

Beats me.

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

Yes.  Read that as "...because if one uses it...".

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

To be clear, what I'm thinking of is to have _3/4_ functions in
elisp-mode's e-d-functions

  elisp-eldoc-funcall
  elisp-eldoc-var-docstring
  elisp-eldoc-failover-funcal-to-var
  flymake-eldoc-function (optional, depends on Flymake mode)

By default, in Emacs -Q, the first 2 send _nothing_ to echo (via the new
ElDoc :echo feature) are but send rich info to other
eldoc-display-functions.  The special
elisp-eldoc-failover-funcall-to-var sends _only_ to the echo area (and
only ever one line).

A customization variable elisp-eldoc-legacy-oneliners, set to t by
default, could control this.  If set to nil, then the first 2 would
behave as in Yuan Fu's patch and the third one would do nothing (or not
exist).

Then, I contend, eglot-documentation-strategy can "safely" be set to
eldoc-documentation-compose without annoying old timers.  And no
touching of eldoc-echo-area-use-multiline-p.

In my view, *eldoc* doesn't need any hook.  I don't remember or
understand this hook idea today, and I don't think I ever did.  But if
you do and think it's helpful to bring it back, you can always
illustrate it in code.

João

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

[Dmitry Gutov]

On 14/04/2023 03:04, João Távora wrote:
> Dmitry Gutov <dmitry@gutov.dev> writes:
> 
>> On 14/04/2023 02:01, João Távora wrote:
> 
>>> 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.
> 
> My patch to elisp-mode.el that I showed Yuan Fu makes the two function
> elisp-eldoc-funcall and elisp-eldoc-var-docstring send very rich
> information to the *eldoc* buffer, but only summarized information to
> the echo area, via the new :echo option in newer ElDoc 1.14.0.  This
> allows users who have eldoc-documentation-compose as the strategy to
> have the buffer on the side and see it update with full docstrings of
> the things they are navigating, organized with a suitable separator.
> This is why I suggested you try M-x eldoc-doc-buffer along with your
> tests.

Okay, I see it now. I think it doesn't look optimal, for example, when 
point is on a variable, it lists just the name and the docstring. C-h v 
has a much richer display which might be worth reusing here (or more 
parts of it, at least). But those are details.

To sum up, if I may, you have reached the conclusion that the doc buffer 
should look different, and its text needs to be produced differently, 
than the notifications in the echo area. (*)

>>> 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).
> 
> I'm not aware of many.  SLY has a eldoc-documentation-function that
> prints multiline content, and SLY users have never complained about it.

At certain point users start to self-select, especially if they don't 
know how things could be better/different. As evidenced just by the 
other bug report with the blinkage in the echo area which should be 
apparent to anybody with graphical Emacs.

So "users of package xxx don't complain about yyy" is not as strong an 
argument as "almost all packages out there use approach yyy".

>>> 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.
> 
> The problem is that "asking users" is really an impossibility.  Best one
> can do is present this in Emacs devel and hope the knees don't jerk too
> much.  If you have better ideas, please put them forth and help
> implement them.

I've done it before, and the results definitely aren't representative of 
the whole community (like 10 responses or so), but they has been 
convincing enough for me to abandon the particular idea I had. ;-(

You could have a different result, though.

>> 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.
> 
> OK I see.  Well I don't think it's a tragedy to do that with
> emacs-lisp-mode-hook instead.  We're only talking about the people
> familiar with "new" ElDoc features, which is arguably a very small
> group, because -- unless they are using my patch to Yuan Fu -- these
> features aren't yet very developed in Elisp-mode.  So the likelyhood of
> that backlash is very low.

The patch will make it in soon enough, right? I'm not sure I understand 
this argument.

>> 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.
> 
> At first sight, I think that's primarily a problem in Company mode.
> Let's continue in that bug.

Sure.

>> 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.
> 
> If I understand your preference for "put it closer to the input", that'd
> just be another function in eldoc-display-functions.  Yuan Fu's
> eldoc-box is such an example.

Might be. If signature info is annotated with a particular key, which 
that display function will pick up. But I'm not sure how to make it so 
that the other display functions ignore it. If siginfo is displayed with 
eldoc-box is something similar, we don't need it in the echo area. Maybe 
not in eldoc-buffer either (not quite sure).

Further, though, the siginfo could become a structured piece of data, 
rather than a string (e.g. I recall an interface where the user could 
switch between overloads using arrow keys). That is unlikely to fit 
eldoc's model at all.

> [ BTW, today I've pushed a Flymake feature
> flymake-show-diagnostics-at-end-of-line that puts diagnostics "closer to
> the input" (though not via Eldoc, of course) ]
> 

It does not bootstrap, unfortunately. Or otherwise build:

   load("progmodes/elisp-mode")
   load("loadup.el")
Eager macro-expansion failure: (wrong-type-argument listp t)

And that's in a clean new worktree.

>>> 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.
> 
> To be clear, what I'm thinking of is to have _3/4_ functions in
> elisp-mode's e-d-functions
> 
>    elisp-eldoc-funcall
>    elisp-eldoc-var-docstring
>    elisp-eldoc-failover-funcal-to-var

Note that this one is easy enough to do for Elisp because both functions 
are synchronous and you can determine the success of elisp-eldoc-funcall 
by its return value. Not so easy to do for eldoc functions in general 
(e.g. to do a similar failover for Eglot).

>    flymake-eldoc-function (optional, depends on Flymake mode)
> 
> By default, in Emacs -Q, the first 2 send _nothing_ to echo (via the new
> ElDoc :echo feature) are but send rich info to other
> eldoc-display-functions.  The special
> elisp-eldoc-failover-funcall-to-var sends _only_ to the echo area (and
> only ever one line).

Nice. Let me get back to this later down in this email (**).

> A customization variable elisp-eldoc-legacy-oneliners, set to t by
> default, could control this.  If set to nil, then the first 2 would
> behave as in Yuan Fu's patch and the third one would do nothing (or not
> exist).
> 
> Then, I contend, eglot-documentation-strategy can "safely" be set to
> eldoc-documentation-compose without annoying old timers.  And no
> touching of eldoc-echo-area-use-multiline-p.

It's a valid hypothesis, at least.

> In my view, *eldoc* doesn't need any hook.  I don't remember or
> understand this hook idea today, and I don't think I ever did.  But if
> you do and think it's helpful to bring it back, you can always
> illustrate it in code.

We have a hook (hooks) eldoc-documentation-function (and -functions), 
which determine what should be displayed in the echo area.

And then we have this eldoc buffer, which as we apparently agree now 
can/should have a different set of output functions (** above), and even 
the functions with information about the same things will usually print 
it in different ways (* above). That basically tells me that 
eldoc-buffer could use separate hooks, rather than reuse existing one, e.g.
eldoc-buffer-output-function, eldoc-buffer-output-functions.

Perhaps the former would reuse the existing set of 
combinator/strategies, but I can easily see eldoc-documentation-function 
and eldoc-buffer-output-function set to different strategies.

This separation could still work together with eldoc-display-functions 
(the different functions in this list would just pick up its info from 
different hooks).

I'm not going to bother with a patch because backward compatibility, and 
blah, and the current approach can obviously function too, though in a 
more complicated way.

But you might want to consider ways the echo and the buffer could be 
configured to use different combinator strategies. I see no inherent 
reason for them to always use the same one.

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

[João Távora]

Dmitry Gutov <dmitry@gutov.dev> writes:

> On 14/04/2023 03:04, João Távora wrote:
>> Dmitry Gutov <dmitry@gutov.dev> writes:
>> 
>>> On 14/04/2023 02:01, João Távora wrote:
>> 
>>>> 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.
>> My patch to elisp-mode.el that I showed Yuan Fu makes the two
>> function
>> elisp-eldoc-funcall and elisp-eldoc-var-docstring send very rich
>> information to the *eldoc* buffer, but only summarized information to
>> the echo area, via the new :echo option in newer ElDoc 1.14.0.  This
>> allows users who have eldoc-documentation-compose as the strategy to
>> have the buffer on the side and see it update with full docstrings of
>> the things they are navigating, organized with a suitable separator.
>> This is why I suggested you try M-x eldoc-doc-buffer along with your
>> tests.
>
> Okay, I see it now. I think it doesn't look optimal, for example, when
> point is on a variable, it lists just the name and the docstring. C-h
> v has a much richer display which might be worth reusing here (or more
> parts of it, at least). But those are details.

Yes, yes.  The problem is how to get that rich content.  The defun case
has a describe-function-1 helper, but sadly no such helper for
variables.  I could just invoke help.el wholesale, as company does.  But
that has a bug that it stomps in the *Help* buffer.  I agree it's just
details.

> To sum up, if I may, you have reached the conclusion that the doc
> buffer should look different, and its text needs to be produced 
> differently, than the notifications in the echo area. (*)

They are usually produced in the same way, and ideally should.  Only the
display is different according to the viewport.  The echo area is a an
extreme case of a very constrained port.  But the plan for ElDoc is for
backends to send even more structured text to eldoc-display-functions
and have them do any kind of markup, fontification, etc.
eldoc-echo-area-display uses :echo if available now, but the main thing
I fixed in ElDoc 1.14 was its sharing and cutting of the same *eldoc*
buffer.  Each display function should have its own working space.

>>>> 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).
>> I'm not aware of many.  SLY has a eldoc-documentation-function that
>> prints multiline content, and SLY users have never complained about it.
>
> At certain point users start to self-select, especially if they don't
> know how things could be better/different. As evidenced just by the
> other bug report with the blinkage in the echo area which should be
> apparent to anybody with graphical Emacs.
>
> So "users of package xxx don't complain about yyy" is not as strong an
> argument as "almost all packages out there use approach yyy".

I don't know to be honest.  And then not all packages are equally
popular.  

> I've done it before, and the results definitely aren't representative
> of the whole community (like 10 responses or so), but they has been
> convincing enough for me to abandon the particular idea I had. ;-(

The very vast majority of users don't care, and will accept the
developers criteria as to what he or she chose is best.  As for the ones
that do care, whether with positive or negative feelings, you only hear
about a minority of them, and always biased to the negative.  So as your
little experiment showed you're walking in a foggy swamp, with a
blindfold, inside a box.

> You could have a different result, though.

Doubt it.

>>> 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.
>> OK I see.  Well I don't think it's a tragedy to do that with
>> emacs-lisp-mode-hook instead.  We're only talking about the people
>> familiar with "new" ElDoc features, which is arguably a very small
>> group, because -- unless they are using my patch to Yuan Fu -- these
>> features aren't yet very developed in Elisp-mode.  So the likelyhood of
>> that backlash is very low.
>
> The patch will make it in soon enough, right? I'm not sure I
> understand this argument.

What patch.  I was describing the risks of simply setting
eldoc-echo-area-use-multiline-p to 1 in elisp mode, which are very
small.


>> If I understand your preference for "put it closer to the input",
>> that'd
>> just be another function in eldoc-display-functions.  Yuan Fu's
>> eldoc-box is such an example.
>
> Might be. If signature info is annotated with a particular key, which
> that display function will pick up. But I'm not sure how to make it so
> that the other display functions ignore it.

You start passing structured text.  See the docstring of
eldoc-documentation-functions:

    To call the CALLBACK function, the hook function must pass it an
    obligatory argument DOCSTRING, a string containing the
    documentation, followed by an optional list of arbitrary
    keyword-value pairs of the form (:KEY VALUE :KEY2 VALUE2...).
    The information contained in these pairs is understood by members
    of `eldoc-display-functions', allowing the
    documentation-producing backend to cooperate with specific
    documentation-displaying frontends.

> Further, though, the siginfo could become a structured piece of data,
> rather than a string (e.g. I recall an interface where the user could
> switch between overloads using arrow keys). That is unlikely to fit
> eldoc's model at all.

Yes, ElDoc is a "at point documentation system", it's not a completion
system.

> It does not bootstrap, unfortunately. Or otherwise build:
>
>   load("progmodes/elisp-mode")
>   load("loadup.el")
> Eager macro-expansion failure: (wrong-type-argument listp t)
>
> And that's in a clean new worktree.

Oof that's bad.  My fault?  I'll have a look.

>>>> 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.
>> To be clear, what I'm thinking of is to have _3/4_ functions in
>> elisp-mode's e-d-functions
>>    elisp-eldoc-funcall
>>    elisp-eldoc-var-docstring
>>    elisp-eldoc-failover-funcal-to-var
>
> Note that this one is easy enough to do for Elisp because both
> functions are synchronous and you can determine the success of
> elisp-eldoc-funcall by its return value. Not so easy to do for eldoc
> functions in general (e.g. to do a similar failover for Eglot).

That's impossible in general.  The thing you're waiting to fail over
from might never arrive.  That's why member of eldoc-doc-functions are
supposed to make an educated promise that they will call the callback in
the return value.  If that promise is upheld, it's not much harder to
combine to eldoc-documentation-functions into one.

(defun eldoc-race (fns) "Combine FNS into a race"
  (lambda (callback)
    (let* (winner-found
           (newcb (lambda (&rest r)
                    (unless winner-found
                      (apply callback r)
                      (setq winner-found t)))))
      (mapc (lambda (f) (funcall f newcb)) fns))))

Obviously you can have a million different rules for these "races".

In practice, I've never seen someone discontent with the default
eldoc-documentation-compose though.  Saw lots of complaints about "echo
are flooding" and "enormous echo areas".  I recommended
eldoc-echo-area-use-multiline-p be used, and people were content.  But
it wasn't very clean, so what we have is cleaner now.

>>    flymake-eldoc-function (optional, depends on Flymake mode)
>> By default, in Emacs -Q, the first 2 send _nothing_ to echo (via the
>> new
>> ElDoc :echo feature) are but send rich info to other
>> eldoc-display-functions.  The special
>> elisp-eldoc-failover-funcall-to-var sends _only_ to the echo area (and
>> only ever one line).
>
> Nice. Let me get back to this later down in this email (**).

It's nice but not perfect.  Nothing can be.  If you look closely,
there's just as much backward compatibility breakage as there is by
changing e-e-a-use-multiline-p to t in elisp-mode.  I.e. a happy user of
eldoc-documentation-compose today will be equally disappointed tomorrow
(she won't see funcall and variable together as usual).  She will also
have to do changes to her config to get that back.

And this second idea of mine is way, waaay more complicated, than the
first.  And just for the sake of not stomping on a user customizable
variable which, which would have the same (very minor) negative effect,
in fact I think _exactly the same_.

And this second idea of mine yet to be put into code;-)

> Perhaps the former would reuse the existing set of
> combinator/strategies, [...]
> This separation could still [...]
> I'm not going to bother with a patch because backward compatibility,
> and blah, 

Yes, I understand this, but the consequence downside is that your case
is weakened because other brains can't see the advantages as clearly as
your brain does.  And all brains make mistakes.  Code doesn't.

> and the current approach can obviously function too, though
> in a more complicated way.

IMO, that can only be asserted when comparing the two things side by
side, with actual examples.  Frequently some things are easy to do in
one approach and harder in the competing approach, and vice versa.  In
my brain it is your solution which _sounds_ way more complicated.  The
key word is "sound" which I have to use because I'm hearing words inside
my brain as I read your writing.  I'm not seeing your solution function
in front of me, and described in non-ambiguous Elisp language with
working examples.

João

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

[Dmitry Gutov]

On 14/04/2023 03:04, João Távora wrote:
> [ BTW, today I've pushed a Flymake feature
> flymake-show-diagnostics-at-end-of-line that puts diagnostics "closer to
> the input" (though not via Eldoc, of course) ]

Now that it's merged, though, I think it does look pretty cool.

Here is a minor suggestion:

diff --git a/lisp/progmodes/flymake.el b/lisp/progmodes/flymake.el
index b744a717c5c..31418895da1 100644
--- a/lisp/progmodes/flymake.el
+++ b/lisp/progmodes/flymake.el
@@ -447,7 +447,7 @@ flymake-note-echo
    :package-version '(Flymake . "1.3.4"))

  (defface flymake-end-of-line-diagnostics-face
-  '((t :height 0.7 :box (:line-width 1)))
+  '((t :height 0.9 :box (:line-width (1 . -1))))
    "Face used for end-of-line diagnostics.
  See variable `flymake-show-diagnostics-at-end-of-line'."
    :package-version '("Flymake" . "1.3.5"))


The negative width stops the line height from shifting, and the increase 
in font size is definitely subjective, but 0.7 really looked too small here.

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

[João Távora]

On Tue, Apr 18, 2023 at 1:47 AM Dmitry Gutov <dmitry@gutov.dev> wrote:

> Here is a minor suggestion:
>

> The negative width stops the line height from shifting, and the increase
> in font size is definitely subjective, but 0.7 really looked too small here.

Feel free to push that, it makes sense.  But maybe halfway at 0.8?

More seriously though, this clashes with Company's overlay-based
dropdown, and I don't know how to fix that.  Company makes Flymake's
end-of-line overlay temporarily invisible, which is good, but
it still takes a lot of space, so the dropdown is ridiculously
offset to the right.

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

[Dmitry Gutov]

On 18/04/2023 14:17, João Távora wrote:
> On Tue, Apr 18, 2023 at 1:47 AM Dmitry Gutov <dmitry@gutov.dev> wrote:
> 
>> Here is a minor suggestion:
>>
> 
>> The negative width stops the line height from shifting, and the increase
>> in font size is definitely subjective, but 0.7 really looked too small here.
> 
> Feel free to push that, it makes sense.  But maybe halfway at 0.8?

Split that in half again and pushed 0.85 ;-) Feel free to revert or 
change, of course.

> More seriously though, this clashes with Company's overlay-based
> dropdown, and I don't know how to fix that.> Company makes Flymake's
> end-of-line overlay temporarily invisible, which is good, but
> it still takes a lot of space, so the dropdown is ridiculously
> offset to the right.

Right. Like line numbers or other display-related features.

I'm not sure how to fix that for the overlay popup frontend, but one 
good news is that people can use child frame based ones, those should be 
compatible.

For all other users (like tty ones), also consider a different mode of 
operation: when the corresponding overlay is only shown when point is on 
the error, or mouse hovers over it. That can reduce the odds of conflict 
to the minimum.

This was it would be a straight substitute for help-at-pt and eldoc, for 
flymake's purposes.

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

[Dmitry Gutov]

[-- Attachment #1: Type: text/plain, Size: 2627 bytes --]

Hi Joao,

On 15/04/2023 12:41, João Távora wrote:
>> Perhaps the former would reuse the existing set of
>> combinator/strategies, [...]
>> This separation could still [...]
>> I'm not going to bother with a patch because backward compatibility,
>> and blah,
> Yes, I understand this, but the consequence downside is that your case
> is weakened because other brains can't see the advantages as clearly as
> your brain does.  And all brains make mistakes.  Code doesn't.
> 
>> and the current approach can obviously function too, though
>> in a more complicated way.
> IMO, that can only be asserted when comparing the two things side by
> side, with actual examples.  Frequently some things are easy to do in
> one approach and harder in the competing approach, and vice versa.  In
> my brain it is your solution which_sounds_  way more complicated.  The
> key word is "sound" which I have to use because I'm hearing words inside
> my brain as I read your writing.  I'm not seeing your solution function
> in front of me, and described in non-ambiguous Elisp language with
> working examples.

This has been on my TODO for a while (sorry about the wait), so here's a 
rough patch for illustration. It incorporates an updated version of your 
earlier proposal for elisp-mode.el (from 24/03/2023) for comparison.

Some benefits that should come with it are:

1. The elements in eldoc-documentation-functions can do less work than 
the ones in eldoc-buffer-functions. I understand that this is not a 
priority for Eglot which just uses the same source of information, but 
for others it can be different. E.g. require an extra network call to 
fetch the full docstring (this is not a hypothetical).
2. Different eldoc-documentation-strategy can be used for the buffer's 
contents. E.g. using the current one (first non-nil) for the echo and 
the "compose" for the buffer seems logical to me, and the patch 
illustrates it.
3. 'M-x eldoc-doc-buffer' is made synchronous and only shows info for 
the point, not a result of some earlier lookup, which might (or might 
not) get refreshed asynchronously.

There can be other solutions for 1 (e.g. passing some extra info *into* 
each eldoc-documentation-functions, so they can choose what to show, 
rather than have them provide all variations in the returned value), but 
it seems harder to find one for 2.

Drawbacks:
1. Seemingly more duplication in the code (but other doc providers might 
choose to use entirely different looks; no duplication in that case).
2. When both functions are based off the same info, reusing it gets 
harder. But it's nothing a extra cache cannot fix.

[-- Attachment #2: eldoc-doc-buffer.diff --]
[-- Type: text/x-patch, Size: 6728 bytes --]

diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 22144ed7c18..4646b4e98c2 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -409,7 +409,7 @@ eldoc-display-message-no-interference-p
 
 \f
 (defvar eldoc-documentation-functions nil
-  "Hook of functions that produce doc strings.
+  "Hook of functions that produce short doc strings.
 
 A doc string is typically relevant if point is on a function-like
 name, inside its arg list, or on any object with some associated
@@ -470,8 +470,11 @@ eldoc-documentation-functions
 taken into account if the major mode specific function does not
 return any documentation.")
 
+(defvar eldoc-buffer-functions nil
+  "Hook of functions that produce doc strings for `eldoc-doc-buffer'.")
+
 (defvar eldoc-display-functions
-  '(eldoc-display-in-echo-area eldoc-display-in-buffer)
+  '(eldoc-display-in-echo-area)
   "Hook of functions tasked with displaying ElDoc results.
 Each function is passed two arguments: DOCS and INTERACTIVE.  DOCS
 is a list (DOC ...) where DOC looks like (STRING :KEY VALUE :KEY2
@@ -486,22 +489,21 @@ eldoc-display-functions
 
 (defvar eldoc--doc-buffer nil "Buffer displaying latest ElDoc-produced docs.")
 
-(defun eldoc-doc-buffer (&optional interactive)
-  "Get or display ElDoc documentation buffer.
-
-The buffer holds the results of the last documentation request.
-If INTERACTIVE, display it.  Else, return said buffer."
-  (interactive (list t))
-  (unless (buffer-live-p eldoc--doc-buffer)
-    (user-error (format
-                 "ElDoc buffer doesn't exist, maybe `%s' to produce one."
-                 (substitute-command-keys "\\[eldoc]"))))
+(defun eldoc-doc-buffer ()
+  "Display the ElDoc documentation buffer.
+
+Request and show the documentation relevant to the thing at point."
+  (interactive)
+  (if (buffer-live-p eldoc--doc-buffer) (kill-buffer eldoc--doc-buffer))
+  (let ((eldoc-documentation-functions eldoc-buffer-functions)
+        (eldoc-display-functions '(eldoc-display-in-buffer))
+        (eldoc-documentation-strategy eldoc-buffer-strategy))
+    (eldoc-print-current-symbol-info))
+  (cl-assert (buffer-live-p eldoc--doc-buffer))
   (with-current-buffer eldoc--doc-buffer
-    (cond (interactive
-           (rename-buffer (replace-regexp-in-string "^ *" ""
-                                                    (buffer-name)))
-           (display-buffer (current-buffer)))
-          (t (current-buffer)))))
+    (rename-buffer (replace-regexp-in-string "^ *" ""
+                                             (buffer-name)))
+    (pop-to-buffer (current-buffer))))
 
 (defvar eldoc-doc-buffer-separator
   (concat "\n" (propertize "\n" 'face '(:inherit separator-line :extend t)) "\n")
@@ -676,7 +678,7 @@ eldoc-display-in-buffer
   "Display DOCS in a dedicated buffer.
 If INTERACTIVE is t, also display the buffer."
   (eldoc--format-doc-buffer docs)
-  (when interactive (eldoc-doc-buffer t)))
+  (when interactive (eldoc-doc-buffer)))
 
 (defun eldoc-documentation-default ()
   "Show the first non-nil documentation string for item at point.
@@ -793,6 +795,11 @@ eldoc-documentation-strategy
                 (function :tag "Other function"))
   :version "28.1")
 
+(defcustom eldoc-buffer-strategy #'eldoc-documentation-compose
+  "Doc string doc string."
+  :type 'function
+  :version "30.1")
+
 (defun eldoc--supported-p ()
   "Non-nil if an ElDoc function is set for this buffer."
   (and (not (memq eldoc-documentation-strategy '(nil ignore)))
diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index ff90a744ea3..a13904ddb26 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -355,6 +355,10 @@ emacs-lisp-mode
             #'elisp-eldoc-funcall nil t)
   (add-hook 'eldoc-documentation-functions
             #'elisp-eldoc-var-docstring nil t)
+  (add-hook 'eldoc-buffer-functions
+            #'elisp-eldoc-funcall-buf nil t)
+  (add-hook 'eldoc-buffer-functions
+            #'elisp-eldoc-var-docstring-buf nil t)
   (add-hook 'xref-backend-functions #'elisp--xref-backend nil t)
   (setq-local project-vc-external-roots-function #'elisp-load-path-roots)
   (setq-local syntax-propertize-function #'elisp-mode-syntax-propertize)
@@ -1822,6 +1826,22 @@ elisp-eldoc-funcall
                          'font-lock-function-name-face
                        'font-lock-keyword-face)))))
 
+(defun elisp-eldoc-funcall-buf (callback &rest _ignored)
+  (let* ((fn-sym (car (elisp--fnsym-in-current-sexp)))
+         (fulldoc
+          (and (and fn-sym (symbolp fn-sym) (fboundp fn-sym))
+               (with-temp-buffer
+                 (let ((standard-output (current-buffer)))
+                   (describe-function-1 fn-sym)
+                   (help-make-xrefs)
+                   (buffer-string))))))
+    (when fn-sym
+      (funcall callback fulldoc
+               :thing fn-sym
+               :face (if (functionp fn-sym)
+                         'font-lock-function-name-face
+                       'font-lock-keyword-face)))))
+
 (defun elisp-eldoc-var-docstring (callback &rest _ignored)
   "Document variable at point by calling CALLBACK.
 Intended for `eldoc-documentation-functions' (which see).
@@ -1833,6 +1853,21 @@ elisp-eldoc-var-docstring
                :thing sym
                :face 'font-lock-variable-name-face))))
 
+(defun elisp-eldoc-var-docstring-buf (callback &rest _ignored)
+  (let* ((sym (elisp--current-symbol))
+         (rawdoc (and (boundp sym)
+                      (documentation-property
+                       sym 'variable-documentation t)))
+         (fulldoc (and rawdoc
+                       (with-temp-buffer
+                         (insert rawdoc)
+                         (help-make-xrefs)
+                         (buffer-string)))))
+    (when fulldoc
+      (funcall callback fulldoc
+               :thing sym
+               :face 'font-lock-variable-name-face))))
+
 (defun elisp-eldoc-var-docstring-with-value (callback &rest _)
   "Document variable at point by calling CALLBACK.
 Intended for `eldoc-documentation-functions' (which see).
diff --git a/lisp/progmodes/flymake.el b/lisp/progmodes/flymake.el
index b27e6527f81..a56ec6cf8b0 100644
--- a/lisp/progmodes/flymake.el
+++ b/lisp/progmodes/flymake.el
@@ -1284,6 +1284,7 @@ flymake-mode
     (add-hook 'after-save-hook 'flymake-after-save-hook nil t)
     (add-hook 'kill-buffer-hook 'flymake-kill-buffer-hook nil t)
     (add-hook 'eldoc-documentation-functions 'flymake-eldoc-function t t)
+    (add-hook 'eldoc-buffer-functions 'flymake-eldoc-function t t)
 
     ;; If Flymake happened to be already ON, we must cleanup
     ;; existing diagnostic overlays, lest we forget them by blindly