From fb7fe56627a66010c341c3759b3fb39b500ebec1 Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Sat, 5 Apr 2025 11:35:40 +0200 Subject: [PATCH] help-at-pt.el: Clean up. --- doc/emacs/help.texi | 5 +- lisp/emacs-lisp/eldoc.el | 5 +- lisp/help-at-pt.el | 281 --------------------------------------- 3 files changed, 2 insertions(+), 289 deletions(-) diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 74b1076b853..37c21f9816d 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -646,12 +646,9 @@ 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}. If you use Eldoc, set the variable @code{eldoc-help-at-pt} -to @code{t} instead. +point, set the variable @code{eldoc-help-at-pt} to @code{t}. diff --git a/lisp/emacs-lisp/eldoc.el b/lisp/emacs-lisp/eldoc.el index 352cc6fc4fd..5b4b9f56fc9 100644 --- a/lisp/emacs-lisp/eldoc.el +++ b/lisp/emacs-lisp/eldoc.el @@ -139,10 +139,7 @@ is only skipped if the documentation needs to be truncated there." :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." + "If non-nil, show `help-at-pt-kbd-string' at point via Eldoc." :type 'boolean :version "31.1") diff --git a/lisp/help-at-pt.el b/lisp/help-at-pt.el index 46f1d76308d..e95e8b0ac2a 100644 --- a/lisp/help-at-pt.el +++ b/lisp/help-at-pt.el @@ -31,17 +31,6 @@ ;; either on demand, using the command `display-local-help', or ;; automatically after a suitable idle time, through the customizable ;; variable `help-at-pt-display-when-idle'. -;; -;; You can get a more global overview of the local help available in -;; the buffer, using the commands `scan-buf-next-region' and -;; `scan-buf-previous-region', which move to the start of the next or -;; previous region with available local help and print the help found -;; there. -;; -;; Suggested key bindings: -;; -;; (keymap-global-set "C-" #'scan-buf-next-region) -;; (keymap-global-set "C-M-" #'scan-buf-previous-region) ;;; Code: @@ -81,9 +70,6 @@ If this produces no string either, return nil." (echo (help-at-pt-string))) (if (and kbd (not (eq kbd t))) kbd echo))) -(declare-function widget-describe "wid-edit" (&optional widget-or-pos)) -(declare-function widget-at "wid-edit" (&optional pos)) - ;;;###autoload (defun display-local-help (&optional inhibit-warning _) "Display `help-echo' text at point. @@ -109,273 +95,6 @@ there is no help property at point. (tooltip-show (substitute-quotes help)) (unless inhibit-warning (message "No local help at point"))))) -(defvar help-at-pt-timer nil - "Non-nil means that a timer is set that checks for local help. -If non-nil, this is the value returned by the call of -`run-with-idle-timer' that set that timer. This variable is used -internally to enable `help-at-pt-display-when-idle'. Do not set it -yourself.") - -(defcustom help-at-pt-timer-delay 1 - "Delay before displaying local help. -This is used if `help-at-pt-display-when-idle' is enabled. -The value may be an integer or floating point number. - -If a timer is already active, there are two ways to make the new -value take effect immediately. After setting the value, you can -first call `help-at-pt-cancel-timer' and then set a new timer -with `help-at-pt-set-timer'. Alternatively, you can set this -variable through Custom. This will not set a timer if none is -active, but if one is already active, Custom will make it use the -new value." - :group 'help-at-pt - :type 'number - :initialize 'custom-initialize-default - :set (lambda (variable value) - (set-default variable value) - (and (boundp 'help-at-pt-timer) - help-at-pt-timer - (timer-set-idle-time help-at-pt-timer value t)))) - -;;;###autoload -(defun help-at-pt-cancel-timer () - "Cancel any timer set by `help-at-pt-set-timer'. -This disables `help-at-pt-display-when-idle'." - (interactive) - (let ((inhibit-quit t)) - (when help-at-pt-timer - (cancel-timer help-at-pt-timer) - (setq help-at-pt-timer nil)))) - -;;;###autoload -(defun help-at-pt-set-timer () - "Enable `help-at-pt-display-when-idle'. -This is done by setting a timer, if none is currently active." - (interactive) - (unless help-at-pt-timer - (setq help-at-pt-timer - (run-with-idle-timer - help-at-pt-timer-delay t #'help-at-pt-maybe-display)))) - -;;;###autoload -(defcustom help-at-pt-display-when-idle 'never - "Automatically show local help on point-over. -If the value is t, the string obtained from any `kbd-help' or -`help-echo' property at point is automatically printed in the -echo area, if nothing else is already displayed there, or after a -quit. If both `kbd-help' and `help-echo' produce help strings, -`kbd-help' is used. If the value is a list, the help only gets -printed if there is a text or overlay property at point that is -included in this list. Suggested properties are `keymap', -`local-map', `button' and `kbd-help'. Any value other than t or -a non-empty list disables the feature. - -The text printed from the `help-echo' property is often only -relevant when using the mouse. The presence of a `kbd-help' -property guarantees that non mouse specific help is available. - -This variable only takes effect after a call to -`help-at-pt-set-timer'. The help gets printed after Emacs has -been idle for `help-at-pt-timer-delay' seconds. You can call -`help-at-pt-cancel-timer' to cancel the timer set by, and the -effect of, `help-at-pt-set-timer'. - -When this variable is set through Custom, `help-at-pt-set-timer' -is called automatically, unless the value is `never', in which -case `help-at-pt-cancel-timer' is called. Specifying an empty -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'. - -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" - :doc - "This choice can get noisy. -The text printed from the `help-echo' property is often only -relevant when using the mouse. If you mind about too many -messages getting printed in the echo area, use \"In certain -situations\". See the documentation there for more information." - t) - (repeat :tag "In certain situations" - ;; unless we specify 0 offset the doc string - ;; for this choice gets indented very - ;; differently than for the other two - ;; choices, when "More" is selected. - :offset 0 - :format "%{%t%}:\n%v%i\n%h" - :doc - "This choice lets you specify a list of \ -text properties. -Presence of any of these properties will trigger display of -available local help on point-over. -If you use this alternative through Custom without listing any -properties, a timer will be set anyway. This will enable buffer -local values. Use \"Never\" if you do not want a timer to be set. - -Suggested properties: -The `keymap' and `local-map' properties change keybindings in -parts of the buffer. Some of these keymaps are mode independent -and are not mentioned in the mode documentation. Hence, the help -text is likely to be useful. -Specifying `button' is relevant in Custom and similar buffers. -In these buffers, most, but not all, of the text shown this way is -available by default when using tab, but not on regular point-over. -The presence of a `kbd-help' property guarantees that non mouse -specific help is available." - :value (keymap local-map button kbd-help) - symbol) - (other :tag "Never" - :format "%t\n%h" - :doc - "This choice normally disables buffer local values. -If you choose this value through Custom and a timer checking for -local help is currently active, it will be canceled. No new -timer will be set. Call `help-at-pt-set-timer' after choosing -this option, or use \"In certain situations\" and specify no text -properties, to enable buffer local values." - never)) - :initialize 'custom-initialize-default - :set (lambda (variable value) - (set-default variable value) - (if (eq value 'never) - (help-at-pt-cancel-timer) - (help-at-pt-set-timer))) - :set-after '(help-at-pt-timer-delay) - :require 'help-at-pt) - -;; Function for use in `help-at-pt-set-timer'. -(defun help-at-pt-maybe-display () - (and (or (eq help-at-pt-display-when-idle t) - (and (consp help-at-pt-display-when-idle) - (catch 'found - (dolist (prop help-at-pt-display-when-idle) - (if (get-char-property (point) prop) - (throw 'found t))) - (unless (bobp) - (save-excursion - (backward-char) - (dolist (prop help-at-pt-display-when-idle) - (if (get-char-property (point) prop) - (throw 'found t)))))))) - (or (not (current-message)) - (string= (current-message) "Quit")) - (display-local-help t))) - -;;;###autoload -(defun scan-buf-move-to-region (prop &optional arg hook) - "Go to the start of the next region with non-nil PROP property. -Then run HOOK, which should be a quoted symbol that is a normal -hook variable, or an expression evaluating to such a symbol. -Adjacent areas with different non-nil PROP properties are -considered different regions. - -With numeric argument ARG, move to the start of the ARGth next -such region, then run HOOK. If ARG is negative, move backward. -If point is already in a region, then that region does not count -toward ARG. If ARG is 0 and point is inside a region, move to -the start of that region. If ARG is 0 and point is not in a -region, print a message to that effect, but do not move point and -do not run HOOK. If there are not enough regions to move over, -an error results and the number of available regions is mentioned -in the error message. Point is not moved and HOOK is not run." - (cond ((> arg 0) - (if (= (point) (point-max)) - (error "No further `%s' regions" prop)) - (let ((pos (point))) - (dotimes (x arg) - (setq pos (next-single-char-property-change pos prop)) - (unless (get-char-property pos prop) - (setq pos (next-single-char-property-change pos prop)) - (unless (get-char-property pos prop) - (cond ((= x 0) - (error "No further `%s' regions" prop)) - ((= x 1) - (error "There is only one further `%s' region" prop)) - (t - (error - "There are only %d further `%s' regions" - x prop)))))) - (goto-char pos) - (run-hooks hook))) - ((= arg 0) - (let ((val (get-char-property (point) prop))) - (cond ((not val) - (message "Point is not in a `%s' region" prop)) - ((eq val (get-char-property (1- (point)) prop)) - (goto-char - (previous-single-char-property-change (point) prop)) - (run-hooks hook)) - (t (run-hooks hook))))) - ((< arg 0) - (let ((pos (point)) (val (get-char-property (point) prop))) - (and val - (eq val (get-char-property (1- pos) prop)) - (setq pos - (previous-single-char-property-change pos prop))) - (if (= pos (point-min)) - (error "No prior `%s' regions" prop)) - (dotimes (x (- arg)) - (setq pos (previous-single-char-property-change pos prop)) - (unless (get-char-property pos prop) - (setq pos (previous-single-char-property-change pos prop)) - (unless (get-char-property pos prop) - (cond ((= x 0) - (error "No prior `%s' regions" prop)) - ((= x 1) - (error "There is only one prior `%s' region" prop)) - (t - (error "There are only %d prior `%s' regions" - x prop)))))) - (goto-char pos) - (run-hooks hook))))) - -;; To be moved to a different file and replaced by a defcustom in a -;; future version. -(defvar scan-buf-move-hook '(display-local-help) - "Normal hook run by `scan-buf-next-region'. -Also used by `scan-buf-previous-region'. The hook is run after -positioning point.") - -;;;###autoload -(defun scan-buf-next-region (&optional arg) - "Go to the start of the next region with non-nil help-echo. -Print the help found there using `display-local-help'. Adjacent -areas with different non-nil help-echo properties are considered -different regions. - -With numeric argument ARG, move to the start of the ARGth next -help-echo region. If ARG is negative, move backward. If point -is already in a help-echo region, then that region does not count -toward ARG. If ARG is 0 and point is inside a help-echo region, -move to the start of that region. If ARG is 0 and point is not -in such a region, just print a message to that effect. If there -are not enough regions to move over, an error results and the -number of available regions is mentioned in the error message. - -A potentially confusing subtlety is that point can be in a -help-echo region without any local help being available. This is -because `help-echo' can be a function evaluating to nil. This -rarely happens in practice." - (interactive "p") - (scan-buf-move-to-region 'help-echo arg 'scan-buf-move-hook)) - -;;;###autoload -(defun scan-buf-previous-region (&optional arg) - "Go to the start of the previous region with non-nil help-echo. -Print the help found there using `display-local-help'. Adjacent -areas with different non-nil help-echo properties are considered -different regions. With numeric argument ARG, behaves like -`scan-buf-next-region' with argument -ARG." - (interactive "p") - (scan-buf-move-to-region 'help-echo (- arg) 'scan-buf-move-hook)) - (provide 'help-at-pt) ;;; help-at-pt.el ends here -- 2.39.5