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

[Dmitry Gutov <dmitry@gutov.dev>]

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.