branch: externals/transient
commit 4d283706a8c51400516a3f6344b8859a90cad900
Author: Jonas Bernoulli <[email protected]>
Commit: Jonas Bernoulli <[email protected]>
transient-get-summary: Optionally echo even duplicated documentation
---
docs/transient.org | 24 ++++++++++++++++++------
docs/transient.texi | 24 ++++++++++++++++++------
lisp/transient.el | 25 +++++++++++++++++--------
3 files changed, 53 insertions(+), 20 deletions(-)
diff --git a/docs/transient.org b/docs/transient.org
index 7da7e72213..be5332b4f5 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -600,14 +600,21 @@ Two more essential options are documented in [[* Common
Suffix Commands]].
- User Option: transient-enable-menu-navigation ::
This option controls whether navigation commands are enabled in
- transient's menu buffer. If the value is ~verbose~ (the default),
- brief documentation about the command under point is additionally
- show in the echo area.
+ transient menu buffer, and whether additional documentation is shown
+ in the echo area while doing so.
+
+ If the value is ~verbose~ (the default), additional documentation
+ about the command at point is shown in the echo area. If this would
+ result in the same documentation, which is being displayed inside
+ the menu buffer, to be duplicated in the echo area, then ~verbose~
+ forgoes doing so. Use ~force-verbose~ to echo even such documentation.
+ Use ~t~ to enable menu navigation without showing documentation in the
+ echo area.
While a transient is active, the menu buffer is (by default) not the
current buffer, making it necessary to use dedicated commands to act
- on that buffer itself. If this option is non-nil, then the following
- bindings are available:
+ on that buffer itself. If this option is non-nil, then the
+ following bindings are available:
- {{{kbd(UP)}}} moves the cursor to the previous suffix.
- {{{kbd(DOWN)}}} moves the cursor to the next suffix.
@@ -700,7 +707,12 @@ text at point, to be run when a transient menu is active,
for example:
- User Option: transient-enable-menu-navigation ::
This option is documented in the previous node ([[* Essential
- Options]]).
+ Options]]). You might want to change the value from ~verbose~ to
+ ~force-verbose~, which causes information to be shown in the echo
+ area, even if it is identical to information already displayed in
+ the menu buffer. Whether that is useful to you depends on whether
+ your setup makes it easy to read the last message displayed in the
+ echo area.
- User Option: transient-navigate-to-group-descriptions ::
diff --git a/docs/transient.texi b/docs/transient.texi
index 3f9827210d..5a41ccbe14 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -749,14 +749,21 @@ element has to be accessed the same way as the older
elements.
@defopt transient-enable-menu-navigation
This option controls whether navigation commands are enabled in
-transient's menu buffer. If the value is @code{verbose} (the default),
-brief documentation about the command under point is additionally
-show in the echo area.
+transient menu buffer, and whether additional documentation is shown
+in the echo area while doing so.
+
+If the value is @code{verbose} (the default), additional documentation
+about the command at point is shown in the echo area. If this would
+result in the same documentation, which is being displayed inside
+the menu buffer, to be duplicated in the echo area, then @code{verbose}
+forgoes doing so. Use @code{force-verbose} to echo even such documentation.
+Use @code{t} to enable menu navigation without showing documentation in the
+echo area.
While a transient is active, the menu buffer is (by default) not the
current buffer, making it necessary to use dedicated commands to act
-on that buffer itself. If this option is non-nil, then the following
-bindings are available:
+on that buffer itself. If this option is non-nil, then the
+following bindings are available:
@itemize
@item
@@ -853,7 +860,12 @@ text at point, to be run when a transient menu is active,
for example:
@end lisp
@defopt transient-enable-menu-navigation
-This option is documented in the previous node (@ref{Essential Options}).
+This option is documented in the previous node (@ref{Essential Options}). You
might want to change the value from @code{verbose} to
+@code{force-verbose}, which causes information to be shown in the echo
+area, even if it is identical to information already displayed in
+the menu buffer. Whether that is useful to you depends on whether
+your setup makes it easy to read the last message displayed in the
+echo area.
@end defopt
@defopt transient-navigate-to-group-descriptions
diff --git a/lisp/transient.el b/lisp/transient.el
index f4191f89a5..4422e9c555 100644
--- a/lisp/transient.el
+++ b/lisp/transient.el
@@ -168,8 +168,12 @@ from Emacs commit
e680827e814e155cf79175d87ff7c6ee3a08b69a."
(defcustom transient-enable-menu-navigation 'verbose
"Whether navigation commands are enabled in the menu buffer.
-If the value is `verbose' (the default), additionally show brief
-documentation about the command under point in the echo area.
+If the value is `verbose' (the default), show additional documentation
+about the command at point in the echo area. If this would result in
+the same documentation, which is being displayed inside the menu buffer,
+to be duplicated in the echo area, then `verbose' forgoes doing so.
+Use `force-verbose' to echo even such documentation. If `t', enable
+navigation, but without echoing any documentation.
While a transient is active, the menu buffer is (by default) not the
current buffer, making it necessary to use dedicated commands to act
@@ -193,9 +197,12 @@ then it is likely that the user would want the former do
what it would
do if no transient were active."
:package-version '(transient . "0.7.8")
:group 'transient
- :type '(choice (const :tag "Enable navigation and echo summary" verbose)
- (const :tag "Enable navigation commands" t)
- (const :tag "Disable navigation commands" nil)))
+ :type
+ '(choice
+ (const :tag "Enable navigation and force showing summary" force-verbose)
+ (const :tag "Enable navigation and enable showing summary" verbose)
+ (const :tag "Enable navigation commands" t)
+ (const :tag "Disable navigation commands" nil)))
(defcustom transient-navigate-to-group-descriptions nil
"Whether menu navigation commands stop at group descriptions.
@@ -5264,7 +5271,7 @@ If RETURN is non-nil, return the summary instead of
showing it.
This is used when a tooltip is needed.")
(cl-defmethod transient-get-summary ((obj transient-object))
- (and-let*
+ (cond-let*
([summary (cond-let*
[[summary (oref obj summary)]]
((functionp summary)
@@ -5281,7 +5288,9 @@ This is used when a tooltip is needed.")
"\n"))))]
(if (string-suffix-p "." summary)
(substring summary 0 -1)
- summary))))
+ summary))
+ ((eq transient-enable-menu-navigation 'force-verbose)
+ (transient--get-description obj))))
;;; Menu Navigation
@@ -5318,7 +5327,7 @@ See `forward-button' for information about N."
(transient--button-move-echo)))
(defun transient--button-move-echo ()
- (when-let ((_(eq transient-enable-menu-navigation 'verbose))
+ (when-let ((_(memq transient-enable-menu-navigation '(verbose
force-verbose)))
(obj (get-text-property (point) 'button-data)))
(let ((message-log-max nil))
(message "%s" (or (transient-get-summary obj) "")))))
