From ab71699e5f2502aff6c65dd195611cfbbe2f2255 Mon Sep 17 00:00:00 2001
From: Daniel Mendler <mail@daniel-mendler.de>
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.  (Bug#77169)
---
 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 @@ over the active text displays the help text as a @dfn{tooltip}.
 @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 fea533d0d20..f9ee001294f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -429,6 +429,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 @@ is only skipped if the documentation needs to be truncated there."
                  (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 @@ Also store it in `eldoc-last-message' and return that value."
                       (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 @@ the docstrings eventually produced, using
              (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 @@ list of properties through Custom will set the timer, thus
 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"