master 06321adfb37: ; Document how to use the new 'display-buffer-default-alist' variable

branch: master
commit 06321adfb379b0cc6e0e99bb43d700775faf440e
Author: Martin Rudalics <[email protected]>
Commit: Martin Rudalics <[email protected]>

    ; Document how to use the new 'display-buffer-default-alist' variable
    
    * lisp/window.el (display-buffer-default-alist): Rewrite doc-string.
    * doc/lispref/windows.texi (Choosing Window): Say how to use the
    new 'display-buffer-default-alist' variable.
---
 doc/lispref/windows.texi |  9 +++++++--
 lisp/window.el           | 18 +++++++++---------
 2 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 544a2f549d2..84345d5fb52 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -3196,8 +3196,13 @@ default value is an empty display action, i.e., @w{@code{(nil . nil)}}.
 
 @defvar display-buffer-default-alist
 The value of this variable is an alist mapping conditions to display
-actions (@pxref{display-buffer-alist}).  Lisp programs may let-bind it
-to specify conditional actions for wrapped @code{display-buffer} calls.
+actions (@pxref{display-buffer-alist}).
+
+Lisp programs may let-bind this variable to specify conditional actions
+for wrapped @code{display-buffer} calls.  Users are not supposed to set
+this variable.  They should customize @code{display-buffer-alist}
+instead which has higher priority and, as a rule, is left alone by Lisp
+programs.
 @end defvar
 
 @anchor{display-buffer-alist}
diff --git a/lisp/window.el b/lisp/window.el
index f35dc402392..fef2f3d4666 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -8114,17 +8114,17 @@ and adds the associated ACTION to the list of actions it will try."
 
 (defvar display-buffer-default-alist nil
   "Alist of conditional default actions for `display-buffer'.
-Its value takes effect before processing the ACTION argument of
-`display-buffer' and before `display-buffer-base-action' and
-`display-buffer-fallback-action', but after
-`display-buffer-overriding-action' and `display-buffer-alist', which
-see.
+If non-nil, this is an alist of elements (CONDITION . ACTION) like
+`display-buffer-alist'.  Its value takes effect before processing the
+ACTION argument of `display-buffer' and before
+`display-buffer-base-action' and `display-buffer-fallback-action', but
+after `display-buffer-overriding-action' and `display-buffer-alist',
+which see.
 
 Lisp programs may let-bind this variable to specify conditional actions
-for nested `display-buffer' calls.
-
-If non-nil, this is an alist of elements (CONDITION . ACTION) like
-`display-buffer-alist'.")
+for wrapped `display-buffer' calls.  Users are not supposed to set this
+variable.  They should customize `display-buffer-alist' instead which
+has higher priority and, as a rule, is left alone by Lisp programs.")
 (put 'display-buffer-default-alist 'risky-local-variable t)
 
 (defcustom display-buffer-base-action '(nil . nil)