branch: externals/transient
commit 5fcd713873001724c8b21d3689c77cb7a6dc9cd7
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
transient-with-help-window: New macro
---
CHANGELOG | 3 +++
docs/transient.org | 16 ++++++++++++++--
docs/transient.texi | 16 ++++++++++++++--
lisp/transient.el | 11 +++++++++++
4 files changed, 42 insertions(+), 4 deletions(-)
diff --git a/CHANGELOG b/CHANGELOG
index 1ec8c68e1d..2c83f10a8d 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 c00ca6b7fe..d9616a55de 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 a69e8d0732..3e01b26c76 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 eb38eff8ef..e13f97c24f 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)
