diff --git a/CHANGELOG b/CHANGELOG index 1ec8c68..2c83f10 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -7,6 +7,9 @@ - ~other-frame-prefix~ and ~other-window-prefix~ can now be used while a transient prefix is active. #305 +- Added new macro ~transient-with-help-window~ for use in ~:show-help~ + functions. #309 + * v0.7.5 2024-09-01 - Updated tooling. diff --git a/docs/transient.org b/docs/transient.org index c00ca6b..d9616a5 100644 --- a/docs/transient.org +++ b/docs/transient.org @@ -1842,6 +1842,12 @@ functions use ~describe-function~. Show help for the prefix, infix or suffix command represented by {{{var(OBJ)}}}. + Regardless of OBJ's type, if its ~show-help~ slot is non-nil, that + must be a function, which takes OBJ is its only argument. It must + prepare, display and return a buffer, and select the window used to + display it. The ~transient-show-help-window~ macro is intended for + use in such functions. + For prefixes, show the info manual, if that is specified using the ~info-manual~ slot. Otherwise, show the manpage if that is specified using the ~man-page~ slot. Otherwise, show the command's @@ -1852,11 +1858,17 @@ functions use ~describe-function~. For infixes, show the manpage if that is specified. Otherwise show the command's documentation string. +- Macro: transient-with-help-window &rest body :: + + Evaluate BODY, send output to ~*Help*~ buffer, and display it in a + window. Select the help window, and make the help buffer current + and return it. + ** Prefix Slots - ~show-help~, ~man-page~ or ~info-manual~ can be used to specify the documentation for the prefix and its suffixes. The command - ~transient-help~ uses the method ~transient-show-help~ (which see) to + ~transient-help~ uses the function ~transient-show-help~ (which see) to lookup and use these values. - ~history-key~ If multiple prefix commands should share a single value, @@ -1953,7 +1965,7 @@ Also see [[*Suffix Classes]]. - ~show-help~ A function used to display help for the suffix. If unspecified, the prefix controls how help is displayed for its - suffixes. + suffixes. See also function ~transient-show-help~. *** Slots of ~transient-infix~ :PROPERTIES: diff --git a/docs/transient.texi b/docs/transient.texi index a69e8d0..3e01b26 100644 --- a/docs/transient.texi +++ b/docs/transient.texi @@ -2097,6 +2097,12 @@ the result. Show help for the prefix, infix or suffix command represented by @var{OBJ}. +Regardless of OBJ's type, if its @code{show-help} slot is non-nil, that +must be a function, which takes OBJ is its only argument. It must +prepare, display and return a buffer, and select the window used to +display it. The @code{transient-show-help-window} macro is intended for +use in such functions. + For prefixes, show the info manual, if that is specified using the @code{info-manual} slot. Otherwise, show the manpage if that is specified using the @code{man-page} slot. Otherwise, show the command's @@ -2108,6 +2114,12 @@ For infixes, show the manpage if that is specified. Otherwise show the command's documentation string. @end defun +@defmac transient-with-help-window &rest body +Evaluate BODY, send output to @code{*Help*} buffer, and display it in a +window. Select the help window, and make the help buffer current +and return it. +@end defmac + @node Prefix Slots @section Prefix Slots @@ -2115,7 +2127,7 @@ the command's documentation string. @item @code{show-help}, @code{man-page} or @code{info-manual} can be used to specify the documentation for the prefix and its suffixes. The command -@code{transient-help} uses the method @code{transient-show-help} (which see) to +@code{transient-help} uses the function @code{transient-show-help} (which see) to lookup and use these values. @item @@ -2234,7 +2246,7 @@ the styling there. @code{face} is appended using @code{add-face-text-property}. @item @code{show-help} A function used to display help for the suffix. If unspecified, the prefix controls how help is displayed for its -suffixes. +suffixes. See also function @code{transient-show-help}. @end itemize @anchor{Slots of @code{transient-infix}} diff --git a/lisp/transient.el b/lisp/transient.el index eb38eff..e13f97c 100644 --- a/lisp/transient.el +++ b/lisp/transient.el @@ -4225,6 +4225,17 @@ manpage, then try to jump to the correct location." "Show the command doc-string." (transient--describe-function cmd)) +(defmacro transient-with-help-window (&rest body) + "Evaluate BODY, send output to *Help* buffer, and display it in a window. +Select the help window, and make the help buffer current and return it." + (declare (indent 0)) + `(let ((buffer nil) + (help-window-select t)) + (with-help-window (help-buffer) + ,@body + (setq buffer (current-buffer))) + (set-buffer buffer))) + (defun transient--describe-function (fn) (let* ((buffer nil) (help-window-select t)