From 4d283706a8c51400516a3f6344b8859a90cad900 Mon Sep 17 00:00:00 2001 From: Jonas Bernoulli Date: Mon, 23 Feb 2026 10:46:05 +0100 Subject: 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 7da7e72..be5332b 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 3f98272..5a41ccb 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 f4191f8..4422e9c 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) ""))))) -- cgit v1.0