branch: externals/transient
commit 0a29b4892c1862991025c9c066200ae706b85895
Author: Jonas Bernoulli <[email protected]>
Commit: Jonas Bernoulli <[email protected]>
manual: Extend information about summary slot
---
docs/transient.org | 15 +++++++++++----
docs/transient.texi | 15 +++++++++++----
2 files changed, 22 insertions(+), 8 deletions(-)
diff --git a/docs/transient.org b/docs/transient.org
index b8655c0aeb..06f4d1b8a4 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -2642,10 +2642,17 @@ and ~advice*~ slots (see [[*Slots of
~transient-suffix~]]) are defined.
unspecified, the prefix controls how help is displayed for its
suffixes. See also function ~transient-show-help~.
-- ~summary~ The summary displayed in the echo area, or as a tooltip.
- If this is ~nil~, which it usually should be, the first line of the
- documentation string is used instead. See ~transient-show-summary~
- for details.
+- ~summary~ A short description to be displayed in addition to the text
+ displayed in the menu itself. If this is ~nil~, the first line of the
+ documentation string is used instead. If non-~nil~, this must be a
+ string or a function that returns a string or ~nil~.
+
+ This description is displayed as a tooltip, when hovering an element
+ in the menu. If ~transient-enable-menu-navigation~ is ~verbose~, it is
+ also shown in the echo area, when navigating the menu.
+
+ The generic function ~transient-get-summary~ is used to determine and
+ format this description.
- ~definition~ A command, which is used if the body is omitted when
defining a command using ~transient-define-suffix~.
diff --git a/docs/transient.texi b/docs/transient.texi
index b9f8ac18ff..6a09a351cf 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -2941,10 +2941,17 @@ unspecified, the prefix controls how help is displayed
for its
suffixes. See also function @code{transient-show-help}.
@item
-@code{summary} The summary displayed in the echo area, or as a tooltip.
-If this is @code{nil}, which it usually should be, the first line of the
-documentation string is used instead. See @code{transient-show-summary}
-for details.
+@code{summary} A short description to be displayed in addition to the text
+displayed in the menu itself. If this is @code{nil}, the first line of the
+documentation string is used instead. If non-@code{nil}, this must be a
+string or a function that returns a string or @code{nil}.
+
+This description is displayed as a tooltip, when hovering an element
+in the menu. If @code{transient-enable-menu-navigation} is @code{verbose}, it
is
+also shown in the echo area, when navigating the menu.
+
+The generic function @code{transient-get-summary} is used to determine and
+format this description.
@item
@code{definition} A command, which is used if the body is omitted when
