transient-display-buffer-action: Discourage dropping alist elements

Re #358, but others have made the same mistake before.
magit · Feb 15, 2025 · 04dab99 · 04dab99
1 parent 73178e0
commit 04dab99
Show file tree

Hide file tree

Showing 2 changed files with 10 additions and 0 deletions.
diff --git a/docs/transient.org b/docs/transient.org
@@ -621,6 +621,11 @@ Also see [[* Common Suffix Commands]].
   For alternatives see [[info:elisp#Buffer Display Action Functions]],
   and [[info:elisp#Buffer Display Action Alists]].
 
+  When you switch to a different ACTION, you should keep the ALIST
+  entries for ~dedicated~ and ~inhibit-same-window~ in most cases.
+  Do not drop them because you are unsure whether they are needed;
+  if you are unsure, then keep them.
+
   Note that the buffer that was current before the transient buffer
   is shown should remain the current buffer.  Many suffix commands
   act on the thing at point, if appropriate, and if the transient

diff --git a/lisp/transient.el b/lisp/transient.el
@@ -213,6 +213,11 @@ This displays the window at the bottom of the selected frame.
 For alternatives see info node `(elisp)Display Action Functions'
 and info node `(elisp)Buffer Display Action Alists'.
 
+When you switch to a different ACTION, you should keep the ALIST
+entries for `dedicated' and `inhibit-same-window' in most cases.
+Do not drop them because you are unsure whether they are needed;
+if you are unsure, then keep them.
+
 Note that the buffer that was current before the transient buffer
 is shown should remain the current buffer.  Many suffix commands
 act on the thing at point, if appropriate, and if the transient