[elpa] externals/transient cb11650a60 2/8: Show information about the suffix at point in the echo area

[Jonas Bernoulli]

branch: externals/transient
commit cb11650a60728d214b2a4d7bb7535add2c4c5d4c
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@bernoul.li>

    Show information about the suffix at point in the echo area
    
    Display the same information, using a tooltip, when the mouse
    is over a command button.
    
    Closes #282.
---
 docs/transient.org  | 27 +++++++++++++++++++++++-
 docs/transient.texi | 28 +++++++++++++++++++++++-
 lisp/transient.el   | 61 +++++++++++++++++++++++++++++++++++++++++++++++------
 3 files changed, 107 insertions(+), 9 deletions(-)

diff --git a/docs/transient.org b/docs/transient.org
index 6816a91d76..503e4dc6e3 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -461,7 +461,8 @@ Also see [[* Common Suffix Commands]].
 - User Option: transient-enable-popup-navigation ::
 
   This option controls whether navigation commands are enabled in the
-  transient popup buffer.
+  transient popup buffer.  If the value is ~verbose~, additionally show
+  brief documentation about the command under point in the echo area.
 
   While a transient is active the transient popup buffer is not the
   current buffer, making it necessary to use dedicated commands to act
@@ -1869,6 +1870,25 @@ functions use ~describe-function~.
   window.  Select the help window, and make the help buffer current
   and return it.
 
+- Function: transient-show-summary obj &optional return ::
+
+  This generic function shows or, if optional RETURN is non-~nil~,
+  returns a brief summary about the command at point or hovered with
+  the mouse.
+
+  This function is called when the mouse is moved over a command and
+  (if the value of ~transient-enable-popup-navigation~ is ~verbose~) when
+  the user navigates to a command using the keyboard.
+
+  If OBJ's ~summary~ slot is a string, that is used.  If ~summary~ is a
+  function, that is called with OBJ as the only argument and the
+  returned string is used.  If ~summary~ is or returns something other
+  than a string or nil, no summary is shown.  If ~summary~ is or returns
+  ~nil~, the first line of the documentation string is used, if any.
+
+  If RETURN is non-~nil~, this function returns the summary instead of
+  showing it.  This is used when a tooltip is needed.
+
 ** Prefix Slots
 
 - ~show-help~, ~man-page~ or ~info-manual~ can be used to specify the
@@ -1972,6 +1992,11 @@ Also see [[*Suffix Classes]].
   unspecified, the prefix controls how help is displayed for its
   suffixes.  See also function ~transient-show-help~.
 
+- ~summary~ The summary displayed in the echo area, or as a tooltip.
+  If this is ~nil~, which it usually should be, the first line of the
+  documentation string is used instead.  See ~transient-show-summary~
+  for details.
+
 *** Slots of ~transient-infix~
 :PROPERTIES:
 :UNNUMBERED: notoc
diff --git a/docs/transient.texi b/docs/transient.texi
index 594871ae99..59f9278cf9 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -618,7 +618,8 @@ the absolute value).
 
 @defopt transient-enable-popup-navigation
 This option controls whether navigation commands are enabled in the
-transient popup buffer.
+transient popup buffer.  If the value is @code{verbose}, additionally show
+brief documentation about the command under point in the echo area.
 
 While a transient is active the transient popup buffer is not the
 current buffer, making it necessary to use dedicated commands to act
@@ -2125,6 +2126,25 @@ window.  Select the help window, and make the help 
buffer current
 and return it.
 @end defmac
 
+@defun transient-show-summary obj &optional return
+This generic function shows or, if optional RETURN is non-@code{nil},
+returns a brief summary about the command at point or hovered with
+the mouse.
+
+This function is called when the mouse is moved over a command and
+(if the value of @code{transient-enable-popup-navigation} is @code{verbose}) 
when
+the user navigates to a command using the keyboard.
+
+If OBJ's @code{summary} slot is a string, that is used.  If @code{summary} is a
+function, that is called with OBJ as the only argument and the
+returned string is used.  If @code{summary} is or returns something other
+than a string or nil, no summary is shown.  If @code{summary} is or returns
+@code{nil}, the first line of the documentation string is used, if any.
+
+If RETURN is non-@code{nil}, this function returns the summary instead of
+showing it.  This is used when a tooltip is needed.
+@end defun
+
 @node Prefix Slots
 @section Prefix Slots
 
@@ -2252,6 +2272,12 @@ the styling there.  @code{face} is appended using 
@code{add-face-text-property}.
 @code{show-help} A function used to display help for the suffix.  If
 unspecified, the prefix controls how help is displayed for its
 suffixes.  See also function @code{transient-show-help}.
+
+@item
+@code{summary} The summary displayed in the echo area, or as a tooltip.
+If this is @code{nil}, which it usually should be, the first line of the
+documentation string is used instead.  See @code{transient-show-summary}
+for details.
 @end itemize
 
 @anchor{Slots of @code{transient-infix}}
diff --git a/lisp/transient.el b/lisp/transient.el
index 9953b83237..a6e9ee8fd8 100644
--- a/lisp/transient.el
+++ b/lisp/transient.el
@@ -140,9 +140,12 @@ TYPE is a type descriptor as accepted by `cl-typep', which 
see."
                  (const  :tag "on demand (no summary)" 0)
                  (number :tag "after delay" 1)))
 
-(defcustom transient-enable-popup-navigation t
+(defcustom transient-enable-popup-navigation 'verbose
   "Whether navigation commands are enabled in the transient popup.
 
+If the value is `verbose', additionally show brief documentation
+about the command under point in the echo area.
+
 While a transient is active the transient popup buffer is not the
 current buffer, making it necessary to use dedicated commands to
 act on that buffer itself.  If this is non-nil, then the following
@@ -165,9 +168,11 @@ By default \\`M-RET' is bound to `transient-push-button', 
instead of
 \\`RET', because if a transient allows the invocation of non-suffixes,
 then it is likely, that you would want \\`RET' to do what it would do
 if no transient were active."
-  :package-version '(transient . "0.4.0")
+  :package-version '(transient . "0.7.8")
   :group 'transient
-  :type 'boolean)
+  :type '(choice (const :tag "enable navigation and echo summary" verbose)
+                 (const :tag "enable navigation commands" t)
+                 (const :tag "disable navigation commands" nil)))
 
 (defcustom transient-display-buffer-action
   '(display-buffer-in-side-window
@@ -774,7 +779,8 @@ slot is non-nil."
    (format      :initarg :format      :initform " %k %d")
    (description :initarg :description :initform nil)
    (face        :initarg :face        :initform nil)
-   (show-help   :initarg :show-help   :initform nil))
+   (show-help   :initarg :show-help   :initform nil)
+   (summary     :initarg :summary     :initform nil))
   "Superclass for suffix command.")
 
 (defclass transient-information (transient-suffix)
@@ -3901,6 +3907,7 @@ as a button."
                (slot-boundp obj 'command))
       (setq str (make-text-button str nil
                                   'type 'transient
+                                  'suffix obj
                                   'command (oref obj command))))
     str))
 
@@ -4359,6 +4366,37 @@ Suffixes on levels %s and %s are unavailable.\n"
                (propertize (format ">=%s" (1+ level))
                            'face 'transient-disabled-suffix))))))
 
+(cl-defgeneric transient-show-summary (obj &optional return)
+  "Show brief summary about the command at point in the echo area.
+
+If OBJ's `summary' slot is a string, use that.  If it is a function,
+call that with OBJ as the only argument and use the returned string.
+If `summary' is or returns something other than a string or nil,
+show no summary.  If `summary' is or returns nil, use the first line
+of the documentation string, if any.
+
+If RETURN is non-nil, return the summary instead of showing it.
+This is used when a tooltip is needed.")
+
+(cl-defmethod transient-show-summary ((obj transient-suffix) &optional return)
+  (with-slots (command summary) obj
+    (when-let*
+        ((doc (cond ((functionp summary)
+                     (funcall summary obj))
+                    (summary)
+                    ((car (split-string (documentation command) "\n")))))
+         ((stringp doc))
+         ((not (equal doc
+                      (car (split-string (documentation
+                                          'transient--default-infix-command)
+                                         "\n"))))))
+      (when (string-suffix-p "." doc)
+        (setq doc (substring doc 0 -1)))
+      (if return
+          doc
+        (let ((message-log-max nil))
+          (message "%s" doc))))))
+
 ;;; Popup Navigation
 
 (defun transient-scroll-up (&optional arg)
@@ -4382,18 +4420,27 @@ around `scroll-down-command' (which see)."
 See `backward-button' for information about N."
   (interactive "p")
   (with-selected-window transient--window
-    (backward-button n t)))
+    (backward-button n t)
+    (when (eq transient-enable-popup-navigation 'verbose)
+      (transient-show-summary (get-text-property (point) 'suffix)))))
 
 (defun transient-forward-button (n)
   "Move to the next button in the transient popup buffer.
 See `forward-button' for information about N."
   (interactive "p")
   (with-selected-window transient--window
-    (forward-button n t)))
+    (forward-button n t)
+    (when (eq transient-enable-popup-navigation 'verbose)
+      (transient-show-summary (get-text-property (point) 'suffix)))))
 
 (define-button-type 'transient
   'face nil
-  'keymap transient-button-map)
+  'keymap transient-button-map
+  'help-echo (lambda (win buf pos)
+               (with-selected-window win
+                 (with-current-buffer buf
+                   (transient-show-summary
+                    (get-text-property pos 'suffix) t)))))
 
 (defun transient--goto-button (command)
   (cond