bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[João Távora]

Hello,

As I recently mentioned to Lars over at bug#32243, the recent changes to
ElDoc have made it possible for the user and the major mode to control
the information that is eventually showed to the user in the echo area.
That bug, which concerned Elisp function signatures overriding/hiding
Flymake diagnostic lines, has been fixed, mostly because Flymake itself
is an independent producer of Eldoc information, and one is now given
the tools to coordinate between different sources.

The TL;DR is that this bug is a proposal for changing the default value
of `eldoc-documentation-strategy` to `eldoc-documentation-compose`, in
Elisp mode so that all these sources can serve us simultaneously.

So, in Emacs master, we have reasonably common sources for Elisp mode,
which may all act and be useful at the same time.  They occupy this
relative order in 'eldoc-documentation-functions':

- elisp-eldoc-funcall
- elisp-eldoc-var-docstring
- flymake-eldoc-function  (only active if Flymake mode is enabled)

I've recently moved `flymake-eldoc-function` from first to the last spot
in the list.  If I hadn't done that, the default behaviour when writing
a sexp such as, say:

   (my-dear-function [point here])

would be to foremost greet the user with the Flymake error message about
insufficient args being supplied to the `my-dear-function` call about to
be written, rather than what those args are supposed to be.  Obviously
this defeats the purpose of having ElDoc serve as a code-writing aid.

But now take this other situation and suppose there is an error in the
"foo" where point is on:

   (my-dear-function 'fo[point here]o 42 'bar)

Having the sexp written with a suitable number of arguments but with
some Flymake mistake will now fail to notify us of those mistakes, since
the signature information takes priority.  This is similar, if not the
same, as the aforementioned bug#32243.

Earlier, there was no obvious solution to this, especially if one
insisted on using only a one-line-tall echo area at the maximum.  Now,
after Mark Oteiza's introduction of `eldoc-documentation-functions`,
there are ways to configure suitable behaviours.  In particular there is
`eldoc-documentation-strategy` (formerly `eldoc-documentation-function`,
singular), which tells how to coordinate ElDoc information from multiple
sources.

This variable's value defaults to `eldoc-documentation-default`
globally. I suggest we default it to `eldoc-documentation-compose` in
Elisp mode, so the three functions occupying
`eldoc-documentation-functions` can be in play at the same time.  This
is because the information conveyed by them can be generally be useful
at the same time.

If that creates too tall an echo area for some, I want to mention that,
for now, there is the variable `eldoc-echo-area-use-multiline-p` to
control this.  For those willing to bear with 2 lines at most, I think
this is guaranteed.  For non-users of Flymake, for instance, 2 lines
usually happens if one lands the cursor on documented Elisp variable
being used inside a documented function.  With the cursor on the first
argument in this form:

   (run-with-idle-timer eldoc-idle-delay nil ...)

The echo area would show two lines instead of the usual 1:

    eldoc-idle-delay: Number of seconds of idle time to wait before printing.
    run-with-idle-timer: (SECS REPEAT FUNCTION &rest ARGS)

Also note that even if one sets `eldoc-echo-are-use-multiline-p` to nil,
or 1, one can still get the full set of lines by via M-x
eldoc-doc-buffer.

Later on, we will probably want to review and explore other outlets
other than the echo area and this auxiliary buffer for displaying the
information collected and coordinated by our chose
eldoc-documentation-strategy.

But that is matter for another bug report...

João

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[Eli Zaretskii]

> From: João Távora <joaotavora@gmail.com>
> Date: Sat, 29 Aug 2020 16:36:51 +0100
> 
> I've recently moved `flymake-eldoc-function` from first to the last spot
> in the list.  If I hadn't done that, the default behaviour when writing
> a sexp such as, say:
> 
>    (my-dear-function [point here])
> 
> would be to foremost greet the user with the Flymake error message about
> insufficient args being supplied to the `my-dear-function` call about to
> be written, rather than what those args are supposed to be.  Obviously
> this defeats the purpose of having ElDoc serve as a code-writing aid.
> 
> But now take this other situation and suppose there is an error in the
> "foo" where point is on:
> 
>    (my-dear-function 'fo[point here]o 42 'bar)
> 
> Having the sexp written with a suitable number of arguments but with
> some Flymake mistake will now fail to notify us of those mistakes, since
> the signature information takes priority.  This is similar, if not the
> same, as the aforementioned bug#32243.
> 
> Earlier, there was no obvious solution to this, especially if one
> insisted on using only a one-line-tall echo area at the maximum.  Now,
> after Mark Oteiza's introduction of `eldoc-documentation-functions`,
> there are ways to configure suitable behaviours.  In particular there is
> `eldoc-documentation-strategy` (formerly `eldoc-documentation-function`,
> singular), which tells how to coordinate ElDoc information from multiple
> sources.
> 
> This variable's value defaults to `eldoc-documentation-default`
> globally. I suggest we default it to `eldoc-documentation-compose` in
> Elisp mode, so the three functions occupying
> `eldoc-documentation-functions` can be in play at the same time.  This
> is because the information conveyed by them can be generally be useful
> at the same time.

How will the proposed change modify the behavior in the use case with
which you started this message?

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[João Távora]

Eli Zaretskii <eliz@gnu.org> writes:

> How will the proposed change modify the behavior in the use case with
> which you started this message?

In the use case I started this message with, the user has enabled
Flymake.  Instead of seeing only the function signature in the echo area
-- and being denied the presumed Flymake diagnostic "beneath it" -- this
user would now see both items of information in two lines of said echo
area.

A similar reasoning applies to other situations with two competing
different sources of context or "at point" documentation.  Currently,
even without Flymake there are function signatures and variable
docstrings, for example.

João

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[Eli Zaretskii]

> From: João Távora <joaotavora@gmail.com>
> Cc: 43103@debbugs.gnu.org,  larsi@gnus.org,  monnier@iro.umontreal.ca
> Date: Sat, 29 Aug 2020 17:07:48 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > How will the proposed change modify the behavior in the use case with
> > which you started this message?
> 
> In the use case I started this message with, the user has enabled
> Flymake.  Instead of seeing only the function signature in the echo area
> -- and being denied the presumed Flymake diagnostic "beneath it" -- this
> user would now see both items of information in two lines of said echo
> area.

So the user will see both the function's signature and the Flymake's
error message because the call's syntax is not yet complete?  That
sounds sub-optimal, doesn't it? why show an error message when the
user is clearly still typing the code?

> A similar reasoning applies to other situations with two competing
> different sources of context or "at point" documentation.  Currently,
> even without Flymake there are function signatures and variable
> docstrings, for example.

I'm talking specifically about Flymake, because it reports errors,
not just any information.

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[João Távora]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: João Távora <joaotavora@gmail.com>
>> Cc: 43103@debbugs.gnu.org,  larsi@gnus.org,  monnier@iro.umontreal.ca
>> Date: Sat, 29 Aug 2020 17:07:48 +0100
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> > How will the proposed change modify the behavior in the use case with
>> > which you started this message?
>> 
>> In the use case I started this message with, the user has enabled
>> Flymake.  Instead of seeing only the function signature in the echo area
>> -- and being denied the presumed Flymake diagnostic "beneath it" -- this
>> user would now see both items of information in two lines of said echo
>> area.
>
> So the user will see both the function's signature and the Flymake's
> error message because the call's syntax is not yet complete?  That
> sounds sub-optimal, doesn't it? why show an error message when the
> user is clearly still typing the code?

For me it's really not clear.  What if the user changed the function
signature elsewhere or the compilation the error check is based on might
is looking at a different version of the library that has another
protocol.  When point is on those invalid calls, it's quite useful to be
alerted to both the error and the signature.  Also note this happens in
any mode that uses Flymake and provide signatures, not just Elisp.

So, situations where the user is typing function calls from scratch do
happen, but they're not necessarily the majority -- it depends on the
editing work.  I will agree with you that displaying the transient error
on those situations is alarmist and not very useful, but it's better
fixed by adjusting 'flymake-no-changes-timeout' (or some other heuristic
that makes Flymake less eager) than asserting that the simultaneous
display of both pieces of information isn't useful _in general_.  It is.
In fact, I recall bug reports in Eglot that repeateadly state so.

>> A similar reasoning applies to other situations with two competing
>> different sources of context or "at point" documentation.  Currently,
>> even without Flymake there are function signatures and variable
>> docstrings, for example.
>
> I'm talking specifically about Flymake, because it reports errors,
> not just any information.

More precisely, it reports "diagnostics", which may be errors, warnings,
notes, or really any annotation about a region in your source.

Anyway, from your statement, it seems you'd be OK (or at least find less
problematic) that the two Flymake-unrelated lines:

    eldoc-idle-delay: Number of seconds of idle time to wait before printing.
    run-with-idle-timer: (SECS REPEAT FUNCTION &rest ARGS)  [SECS is boldface]

Being shown when point hovers on the second atom of the form

    (run-with-idle-timer eldoc-idle-delay nil ...)

?

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[Eli Zaretskii]

> From: João Távora <joaotavora@gmail.com>
> Cc: 43103@debbugs.gnu.org,  larsi@gnus.org,  monnier@iro.umontreal.ca
> Date: Sat, 29 Aug 2020 21:13:31 +0100
> 
> I will agree with you that displaying the transient error
> on those situations is alarmist and not very useful, but it's better
> fixed by adjusting 'flymake-no-changes-timeout'

If we are okay with a large timeout (like 1 sec at least), then maybe
it's fine.

> Anyway, from your statement, it seems you'd be OK (or at least find less
> problematic) that the two Flymake-unrelated lines:
> 
>     eldoc-idle-delay: Number of seconds of idle time to wait before printing.
>     run-with-idle-timer: (SECS REPEAT FUNCTION &rest ARGS)  [SECS is boldface]
> 
> Being shown when point hovers on the second atom of the form
> 
>     (run-with-idle-timer eldoc-idle-delay nil ...)
> 
> ?

Expect annoying users due to resizing of mini-window.

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[João Távora]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: João Távora <joaotavora@gmail.com>
>> Cc: 43103@debbugs.gnu.org,  larsi@gnus.org,  monnier@iro.umontreal.ca
>> Date: Sat, 29 Aug 2020 21:13:31 +0100
>> 
>> I will agree with you that displaying the transient error
>> on those situations is alarmist and not very useful, but it's better
>> fixed by adjusting 'flymake-no-changes-timeout'
>
> If we are okay with a large timeout (like 1 sec at least), then maybe
> it's fine.

I'm okay with a 1 sec timeout for flymake-no-changes-timeout, though
before changing that default I'd first pay attention to the feedback of
Flymake+ElDoc users (as you know, Flymake isn't on by default).

Personally, as a Flymake user, I'm not very bothered by the alarmist
messages.  They're very similar to what until very recently happened
with the "add a quote" situation (the one that
`jit-lock-antiblink-grace` fixed).  Other modes (and other editors,
IIRC) will visually annotate the transient erroneous state as the user
is typing "new code".  Though, granted, we shouldn't compare ourselves
with those inferior kind.

>> Anyway, from your statement, it seems you'd be OK (or at least find less
>> problematic) that the two Flymake-unrelated lines:
>> 
>>     eldoc-idle-delay: Number of seconds of idle time to wait before printing.
>>     run-with-idle-timer: (SECS REPEAT FUNCTION &rest ARGS)  [SECS is boldface]
>> 
>> Being shown when point hovers on the second atom of the form
>> 
>>     (run-with-idle-timer eldoc-idle-delay nil ...)
>> 
>> ?
>
> Expect annoying users due to resizing of mini-window.

Yes, and this is why I mentioned eldoc-echo-area-use-multiline-p in my
original message.  It is the current way to control this (at least
before I propose a overhaul of the ElDoc display system).

Its default and original value is `truncate-sym-name-if-fit`, which (but
for one detail) basically amounts to `t` or "yes, do use multiple
lines".  So we could

1. greet these annoyed users with this fact and tell
them to set eldoc-echo-area-use-multiline-p to nil or 1

2. set it to such a value by default in emacs-lisp-mode

3. wait for the aforementioned overhaul to somehow give us better
perspective before doing the work of this bug report (i.e. switch to
eldoc-documentation-compose in emacs-lisp-mode).

At any rate, as I wrote earlier:

- the Flymake Eldoc source is last in the list, so it will be the one
edited out if eldoc-echo-area-use-multiline-p is set to nil.  In
practice this would amount to no immediately visible change in
behaviour;

- even if eldoc-echo-area-use-multiline-p is set to nil, users can still
get to all the info collecte by ElDoc with the new
`eldoc-documentation-compose` strategy by pressing M-x eldoc-doc-buffer

Hope this clarifies things,
João

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[Dmitry Gutov]

On 30.08.2020 17:26, Eli Zaretskii wrote:
> Expect annoying users due to resizing of mini-window.

Exactly.

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[Dmitry Gutov]

On 30.08.2020 18:15, João Távora wrote:

> Its default and original value is `truncate-sym-name-if-fit`, which (but
> for one detail) basically amounts to `t` or "yes, do use multiple
> lines".  So we could

It's true, but the curious reality is that AFAIK the built-in eldoc 
functions (foremost, the Elisp one) have always used the one-line 
display, even when they could show more.

These is definite wisdom in that.

> 1. greet these annoyed users with this fact and tell
> them to set eldoc-echo-area-use-multiline-p to nil or 1
> 
> 2. set it to such a value by default in emacs-lisp-mode

Change the default in eldoc.el. Why emacs-lisp-mode?

> 3. wait for the aforementioned overhaul to somehow give us better
> perspective before doing the work of this bug report (i.e. switch to
> eldoc-documentation-compose in emacs-lisp-mode).

Or that.

> At any rate, as I wrote earlier:
> 
> - the Flymake Eldoc source is last in the list, so it will be the one
> edited out if eldoc-echo-area-use-multiline-p is set to nil.  In
> practice this would amount to no immediately visible change in
> behaviour;

One would probably prefer to see the description of the compilation 
error rather than the function signature, if they had to choose.

> - even if eldoc-echo-area-use-multiline-p is set to nil, users can still
> get to all the info collecte by ElDoc with the new
> `eldoc-documentation-compose` strategy by pressing M-x eldoc-doc-buffer

Is that the only benefit?

This command is pretty odd in its design. But if its main purpose was to 
show multiple eldoc results together, it could always use the 'compose' 
strategy itself, regardless of the value of eldoc-documentation-strategy.

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[João Távora]

Dmitry Gutov <dgutov@yandex.ru> writes:
> On 30.08.2020 18:15, João Távora wrote:

> It's true, but the curious reality is that AFAIK the built-in eldoc
> functions (foremost, the Elisp one) have always used the one-line
> display, even when they could show more.
>
> These is definite wisdom in that.

I see only signs of rudimentary intial design which predates
eldoc-...-multiline-p, composition, Flymake...

> Change the default in eldoc.el. Why emacs-lisp-mode?

See subject line.

> One would probably prefer to see the description of the compilation
> error rather than the function signature, if they had to choose.

Maybe you would, you can adjust it.  I'd rather not change more defaults
than the one suggested in the subject line.

>> - even if eldoc-echo-area-use-multiline-p is set to nil, users can still
>> get to all the info collecte by ElDoc with the new
>> `eldoc-documentation-compose` strategy by pressing M-x eldoc-doc-buffer
>
> Is that the only benefit?

No.

> This command is pretty odd in its design. But if its main purpose was
> to show multiple eldoc results together

It's similar to `help-buffer`, but also switches to the buffer when
called interactively.  I don't see anything odd in that, in Emacs terms.
The command pops a window to *eldoc ...*, a less restricted view into
the continuously composed results of ElDoc collection, the echo area
being a much more restricted outlet.  In the future, there could/should
be an arbitrary number of such outlets: windows, frames, tooltips, some
more restrictive, some less, some more interactive, some less.

This is beyond the scope of this bug, though.

João

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[Dmitry Gutov]

On 31.08.2020 11:38, João Távora wrote:

>> It's true, but the curious reality is that AFAIK the built-in eldoc
>> functions (foremost, the Elisp one) have always used the one-line
>> display, even when they could show more.
>>
>> These is definite wisdom in that.
> 
> I see only signs of rudimentary intial design which predates
> eldoc-...-multiline-p, composition, Flymake...

That doesn't mean the initial design didn't get something right.

If it didn't, this aspect would have likely changed by now.

>> Change the default in eldoc.el. Why emacs-lisp-mode?
> 
> See subject line.

Having a major mode exhibit a different behavior WRT eldoc strategy is 
bound to be confusing. E.g., why Elisp and not Python? Why not the rest?

>> One would probably prefer to see the description of the compilation
>> error rather than the function signature, if they had to choose.
> 
> Maybe you would, you can adjust it.  I'd rather not change more defaults
> than the one suggested in the subject line.

If it's for emacs-lisp-mode only, it's already not "changing the default".

>>> - even if eldoc-echo-area-use-multiline-p is set to nil, users can still
>>> get to all the info collecte by ElDoc with the new
>>> `eldoc-documentation-compose` strategy by pressing M-x eldoc-doc-buffer
>>
>> Is that the only benefit?
> 
> No.

Any others?

>> This command is pretty odd in its design. But if its main purpose was
>> to show multiple eldoc results together
> 
> It's similar to `help-buffer`, but also switches to the buffer when
> called interactively.  I don't see anything odd in that, in Emacs terms.

It's odd to use basically the same presentation for the buffer as the 
one for the echo area. The echo area is smaller in size, and has 
undesirable side-effects when its contents change height. A buffer 
doesn't have these kind of constraints.

And if we were to differentiate the buffer's presentation (for instance, 
by binding eldoc-echo-area-use-multiline-p to t inside 
eldoc-print-current-symbol-info's interactive clause), we might as well 
use a different strategy for it, too.

> The command pops a window to *eldoc ...*, a less restricted view into
> the continuously composed results of ElDoc collection, the echo area
> being a much more restricted outlet.  In the future, there could/should
> be an arbitrary number of such outlets: windows, frames, tooltips, some
> more restrictive, some less, some more interactive, some less.

Some of these have different constraints, too.

> This is beyond the scope of this bug, though.

You brought it up.

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[João Távora]

Dmitry Gutov <dgutov@yandex.ru> writes:

>>> These is definite wisdom in that.
>> I see only signs of rudimentary intial design which predates
>> eldoc-...-multiline-p, composition, Flymake...
> That doesn't mean the initial design didn't get something right.
> If it didn't, this aspect would have likely changed by now.

It couldn't change because there weren't the tools for it to change.
There are now.  I don't know where your evolutionary argument is headed
but it's not very interesting, in my opinion..

>>> Change the default in eldoc.el. Why emacs-lisp-mode?
>> See subject line.
>
> Having a major mode exhibit a different behavior WRT eldoc strategy is
> bound to be confusing. E.g., why Elisp and not Python? Why not the
> rest?

I think people are used to their major modes working in a certain way,
and changes to that way should come about incrementally.  Other modes
may have ElDoc sources that don't lend themselves to this particular
composition strategy.

>>> One would probably prefer to see the description of the compilation
>>> error rather than the function signature, if they had to choose.
>> Maybe you would, you can adjust it.  I'd rather not change more
>> defaults
>> than the one suggested in the subject line.
>
> If it's for emacs-lisp-mode only, it's already not "changing the default".

I don't care what you call it.  I proposed to change the "Emacs -Q
behaviour" of emacs-lisp-mode first.

>>>> - even if eldoc-echo-area-use-multiline-p is set to nil, users can still
>>>> get to all the info collecte by ElDoc with the new
>>>> `eldoc-documentation-compose` strategy by pressing M-x eldoc-doc-buffer
>>>
>>> Is that the only benefit?
>> No.
>
> Any others?

For example, it can be used to have ElDoc information permanently
visible in another frame.

>>> This command is pretty odd in its design. But if its main purpose was
>>> to show multiple eldoc results together
>> It's similar to `help-buffer`, but also switches to the buffer when
>> called interactively.  I don't see anything odd in that, in Emacs terms.
>
> It's odd to use basically the same presentation for the buffer as the
> one for the echo area.

They don't use the same presentation.  I don't understand the rest of
your reasoning,  sorry.

If you want another example in Emacs, here's one: in Flymake (and in
Flycheck) there are diagnostics collected from multiple backends.  This
information is presented in a variety of ways: in-source annotations,
tiny mode-line construct, echo area, and a constantly updated separate
buffer listing all the diagnostics in tabular form.  The ElDoc buffer is
similar to the latter.

>> This is beyond the scope of this bug, though.
> You brought it up.

No.  You asserted the design is odd, I explained how it's not.

João

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[Dmitry Gutov]

On 31.08.2020 23:25, João Távora wrote:

>>>> These is definite wisdom in that.
>>> I see only signs of rudimentary intial design which predates
>>> eldoc-...-multiline-p, composition, Flymake...
>> That doesn't mean the initial design didn't get something right.
>> If it didn't, this aspect would have likely changed by now.
> 
> It couldn't change because there weren't the tools for it to change.
> There are now.

I don't think so. It still uses the echo area.

>> Having a major mode exhibit a different behavior WRT eldoc strategy is
>> bound to be confusing. E.g., why Elisp and not Python? Why not the
>> rest?
> 
> I think people are used to their major modes working in a certain way,
> and changes to that way should come about incrementally.

Many of us here program in multiple programming languages.

Having major modes exhibit different behaviors where they don't have to 
is jarring.

> Other modes
> may have ElDoc sources that don't lend themselves to this particular
> composition strategy.

They don't have multiple documentation sources? One from major mode, 
another from Flymake, at least.

>>>>> - even if eldoc-echo-area-use-multiline-p is set to nil, users can still
>>>>> get to all the info collecte by ElDoc with the new
>>>>> `eldoc-documentation-compose` strategy by pressing M-x eldoc-doc-buffer
>>>>
>>>> Is that the only benefit?
>>> No.
>>
>> Any others?
> 
> For example, it can be used to have ElDoc information permanently
> visible in another frame.

In the default configuration?

You're proposing to change the default configuration.

To clarify, I was asking whether this was the only benefit of changing 
the strategy if we also set eldoc-echo-area-use-multiline-p to nil.

>>>> This command is pretty odd in its design. But if its main purpose was
>>>> to show multiple eldoc results together
>>> It's similar to `help-buffer`, but also switches to the buffer when
>>> called interactively.  I don't see anything odd in that, in Emacs terms.
>>
>> It's odd to use basically the same presentation for the buffer as the
>> one for the echo area.
> 
> They don't use the same presentation.

Same text contents.

> If you want another example in Emacs, here's one: in Flymake (and in
> Flycheck) there are diagnostics collected from multiple backends.  This
> information is presented in a variety of ways: in-source annotations,
> tiny mode-line construct, echo area, and a constantly updated separate
> buffer listing all the diagnostics in tabular form.  The ElDoc buffer is
> similar to the latter.

I'm not saying the Eldoc buffer command is unnecessary. I'm saying the 
current implementation and semantics are weird.

One particular way it's unfortunate, is I actually *would* like a 
generic "show documentation" feature with an existing key binding. Shame 
it doesn't really work for that purpose.

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[João Távora]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 31.08.2020 23:25, João Távora wrote:
>
>>>>> These is definite wisdom in that.
>>>> I see only signs of rudimentary intial design which predates
>>>> eldoc-...-multiline-p, composition, Flymake...
>>> That doesn't mean the initial design didn't get something right.
>>> If it didn't, this aspect would have likely changed by now.
>> It couldn't change because there weren't the tools for it to change.
>> There are now.
>
> I don't think so. It still uses the echo area.

The echo area is not one of the new tools.

>>> Having a major mode exhibit a different behavior WRT eldoc strategy is
>>> bound to be confusing. E.g., why Elisp and not Python? Why not the
>>> rest?
>> I think people are used to their major modes working in a certain
>> way,
>> and changes to that way should come about incrementally.
>
> Many of us here program in multiple programming languages.
>
> Having major modes exhibit different behaviors where they don't have
> to is jarring.

Shall I enumerate variables that are set differently per major-mode?
Your argument is very odd: every major mode has different behaviours,
including for example the shape and form of the elements of
eldoc-documentation-functions.

> They don't have multiple documentation sources? One from major mode,
> another from Flymake, at least.

But you don't know in general the form of each of those, or if there may
be more, or other characteristics.

>>>>>> - even if eldoc-echo-area-use-multiline-p is set to nil, users can still
>>>>>> get to all the info collecte by ElDoc with the new
>>>>>> `eldoc-documentation-compose` strategy by pressing M-x eldoc-doc-buffer
>>>>>
>>>>> Is that the only benefit?
>>>> No.
>>>
>>> Any others?
>> For example, it can be used to have ElDoc information permanently
>> visible in another frame.
>
> In the default configuration?

Yes.

> You're proposing to change the default configuration.
>
> To clarify, I was asking whether this was the only benefit of changing
> the strategy if we also set eldoc-echo-area-use-multiline-p to nil.

Hopefully you understand now.  I've told you all I know.

> One particular way it's unfortunate, is I actually *would* like a
> generic "show documentation" feature with an existing key
> binding. Shame it doesn't really work for that purpose.

Try M-x eldoc and global-set-key and tell us what's missing. I don't
know how this relates to the ElDoc buffer or its purported "weirdness".

João

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[Dmitry Gutov]

On 01.09.2020 00:12, João Távora wrote:
> Dmitry Gutov <dgutov@yandex.ru> writes:
> 
>> On 31.08.2020 23:25, João Távora wrote:
>>
>>>>>> These is definite wisdom in that.
>>>>> I see only signs of rudimentary intial design which predates
>>>>> eldoc-...-multiline-p, composition, Flymake...
>>>> That doesn't mean the initial design didn't get something right.
>>>> If it didn't, this aspect would have likely changed by now.
>>> It couldn't change because there weren't the tools for it to change.
>>> There are now.
>>
>> I don't think so. It still uses the echo area.
> 
> The echo area is not one of the new tools.

You're making my point here.

>> Many of us here program in multiple programming languages.
>>
>> Having major modes exhibit different behaviors where they don't have
>> to is jarring.
> 
> Shall I enumerate variables that are set differently per major-mode?
> Your argument is very odd: every major mode has different behaviours,
> including for example the shape and form of the elements of
> eldoc-documentation-functions.

One reason we create minor modes, unified bindings, and so on, is to 
make the behavior in general more predictable and uniform. So that one 
doesn't need to re-learn Emacs entirely when editing a file in a 
different format.

>> They don't have multiple documentation sources? One from major mode,
>> another from Flymake, at least.
> 
> But you don't know in general the form of each of those, or if there may
> be more, or other characteristics.

That looks like a drawback of your latest redesign (which I pointed out 
previously, but who cares about that). The strategy is a global 
variable, and it's user-customizable.

And yet, somehow, now you're getting worried that different strategies 
might only suit some major modes?

>>>>>>> - even if eldoc-echo-area-use-multiline-p is set to nil, users can still
>>>>>>> get to all the info collecte by ElDoc with the new
>>>>>>> `eldoc-documentation-compose` strategy by pressing M-x eldoc-doc-buffer
>>>>>>
>>>>>> Is that the only benefit?
>>>>> No.
>>>>
>>>> Any others?
>>> For example, it can be used to have ElDoc information permanently
>>> visible in another frame.
>>
>> In the default configuration?
> 
> Yes.

The command. Not the strategy?

>> You're proposing to change the default configuration.
>>
>> To clarify, I was asking whether this was the only benefit of changing
>> the strategy if we also set eldoc-echo-area-use-multiline-p to nil.
> 
> Hopefully you understand now.  I've told you all I know.

You seem to have been answering a different question.

>> One particular way it's unfortunate, is I actually *would* like a
>> generic "show documentation" feature with an existing key
>> binding. Shame it doesn't really work for that purpose.
> 
> Try M-x eldoc and global-set-key and tell us what's missing.

Already told you. I'm not sure how many different ways I can explain 
things, if you keep snipping those explanations out.

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[João Távora]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 01.09.2020 00:12, João Távora wrote:
>> Dmitry Gutov <dgutov@yandex.ru> writes:
>> 
>>> On 31.08.2020 23:25, João Távora wrote:
>>>
>>>>>>> These is definite wisdom in that.
>>>>>> I see only signs of rudimentary intial design which predates
>>>>>> eldoc-...-multiline-p, composition, Flymake...
>>>>> That doesn't mean the initial design didn't get something right.
>>>>> If it didn't, this aspect would have likely changed by now.
>>>> It couldn't change because there weren't the tools for it to change.
>>>> There are now.
>>> I don't think so. It still uses the echo area.
>> The echo area is not one of the new tools.
> You're making my point here.

If you say so, I really have no clue what your point is.  The echo area
has been there from ElDoc's first design, it is not one of the new tools
that ElDoc offers now.

For your benefit, and to wrap up this exchange, here's a summary of what
I propose: In Elisp mode, I've experimented with the
`eldoc-documentation-compose` strategy and I like the results: it's
useful to have Elisp function signatures, Elisp variable documentation
and Elisp diagnostics displayed somewhere, constantly updated.  I think
other people would like these things, hence my proposal.  I don't mind
the echo area jumping in height one or two lines once in a while, but if
others do, there are tools to control it, which we can leverage to good
effect.  That's it.

>>> One particular way it's unfortunate, is I actually *would* like a
>>> generic "show documentation" feature with an existing key
>>> binding. Shame it doesn't really work for that purpose.
>> Try M-x eldoc and global-set-key and tell us what's missing.
>
> Already told you. I'm not sure how many different ways I can explain
> things, if you keep snipping those explanations out.

You said you wished for a command to "show documentation" and I pointed
you to M-x eldoc, a new command which seems to do what you want, and
that you might not be aware of since it wasn't discussed.  If you don't
wish to pursue this suggestion, fine.  I am in no obligation to waste my
time replying to every new off-topic point you bring up, I do so only
where I think I can add value.  Bickering with you is not one of those
things.

João

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[Dmitry Gutov]

On 01.09.2020 01:50, João Távora wrote:

> The echo area
> has been there from ElDoc's first design, it is not one of the new tools
> that ElDoc offers now.

My point is -- as is well-known -- the echo area has a long-standing 
problem. If the message is multiline, the windows will jump. Since the 
echo area is still the main means of conveying Eldoc notifications, 
changing Eldoc behavior to multiline messages is problematic.

> For your benefit, and to wrap up this exchange, here's a summary of what
> I propose: In Elisp mode, I've experimented with the
> `eldoc-documentation-compose` strategy and I like the results: it's
> useful to have Elisp function signatures, Elisp variable documentation
> and Elisp diagnostics displayed somewhere, constantly updated.

Indeed.

> I think
> other people would like these things, hence my proposal.  I don't mind
> the echo area jumping in height one or two lines once in a while,

I mind. Unfortunately.

> but if
> others do, there are tools to control it, which we can leverage to good
> effect.  That's it.

What tools?

>>>> One particular way it's unfortunate, is I actually *would* like a
>>>> generic "show documentation" feature with an existing key
>>>> binding. Shame it doesn't really work for that purpose.
>>> Try M-x eldoc and global-set-key and tell us what's missing.
>>
>> Already told you. I'm not sure how many different ways I can explain
>> things, if you keep snipping those explanations out.
> 
> You said you wished for a command to "show documentation" and I pointed
> you to M-x eldoc, a new command which seems to do what you want, and
> that you might not be aware of since it wasn't discussed.

And I told you its semantics are broken.

Showing the text intended to be displayed in the echo area (one line, 
usually; maybe a few) in a full-size window is ridiculous.

> If you don't
> wish to pursue this suggestion, fine.  I am in no obligation to waste my
> time replying to every new off-topic point you bring up, I do so only
> where I think I can add value.  Bickering with you is not one of those
> things.

If you try actually reading what I wrote, you might find some actionable 
suggestions there.

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[João Távora]

Dmitry Gutov <dgutov@yandex.ru> writes:

>> other people would like these things, hence my proposal.  I don't mind
>> the echo area jumping in height one or two lines once in a while,
>
> I mind. Unfortunately.
>
>> but if
>> others do, there are tools to control it, which we can leverage to good
>> effect.  That's it.
>
> What tools?

eldoc-echo-area-use-multiline-p, as I mentiond at least 3 times in this
thread.

>> You said you wished for a command to "show documentation" and I
>> pointed
>> you to M-x eldoc, a new command which seems to do what you want, and
>> that you might not be aware of since it wasn't discussed.

> And I told you its semantics are broken.

I think you are still confusing M-x eldoc and M-x eldoc-doc-buffer,
which are two different commands.  For the record, both commands and
surrounding functionality can and probably will be improved.

> Showing the text intended to be displayed in the echo area (one line,
> usually; maybe a few) in a full-size window is ridiculous.

This is not true in the generality of ElDoc usage, of course: LSP users
are confronted with very verbose at-point documentation.  And a window
and buffer in Emacs are not the same thing, something I assumed you
knew.

>> If you don't
>> wish to pursue this suggestion, fine.  I am in no obligation to waste my
>> time replying to every new off-topic point you bring up, I do so only
>> where I think I can add value.  Bickering with you is not one of those
>> things.
>
> If you try actually reading what I wrote, you might find some
> actionable suggestions there.

I told you at least once that it's rude to accuse other people of not
reading your emails.  It's a lie and a disrespect for the precious time
they invest in reading them and replying to them as they see fit.  Not
to mention wholly unproductive.  Because I don't have time for this, I'm
putting you in my ignore list, joined by very few, if anyone.  So now
you'll _know_ that I won't be reading what you write, and the reason why
I won't.

João

bug#43103: 28.0.50; Default ElDoc composition strategy in Elisp mode (eldoc-documentation-strategy)

[Dmitry Gutov]

On 01.09.2020 14:11, João Távora wrote:
> Dmitry Gutov <dgutov@yandex.ru> writes:
> 
>>> other people would like these things, hence my proposal.  I don't mind
>>> the echo area jumping in height one or two lines once in a while,
>>
>> I mind. Unfortunately.
>>
>>> but if
>>> others do, there are tools to control it, which we can leverage to good
>>> effect.  That's it.
>>
>> What tools?
> 
> eldoc-echo-area-use-multiline-p, as I mentiond at least 3 times in this
> thread.

In my very first message, I asked what's the point of changing the 
strategy if we set this variable to nil.

Please pay attention.

>>> You said you wished for a command to "show documentation" and I
>>> pointed
>>> you to M-x eldoc, a new command which seems to do what you want, and
>>> that you might not be aware of since it wasn't discussed.
> 
>> And I told you its semantics are broken.
> 
> I think you are still confusing M-x eldoc and M-x eldoc-doc-buffer,
> which are two different commands.

Ah, that very well may be.

But if so, your advice wasn't great. M-x eldoc (if it only uses the echo 
area) is for showing small hints, not for showing documentation.

> For the record, both commands and
> surrounding functionality can and probably will be improved.

Indeed.

>> Showing the text intended to be displayed in the echo area (one line,
>> usually; maybe a few) in a full-size window is ridiculous.
> 
> This is not true in the generality of ElDoc usage, of course: LSP users
> are confronted with very verbose at-point documentation.

And very verbose eldoc messages, then?

> And a window
> and buffer in Emacs are not the same thing, something I assumed you
> knew.

Your point being?

The said buffer is subsequently displayed in a normal window. Not in a 
"mini" window akin to minibuffer.

>>> If you don't
>>> wish to pursue this suggestion, fine.  I am in no obligation to waste my
>>> time replying to every new off-topic point you bring up, I do so only
>>> where I think I can add value.  Bickering with you is not one of those
>>> things.
>>
>> If you try actually reading what I wrote, you might find some
>> actionable suggestions there.
> 
> I told you at least once that it's rude to accuse other people of not
> reading your emails.  It's a lie and a disrespect for the precious time
> they invest in reading them and replying to them as they see fit.

And it's not rude to snip off a third of the message your are replying 
to without any good reason?

> Not
> to mention wholly unproductive.  Because I don't have time for this, I'm
> putting you in my ignore list, joined by very few, if anyone.  So now
> you'll _know_ that I won't be reading what you write, and the reason why
> I won't.

It must be fun to see (or not see) one's commits surprisingly reverted 
because of a message you chose not to read.