From: Daniel Mendler <mail@daniel-mendler.de>
Date: Sat, 22 Mar 2025 09:29:45 +0000 (+0100)
Subject: New Eldoc function `eldoc-show-help-at-pt'
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=d2d580ea0b171cd8dbce29038d6832c7fc0f6556;p=emacs.git

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)

(cherry picked from commit ab71699e5f2502aff6c65dd195611cfbbe2f2255)
---

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 856b2ccddde..74b1076b853 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -647,9 +647,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/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el
index 6c5e3de5d13..56322a9a6c9 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.
@@ -400,7 +407,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
@@ -926,6 +933,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 64f7b0de017..46f1d76308d 100644
--- a/lisp/help-at-pt.el
+++ b/lisp/help-at-pt.el
@@ -187,7 +187,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"