GNU bug report logs - #77169
[PATCH] New Eldoc function `help-at-pt-eldoc-function'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 77169 in the body.
You can then email your comments to 77169 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Daniel Mendler <mail <at> daniel-mendler.de>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] New Eldoc function `help-at-pt-eldoc-function'
Date: Sat, 22 Mar 2025 10:40:18 +0100

[Message part 1 (text/plain, inline)]

Tags: patch

This patch proposes the addition of a new Eldoc function
`help-at-pt-eldoc-function'.

Show help-at-pt string via Eldoc as an alternative to the
`help-at-pt-display-when-idle' timer.  The help-at-pt timer competes
with Eldoc for the echo area, such that using both does not work well.
The new `help-at-pt-eldoc-function' is meant to be added to
`eldoc-documentation-functions'.

[0001-New-Eldoc-function-help-at-pt-eldoc-function.patch (text/patch, attachment)]

Message #8 received at 77169 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Daniel Mendler <mail <at> daniel-mendler.de>
Cc: 77169 <at> debbugs.gnu.org
Subject: Re: bug#77169: [PATCH] New Eldoc function `help-at-pt-eldoc-function'
Date: Sat, 22 Mar 2025 13:14:06 +0200

> Date: Sat, 22 Mar 2025 10:40:18 +0100
> From:  Daniel Mendler via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> This patch proposes the addition of a new Eldoc function
> `help-at-pt-eldoc-function'.
> 
> Show help-at-pt string via Eldoc as an alternative to the
> `help-at-pt-display-when-idle' timer.  The help-at-pt timer competes
> with Eldoc for the echo area, such that using both does not work well.
> The new `help-at-pt-eldoc-function' is meant to be added to
> `eldoc-documentation-functions'.

Thanks, but please also reflect this feature in the doc string of
help-at-pt-display-when-idle and in the Emacs user manual (where that
option is described).

Also, shouldn't we have a user option to turn this on in ElDoc?

And what about a NEWS entry?

Message #11 received at 77169 <at> debbugs.gnu.org (full text, mbox):

From: Daniel Mendler <mail <at> daniel-mendler.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 77169 <at> debbugs.gnu.org
Subject: Re: bug#77169: [PATCH] New Eldoc function `help-at-pt-eldoc-function'
Date: Sat, 22 Mar 2025 12:29:13 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Date: Sat, 22 Mar 2025 10:40:18 +0100
>> From:  Daniel Mendler via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
>> 
>> This patch proposes the addition of a new Eldoc function
>> `help-at-pt-eldoc-function'.
>> 
>> Show help-at-pt string via Eldoc as an alternative to the
>> `help-at-pt-display-when-idle' timer.  The help-at-pt timer competes
>> with Eldoc for the echo area, such that using both does not work well.
>> The new `help-at-pt-eldoc-function' is meant to be added to
>> `eldoc-documentation-functions'.

Eli, thank you for looking at the patch so quickly.

> Thanks, but please also reflect this feature in the doc string of
> help-at-pt-display-when-idle and in the Emacs user manual (where that
> option is described).

The question is if `help-at-pt-display-when-idle' should be marked
obsolete in favor of the Eldoc mechanism to avoid conflicts. Eldoc is
even preloaded these days, so the de-facto standard for documentation at
point.

> Also, shouldn't we have a user option to turn this on in ElDoc?

Not sure if we need an option given that it is easy to add the function
to the list, or remove it, if the function is enabled by default.

(add-hook 'eldoc-documentation-functions #'help-at-pt-eldoc-function)
(remove-hook 'eldoc-documentation-functions #'help-at-pt-eldoc-function)

> And what about a NEWS entry?

I will add one.

Daniel

Message #14 received at 77169 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Daniel Mendler <mail <at> daniel-mendler.de>
Cc: 77169 <at> debbugs.gnu.org
Subject: Re: bug#77169: [PATCH] New Eldoc function `help-at-pt-eldoc-function'
Date: Sat, 22 Mar 2025 14:46:26 +0200

> From: Daniel Mendler <mail <at> daniel-mendler.de>
> Cc: 77169 <at> debbugs.gnu.org
> Date: Sat, 22 Mar 2025 12:29:13 +0100
> 
> > Thanks, but please also reflect this feature in the doc string of
> > help-at-pt-display-when-idle and in the Emacs user manual (where that
> > option is described).
> 
> The question is if `help-at-pt-display-when-idle' should be marked
> obsolete in favor of the Eldoc mechanism to avoid conflicts. Eldoc is
> even preloaded these days, so the de-facto standard for documentation at
> point.

Users can still disable ElDoc, and if they do, perhaps they would like
to have help-at-pt-display-when-idle.

We could start the process of obsoleting help-at-pt-display-when-idle,
if we think it should be superseded by ElDoc, but that process takes
time, and in the meantime we should assume people are still using
help-at-pt-display-when-idle and need to be aware of the replacement,
and vice versa.

> > Also, shouldn't we have a user option to turn this on in ElDoc?
> 
> Not sure if we need an option given that it is easy to add the function
> to the list, or remove it, if the function is enabled by default.

It might be easy fore you and me, but not for users who are not Lisp
programmers.

Thanks.

Message #17 received at 77169 <at> debbugs.gnu.org (full text, mbox):

From: Daniel Mendler <mail <at> daniel-mendler.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 77169 <at> debbugs.gnu.org
Subject: Re: bug#77169: [PATCH] New Eldoc function `help-at-pt-eldoc-function'
Date: Sat, 22 Mar 2025 21:56:27 +0100

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Daniel Mendler <mail <at> daniel-mendler.de>
>> Cc: 77169 <at> debbugs.gnu.org
>> Date: Sat, 22 Mar 2025 12:29:13 +0100
>> 
>> > Thanks, but please also reflect this feature in the doc string of
>> > help-at-pt-display-when-idle and in the Emacs user manual (where that
>> > option is described).
>> 
>> The question is if `help-at-pt-display-when-idle' should be marked
>> obsolete in favor of the Eldoc mechanism to avoid conflicts. Eldoc is
>> even preloaded these days, so the de-facto standard for documentation at
>> point.
>
> Users can still disable ElDoc, and if they do, perhaps they would like
> to have help-at-pt-display-when-idle.
>
> We could start the process of obsoleting help-at-pt-display-when-idle,
> if we think it should be superseded by ElDoc, but that process takes
> time, and in the meantime we should assume people are still using
> help-at-pt-display-when-idle and need to be aware of the replacement,
> and vice versa.

Agree.

>> > Also, shouldn't we have a user option to turn this on in ElDoc?
>> 
>> Not sure if we need an option given that it is easy to add the function
>> to the list, or remove it, if the function is enabled by default.
>
> It might be easy fore you and me, but not for users who are not Lisp
> programmers.

Okay. I have attached an updated version of the patch to this mail. I
have added a customization option (off by default) and a NEWS entry.

Daniel

[0001-New-Eldoc-function-eldoc-help-at-pt-function.patch (text/x-diff, attachment)]

Message #20 received at 77169 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Daniel Mendler <mail <at> daniel-mendler.de>
Cc: 77169 <at> debbugs.gnu.org
Subject: Re: bug#77169: [PATCH] New Eldoc function `help-at-pt-eldoc-function'
Date: Sun, 23 Mar 2025 08:07:30 +0200

> From: Daniel Mendler <mail <at> daniel-mendler.de>
> Cc: 77169 <at> debbugs.gnu.org
> Date: Sat, 22 Mar 2025 21:56:27 +0100
> 
> >> > Also, shouldn't we have a user option to turn this on in ElDoc?
> >> 
> >> Not sure if we need an option given that it is easy to add the function
> >> to the list, or remove it, if the function is enabled by default.
> >
> > It might be easy fore you and me, but not for users who are not Lisp
> > programmers.
> 
> Okay. I have attached an updated version of the patch to this mail. I
> have added a customization option (off by default) and a NEWS entry.

Thanks.

> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -415,6 +415,11 @@ need to set it with 'setopt' for it to take an effect.  If the docstring
>  doesn't already mention 'setopt', the 'describe-variable' command will
>  now add a note about this automatically.
>  
> +---

This should be "+++", since you've updated the manuals.

> +(defcustom eldoc-help-at-pt nil
> +  "Show `help-at-pt-kbd-string' at point via Eldoc.

"If non-nil, show `help-at-pt-kbd-string' at point via Eldoc."

> +This setting is an alternative to `help-at-pt-display-when-idle'.  If
> +the variable is t, enable the `eldoc-help-at-pt-function'."

"Enable" is inaccurate, since it's enabled by default, it just doesn't
do anything when the variable is nil.  So something like

  If the value is non-nil, `eldoc-help-at-pt-function' will show
  help-at-point via Eldoc.

> -(defvar eldoc-documentation-functions nil
> +(defvar eldoc-documentation-functions (list #'eldoc-help-at-pt-function)
>    "Hook of functions that produce doc strings.
>  
>  A doc string is typically relevant if point is on a function-like
> @@ -957,6 +963,12 @@ eldoc-print-current-symbol-info
>               (setq eldoc--last-request-state token)
>               (eldoc--invoke-strategy nil))))))
>  
> +(defun eldoc-help-at-pt-function (&rest _)

I thought symbols that end in "-function" are usually variables whose
value is the function, is that not so?  So maybe call this
eldoc-show-help-at-pt instead?

> --- a/lisp/help-at-pt.el
> +++ b/lisp/help-at-pt.el
> @@ -191,7 +191,11 @@ help-at-pt-display-when-idle
>  enabling buffer local values.  It sets the actual value to nil.
>  Thus, Custom distinguishes between a nil value and other values
>  that disable the feature, which Custom identifies with `never'.
> -The default is `never'."
> +The default is `never'.
> +
> +Eldoc uses the echo area to display help at point.

I'd say "Eldoc uses the echo area to display documentation" instead,
since the conflict between help-at-pt-display-when-idle and Eldoc is
due to the use of echo-area, not because they both show help-at-pt.

Message #23 received at 77169 <at> debbugs.gnu.org (full text, mbox):

From: Daniel Mendler <mail <at> daniel-mendler.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 77169 <at> debbugs.gnu.org
Subject: Re: bug#77169: [PATCH] New Eldoc function `help-at-pt-eldoc-function'
Date: Sun, 23 Mar 2025 08:22:46 +0100

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Daniel Mendler <mail <at> daniel-mendler.de>
>> Cc: 77169 <at> debbugs.gnu.org
>> Date: Sat, 22 Mar 2025 21:56:27 +0100
>> 
>> >> > Also, shouldn't we have a user option to turn this on in ElDoc?
>> >> 
>> >> Not sure if we need an option given that it is easy to add the function
>> >> to the list, or remove it, if the function is enabled by default.
>> >
>> > It might be easy fore you and me, but not for users who are not Lisp
>> > programmers.
>> 
>> Okay. I have attached an updated version of the patch to this mail. I
>> have added a customization option (off by default) and a NEWS entry.
>
> Thanks.
>
>> --- a/etc/NEWS
>> +++ b/etc/NEWS
>> @@ -415,6 +415,11 @@ need to set it with 'setopt' for it to take an effect.  If the docstring
>>  doesn't already mention 'setopt', the 'describe-variable' command will
>>  now add a note about this automatically.
>>  
>> +---
>
> This should be "+++", since you've updated the manuals.
>
>> +(defcustom eldoc-help-at-pt nil
>> +  "Show `help-at-pt-kbd-string' at point via Eldoc.
>
> "If non-nil, show `help-at-pt-kbd-string' at point via Eldoc."
>
>> +This setting is an alternative to `help-at-pt-display-when-idle'.  If
>> +the variable is t, enable the `eldoc-help-at-pt-function'."
>
> "Enable" is inaccurate, since it's enabled by default, it just doesn't
> do anything when the variable is nil.  So something like
>
>   If the value is non-nil, `eldoc-help-at-pt-function' will show
>   help-at-point via Eldoc.
>
>> -(defvar eldoc-documentation-functions nil
>> +(defvar eldoc-documentation-functions (list #'eldoc-help-at-pt-function)
>>    "Hook of functions that produce doc strings.
>>  
>>  A doc string is typically relevant if point is on a function-like
>> @@ -957,6 +963,12 @@ eldoc-print-current-symbol-info
>>               (setq eldoc--last-request-state token)
>>               (eldoc--invoke-strategy nil))))))
>>  
>> +(defun eldoc-help-at-pt-function (&rest _)
>
> I thought symbols that end in "-function" are usually variables whose
> value is the function, is that not so?  So maybe call this
> eldoc-show-help-at-pt instead?
>
>> --- a/lisp/help-at-pt.el
>> +++ b/lisp/help-at-pt.el
>> @@ -191,7 +191,11 @@ help-at-pt-display-when-idle
>>  enabling buffer local values.  It sets the actual value to nil.
>>  Thus, Custom distinguishes between a nil value and other values
>>  that disable the feature, which Custom identifies with `never'.
>> -The default is `never'."
>> +The default is `never'.
>> +
>> +Eldoc uses the echo area to display help at point.
>
> I'd say "Eldoc uses the echo area to display documentation" instead,
> since the conflict between help-at-pt-display-when-idle and Eldoc is
> due to the use of echo-area, not because they both show help-at-pt.

Thanks. I have updated the patch accordingly. The updated patch is
attached to this mail.

Daniel

[0001-New-Eldoc-function-eldoc-show-help-at-pt.patch (text/x-diff, attachment)]

Message #26 received at 77169 <at> debbugs.gnu.org (full text, mbox):

From: Howard Melman <hmelman <at> gmail.com>
To: GNU Emacs <bug-gnu-emacs <at> gnu.org>
Cc: mail <at> daniel-mendler.de, eliz <at> gnu.org, 77169 <at> debbugs.gnu.org
Subject: Re: bug#77169: [PATCH] New Eldoc function `help-at-pt-eldoc-function'
Date: Sun, 23 Mar 2025 10:29:33 -0400

Daniel Mendler via "Bug reports for GNU Emacs, the Swiss
army knife of text editors" <bug-gnu-emacs <at> gnu.org> writes:

>>> Okay. I have attached an updated version of the patch to this mail. I
>>> have added a customization option (off by default) and a NEWS entry.

> +(defcustom eldoc-help-at-pt nil
> +  "If non-nil, sow `help-at-pt-kbd-string' at point via Eldoc.

s/sow/show/

-- 

Howard

Message #32 received at 77169 <at> debbugs.gnu.org (full text, mbox):

From: Daniel Mendler <mail <at> daniel-mendler.de>
To: Howard Melman <hmelman <at> gmail.com>
Cc: eliz <at> gnu.org, 77169 <at> debbugs.gnu.org
Subject: Re: bug#77169: [PATCH] New Eldoc function `help-at-pt-eldoc-function'
Date: Wed, 26 Mar 2025 16:19:05 +0100

[Message part 1 (text/plain, inline)]

Howard Melman <hmelman <at> gmail.com> writes:

> Daniel Mendler via "Bug reports for GNU Emacs, the Swiss
> army knife of text editors" <bug-gnu-emacs <at> gnu.org> writes:
>
>>>> Okay. I have attached an updated version of the patch to this mail. I
>>>> have added a customization option (off by default) and a NEWS entry.
>
>> +(defcustom eldoc-help-at-pt nil
>> +  "If non-nil, sow `help-at-pt-kbd-string' at point via Eldoc.
>
> s/sow/show/

Fixed. Updated patch attached to this mail.

Daniel

[0001-New-Eldoc-function-eldoc-show-help-at-pt.patch (text/x-diff, attachment)]

Message #37 received at 77169-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Daniel Mendler <mail <at> daniel-mendler.de>
Cc: 77169-done <at> debbugs.gnu.org, hmelman <at> gmail.com
Subject: Re: bug#77169: [PATCH] New Eldoc function `help-at-pt-eldoc-function'
Date: Sat, 29 Mar 2025 13:53:36 +0300

> From: Daniel Mendler <mail <at> daniel-mendler.de>
> Cc: 77169 <at> debbugs.gnu.org,  eliz <at> gnu.org
> Date: Wed, 26 Mar 2025 16:19:05 +0100
> 
> Howard Melman <hmelman <at> gmail.com> writes:
> 
> > Daniel Mendler via "Bug reports for GNU Emacs, the Swiss
> > army knife of text editors" <bug-gnu-emacs <at> gnu.org> writes:
> >
> >>>> Okay. I have attached an updated version of the patch to this mail. I
> >>>> have added a customization option (off by default) and a NEWS entry.
> >
> >> +(defcustom eldoc-help-at-pt nil
> >> +  "If non-nil, sow `help-at-pt-kbd-string' at point via Eldoc.
> >
> > s/sow/show/
> 
> Fixed. Updated patch attached to this mail.

Thanks, installed on master, and closing the bug.

Message #40 received at 77169-done <at> debbugs.gnu.org (full text, mbox):

From: Daniel Mendler <mail <at> daniel-mendler.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 77169-done <at> debbugs.gnu.org, hmelman <at> gmail.com
Subject: Re: bug#77169: [PATCH] New Eldoc function `help-at-pt-eldoc-function'
Date: Sat, 29 Mar 2025 12:27:59 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Daniel Mendler <mail <at> daniel-mendler.de>
>> Cc: 77169 <at> debbugs.gnu.org,  eliz <at> gnu.org
>> Date: Wed, 26 Mar 2025 16:19:05 +0100
>> 
>> Howard Melman <hmelman <at> gmail.com> writes:
>> 
>> > Daniel Mendler via "Bug reports for GNU Emacs, the Swiss
>> > army knife of text editors" <bug-gnu-emacs <at> gnu.org> writes:
>> >
>> >>>> Okay. I have attached an updated version of the patch to this mail. I
>> >>>> have added a customization option (off by default) and a NEWS entry.
>> >
>> >> +(defcustom eldoc-help-at-pt nil
>> >> +  "If non-nil, sow `help-at-pt-kbd-string' at point via Eldoc.
>> >
>> > s/sow/show/
>> 
>> Fixed. Updated patch attached to this mail.
>
> Thanks, installed on master, and closing the bug.

Thanks!

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.