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

From: Daniel Mendler <[email-masked]>
Date: Wed, 26 Mar 2025 16:19:05 +0100

Howard Melman <[email-masked]> writes:

> Daniel Mendler via "Bug reports for GNU Emacs, the Swiss
> army knife of text editors" <[email-masked]> 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

>From d675280c2ee379faa33b7c65cbcf04ac5beabc93 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-show-help-at-pt'

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-show-help-at-pt): 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 | 15 ++++++++++++++-
 lisp/help-at-pt.el       |  7 ++++++-
 4 files changed, 28 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 c8797cf74ec..4d559565011 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -427,6 +427,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 85fb6c780e2..2b5d5cc0c8d 100644
--- a/lisp/emacs-lisp/eldoc.el
+++ b/lisp/emacs-lisp/eldoc.el
@@ -138,6 +138,13 @@ eldoc-echo-area-prefer-doc-buffer
                  (const :tag "Skip echo area if truncating" maybe))
   :version "28.1")
 
+(defcustom eldoc-help-at-pt nil
+  "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 value is non-nil, `eldoc-show-help-at-pt' will show help-at-point
+via Eldoc."
+  :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 +417,7 @@ eldoc-display-message-no-interference-p
                       (overlay-end show-paren--overlay)))))))
 
 
-(defvar eldoc-documentation-functions nil
+(defvar eldoc-documentation-functions (list #'eldoc-show-help-at-pt)
   "Hook of functions that produce doc strings.
 
 A doc string is typically relevant if point is on a function-like
@@ -957,6 +964,12 @@ eldoc-print-current-symbol-info
              (setq eldoc--last-request-state token)
              (eldoc--invoke-strategy nil))))))
 
+(defun eldoc-show-help-at-pt (&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..094f2b788fe 100644
--- a/lisp/help-at-pt.el
+++ b/lisp/help-at-pt.el
@@ -191,7 +191,12 @@ 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 documentation.  As such it
+conflicts with `help-at-pt-display-when-idle' due to the use of
+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