From: Eli Zaretskii <eliz@gnu.org>
Date: Fri, 4 Jul 2025 12:02:29 +0000 (+0300)
Subject: Improve documentation of 'warning-display-at-bottom'
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=4989cffcaf800144d47e8d4ab5639b2e03a971e4;p=emacs.git

Improve documentation of 'warning-display-at-bottom'

* lisp/emacs-lisp/warnings.el (warning-display-at-bottom):
* doc/lispref/display.texi (Warning Options):
* doc/emacs/windows.texi (Temporary Displays):
* etc/NEWS: Improve documentation of 'warning-display-at-bottom'.
See https://lists.gnu.org/archive/html/emacs-devel/2025-07/msg00024.html
for more details.

(cherry picked from commit 5bdacbe460a3dbc1777b8d06767c9c323c4fee23)
---

diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index d0f2ce0958c..e6b53018ace 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -588,6 +588,16 @@ can be controlled by customizing the options
 (@pxref{Temporary Displays,,Temporary Displays, elisp, The Emacs Lisp
 Reference Manual}), and cannot exceed the size of the containing frame.
 
+@cindex warning buffer, display
+@vindex warning-display-at-bottom
+  Buffers showing warnings (such as byte-compilation warnings,
+@pxref{Compilation Functions,, Byte Compilation Functions, elisp, The
+Emacs Lisp Reference Manual}) are also by default shown in a window at
+the bottom of the selected frame.  You can control this using the
+variable @code{warning-display-at-bottom}: if set to @code{nil}, Emacs
+will use the normal logic of @code{display-buffer} (@pxref{Window
+Choice}) instead, and you can customize that via
+@code{display-buffer-alist}.
 
 @node Window Convenience
 @section Convenience Features for Window Handling
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 448003b6e21..87ccba50213 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -933,6 +933,18 @@ won't appear at all.
   These variables are used by users to control what happens
 when a Lisp program reports a warning.
 
+@defopt warning-display-at-bottom
+This user option controls the window in which the warnings buffer is
+shown.  By default, the value is @code{t}, and Emacs displays the
+warnings buffer in a window at the bottom of the selected frame,
+creating a new window there if needed.  If customized to @code{nil}, the
+warnings buffer will be shown using the default rules of
+@code{display-buffer} (@pxref{Choosing Window}); in that case the
+@code{warning} category can be used in @code{display-buffer-alist} to
+customize how @code{display-buffer} will display these buffers
+(@pxref{Buffer Display Action Alists}).
+@end defopt
+
 @defopt warning-minimum-level
 This user option specifies the minimum severity level that should be
 shown immediately to the user, by popping the warnings buffer in some
diff --git a/lisp/emacs-lisp/warnings.el b/lisp/emacs-lisp/warnings.el
index bd68edae0c5..96dd114e587 100644
--- a/lisp/emacs-lisp/warnings.el
+++ b/lisp/emacs-lisp/warnings.el
@@ -122,9 +122,18 @@ See also `warning-suppress-log-types'."
   :version "22.1")
 
 (defcustom warning-display-at-bottom t
-  "Display the warning buffer at the bottom of the screen.
-The output window will be scrolled to the bottom of the buffer
-to show the last warning message."
+  "Whether to display the warning buffer at the bottom of the screen.
+If this is non-nil (the default), Emacs will attempt to display the
+window showing the warning buffer at the bottom of the selected
+frame, whether by reusing the bottom-most window or by creating a
+new window at the bottom of the frame.  The resulting window will be
+scrolled to the bottom of the buffer to show the last warning message.
+
+If the value of this variable is nil, Emacs will display the warning
+buffer in some window, as determined by `display-buffer' and its
+customizations.  In particular, the category designated by the
+symbol `warning' can be used in `display-buffer-alist' to customize
+the display of this buffer."
   :type 'boolean
   :version "30.1")