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