transient--do-leave: New pre-command for non-suffixes

Previously one would have had to use `transient--do-exit` but
unlike `transient--do-stay', that does export variable.  Avoid
this unfortunate asymmetry, even though in most, if not all,
cases it should not affect the outcome.

2 files changed, 42 insertions, 18 deletions

diff --git a/docs/transient.org b/docs/transient.org
index 5105e2a..3784540 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -1371,22 +1371,35 @@ slot.
 :UNNUMBERED: notoc
 :END:
 
-The default for non-suffixes, i.e., commands that are bound in other
-keymaps beside the transient keymap, is ~transient--do-warn~.  Silently
-ignoring the user-error is also an option, though probably not a good
-one.
+By default, non-suffixes (commands that are bound in other keymaps
+beside the transient keymap) cannot be invoked.  Trying to invoke
+such a command results in a warning and the transient stays active.
 
-If you want to let the user invoke non-suffix commands, then use
-~transient--do-stay~ as the value of the prefix's ~transient-non-suffix~
-slot.
+If you want a different behavior, then set the ~:transient-non-suffix~
+slot of the transient prefix command.  The value can be a boolean,
+answering the question, "is it allowed to invoke non-suffix commands?"
+
+If the value is ~t~ or ~transient--do-stay~, then non-suffixes can be
+invoked, when it is ~nil~ or ~transient--do-warn~ (the default) then they
+cannot be invoked.
+
+The only other recommended value is ~transient--do-leave~.  If that is
+used, then non-suffixes can be invoked, but if one is invoked, then
+that exits the transient.
 
 - Function: transient--do-warn ::
 
   Call ~transient-undefined~ and stay transient.
 
-- Function: transient--do-noop ::
+- Function: transient--do-stay ::
+
+  Call the command without exporting variables and stay transient.
+
+- Function: transient--do-leave ::
+
+  Call the command without exporting variables and exit the transient.
 
-  Call ~transient-noop~ and stay transient.
+# transient--do-noop intentionally left undocumented.
 
 *** Special Pre-Commands
 :PROPERTIES:
diff --git a/docs/transient.texi b/docs/transient.texi
index 996cd96..2b882d1 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -1586,21 +1586,32 @@ be added to @code{transient-predicate-map}.
 @anchor{Pre-commands for Non-Suffixes}
 @subheading Pre-commands for Non-Suffixes
 
-The default for non-suffixes, i.e., commands that are bound in other
-keymaps beside the transient keymap, is @code{transient--do-warn}.  Silently
-ignoring the user-error is also an option, though probably not a good
-one.
+By default, non-suffixes (commands that are bound in other keymaps
+beside the transient keymap) cannot be invoked.  Trying to invoke
+such a command results in a warning and the transient stays active.
 
-If you want to let the user invoke non-suffix commands, then use
-@code{transient--do-stay} as the value of the prefix's @code{transient-non-suffix}
-slot.
+If you want a different behavior, then set the @code{:transient-non-suffix}
+slot of the transient prefix command.  The value can be a boolean,
+answering the question, "is it allowed to invoke non-suffix commands?"
+
+If the value is @code{t} or @code{transient--do-stay}, then non-suffixes can be
+invoked, when it is @code{nil} or @code{transient--do-warn} (the default) then they
+cannot be invoked.
+
+The only other recommended value is @code{transient--do-leave}.  If that is
+used, then non-suffixes can be invoked, but if one is invoked, then
+that exits the transient.
 
 @defun transient--do-warn
 Call @code{transient-undefined} and stay transient.
 @end defun
 
-@defun transient--do-noop
-Call @code{transient-noop} and stay transient.
+@defun transient--do-stay
+Call the command without exporting variables and stay transient.
+@end defun
+
+@defun transient--do-leave
+Call the command without exporting variables and exit the transient.
 @end defun
 
 @anchor{Special Pre-Commands}