transient--do-replace: Replace with two variants

Rename the existing `transient--do-replace' to `transient--do-stack',
because that's what it really does.

Repurpose the name `transient--do-replace' for a new variants that
actually replaces the active transient, i.e., which does not place
the active transient on the stack, but replaces it completely.

Changing what `transient--do-replace' does, shouldn't be a problem
because in definitions of individual transient prefix commands and
their sub-prefixes, this pre-command should never have been used
by name anyway.

3 files changed, 37 insertions, 8 deletions

diff --git a/docs/transient.org b/docs/transient.org
index e8b5a6c..615adbb 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -1380,15 +1380,25 @@ slot for the sub-prefix itself.
 
   Whether we actually return to the parent transient is ultimately
   under the control of each invoked suffix.  The difference between
-  this pre-command and ~transient--do-replace~ is that it changes the
+  this pre-command and ~transient--do-stack~ is that it changes the
   value of the ~transient-suffix~ slot to ~t~.
 
   If there is no parent transient, then only call this command and
   skip the second step.
 
+- Function: transient--do-stack ::
+
+  Call the transient prefix command, stacking the active transient.
+  Push the active transient to the transient stack.
+
+  Unless ~transient--do-recurse~ is explicitly used, this pre-command
+  is automatically used for suffixes that are prefixes themselves,
+  i.e., for sub-prefixes.
+
 - Function: transient--do-replace ::
 
   Call the transient prefix command, replacing the active transient.
+  Do not push the active transient to the transient stack.
 
   Unless ~transient--do-recurse~ is explicitly used, this pre-command
   is automatically used for suffixes that are prefixes themselves,
diff --git a/docs/transient.texi b/docs/transient.texi
index a8d1ab2..9c4730f 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -1572,15 +1572,25 @@ transient.
 
 Whether we actually return to the parent transient is ultimately
 under the control of each invoked suffix.  The difference between
-this pre-command and @code{transient--do-replace} is that it changes the
+this pre-command and @code{transient--do-stack} is that it changes the
 value of the @code{transient-suffix} slot to @code{t}.
 
 If there is no parent transient, then only call this command and
 skip the second step.
 @end defun
 
+@defun transient--do-stack
+Call the transient prefix command, stacking the active transient.
+Push the active transient to the transient stack.
+
+Unless @code{transient--do-recurse} is explicitly used, this pre-command
+is automatically used for suffixes that are prefixes themselves,
+i.e., for sub-prefixes.
+@end defun
+
 @defun transient--do-replace
 Call the transient prefix command, replacing the active transient.
+Do not push the active transient to the transient stack.
 
 Unless @code{transient--do-recurse} is explicitly used, this pre-command
 is automatically used for suffixes that are prefixes themselves,
diff --git a/lisp/transient.el b/lisp/transient.el
index fb4dec1..2b81822 100644
--- a/lisp/transient.el
+++ b/lisp/transient.el
@@ -1779,7 +1779,7 @@ of the corresponding object."
           (define-key map (vector cmd)
             (pcase (list kind (oref obj transient) return)
               (`(prefix   t ,_) #'transient--do-recurse)
-              (`(prefix nil ,_) #'transient--do-replace)
+              (`(prefix nil ,_) #'transient--do-stack)
               (`(infix    t ,_) #'transient--do-stay)
               (`(suffix   t ,_) #'transient--do-call)
               ('(suffix nil  t) #'transient--do-return)
@@ -1791,7 +1791,7 @@ of the corresponding object."
               (`(prefix ,(or 'transient--do-stay 'transient--do-call) ,_)
                #'transient--do-recurse)
               (`(prefix   t ,_) #'transient--do-recurse)
-              (`(prefix  ,_ ,_) #'transient--do-replace)
+              (`(prefix  ,_ ,_) #'transient--do-stack)
               (`(infix   ,_ ,_) #'transient--do-stay)
               (`(suffix   t ,_) #'transient--do-call)
               ('(suffix nil  t) #'transient--do-return)
@@ -1856,7 +1856,7 @@ EDIT may be non-nil."
       (setq params (list :scope (oref transient--prefix scope))))
      (transient--prefix
       ;; Invoked as a ":transient-non-suffix 'transient--do-{stay,call}"
-      ;; of an outer prefix.  Unlike the usual `transient--do-replace',
+      ;; of an outer prefix.  Unlike the usual `transient--do-stack',
       ;; these predicates fail to clean up after the outer prefix.
       (transient--pop-keymap 'transient--transient-map)
       (transient--pop-keymap 'transient--redisplay-map))
@@ -2546,7 +2546,7 @@ Use that command's pre-command to determine transient behavior."
 (defun transient--do-recurse ()
   "Call the transient prefix command, preparing for return to active transient.
 If there is no parent prefix, then just call the command."
-  (transient--do-replace))
+  (transient--do-stack))
 
 (defun transient--setup-recursion (prefix-obj)
   (when transient--stack
@@ -2558,13 +2558,21 @@ If there is no parent prefix, then just call the command."
                     (list t #'transient--do-recurse))
           (oset prefix-obj transient-suffix t))))))
 
-(defun transient--do-replace ()
-  "Call the transient prefix command, replacing the active transient."
+(defun transient--do-stack ()
+  "Call the transient prefix command, stacking the active transient.
+Push the active transient to the transient stack."
   (transient--export)
   (transient--stack-push)
   (setq transient--exitp 'replace)
   transient--exit)
 
+(defun transient--do-replace ()
+  "Call the transient prefix command, replacing the active transient.
+Do not push the active transient to the transient stack."
+  (transient--export)
+  (setq transient--exitp 'replace)
+  transient--exit)
+
 (defun transient--do-suspend ()
   "Suspend the active transient, saving the transient stack."
   (transient--stack-push)
@@ -2614,6 +2622,7 @@ prefix argument and pivot to `transient-update'."
 (put 'transient--do-exit       'transient-color 'transient-blue)
 (put 'transient--do-recurse    'transient-color 'transient-red)
 (put 'transient--do-replace    'transient-color 'transient-blue)
+(put 'transient--do-stack      'transient-color 'transient-red)
 (put 'transient--do-suspend    'transient-color 'transient-blue)
 (put 'transient--do-quit-one   'transient-color 'transient-blue)
 (put 'transient--do-quit-all   'transient-color 'transient-blue)