transient-with-help-window: New macro

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.

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:

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,14 +2114,20 @@ 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
 
 @itemize
 @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}}

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)