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 856b2ccdddef883b12f110175e4d680d1ced4378..74b1076b853552d9058e83956444dc0fa9760928 100644 (file)
--- 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 6c5e3de5d136365fe84bb168fadc0875cded7245..56322a9a6c9643e870299b8c8535ac0472a3f661 100644 (file)
--- 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)))))))
 
 \f
-(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))))
+
 \f
 ;; 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 64f7b0de017de431826b3eabc59c622c998a1d52..46f1d76308dca2a6b4b5b7086a46a4ce7bf23c19 100644 (file)
--- 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"