Subject: Re: bug#77169: [PATCH] New Eldoc function `help-at-pt-eldoc-function'

From: Daniel Mendler <[email-masked]>
Date: Sat, 22 Mar 2025 21:56:27 +0100

Eli Zaretskii <[email-masked]> writes:

>> From: Daniel Mendler <[email-masked]>
>> Cc: [email-masked]
>> 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

>From 8a70fb1df597257ff552a171e5da53c7bde8a057 Mon Sep 17 00:00:00 2001
From: Daniel Mendler <[email-masked]>
Date: Sat, 22 Mar 2025 10:29:45 +0100
Subject: [PATCH] New Eldoc function `eldoc-help-at-pt-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 the two mechanisms do not work
well together.  Therefore when using Eldoc, the setting
`eldoc-help-at-pt' may be preferable.

* lisp/emacs-lisp/eldoc.el (eldoc-help-at-pt): New customization option.
(eldoc-help-at-pt-function): New Eldoc function.
(eldoc-documentation-functions): Register the new function.
* lisp/help-at-pt.el (help-at-pt-display-when-idle): Mention
`eldoc-help-at-pt' in the docstring.
* doc/emacs/help.texi: Document `eldoc-help-at-pt'.
* etc/NEWS: Announce the change.
---
 doc/emacs/help.texi      |  4 +++-
 etc/NEWS                 |  5 +++++
 lisp/emacs-lisp/eldoc.el | 14 +++++++++++++-
 lisp/help-at-pt.el       |  6 +++++-
 4 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 5c2eabb02d6..6ea7b5783c2 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -857,9 +857,11 @@ Help Echo
 @kindex C-h .
 @findex display-local-help
 @vindex help-at-pt-display-when-idle
+@vindex eldoc-help-at-pt
   On terminals that don't support mouse-tracking, you can display the
 help text for active buffer text at point by typing @kbd{C-h .}
 (@code{display-local-help}).  This shows the help text in the echo
 area.  To display help text automatically whenever it is available at
 point, set the variable @code{help-at-pt-display-when-idle} to
-@code{t}.
+@code{t}.  If you use Eldoc, set the variable @code{eldoc-help-at-pt}
+to @code{t} instead.
diff --git a/etc/NEWS b/etc/NEWS
index 3b14a87dd42..8b81a130c4d 100644
--- 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.
 
+---
+** New user option 'eldoc-help-at-pt' to show help at point via Eldoc.
+When enabled, display the 'help-at-pt-kbd-string' via Eldoc.  This
+setting is an alternative to 'help-at-pt-display-when-idle'.
+
 
 * Editing Changes in Emacs 31.1
 
diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 966158024dd..d510877d0b2 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -138,6 +138,12 @@ eldoc-echo-area-prefer-doc-buffer
                  (const :tag "Skip echo area if truncating" maybe))
   :version "28.1")
 
+(defcustom eldoc-help-at-pt 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'."
+  :type 'boolean)
+
 (defface eldoc-highlight-function-argument
   '((t (:inherit bold)))
   "Face used for the argument at point in a function's argument list.
@@ -410,7 +416,7 @@ eldoc-display-message-no-interference-p
                       (overlay-end show-paren--overlay)))))))
 
 
-(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 _)
+  "Show help at point via Eldoc if `eldoc-help-at-pt' is non-nil.
+Intended for `eldoc-documentation-functions' (which see)."
+  (when-let* ((help (and eldoc-help-at-pt (help-at-pt-kbd-string))))
+    (format "Help: %s" (substitute-command-keys help))))
+
 
 ;; This section only affects ElDoc output to the echo area, as in
 ;; `eldoc-display-in-echo-area'.
diff --git a/lisp/help-at-pt.el b/lisp/help-at-pt.el
index 68054016dc5..548aa864a03 100644
--- 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.  As such it
+competes with `help-at-pt-display-when-idle' for the echo area.
+If you use Eldoc, consider setting `eldoc-help-at-pt' instead."
   :group 'help-at-pt
   :type '(choice  (const :tag "Always"
 			 :format "%t\n%h"
-- 
2.47.2