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 d0f2ce0958ca5c845a2fc830f468a5bdb6e9c166..e6b53018ace365a97c350c4a8f27d422bedec64f 100644 (file)
--- 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 448003b6e215e97e5eb5ea7e1af1c1345000b9e6..87ccba502132ab9896f57945394019aa5f9c2b6d 100644 (file)
--- 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 bd68edae0c54a1f38f4912abb2b31ca30f7aad5f..96dd114e58784dc15b99e8b0c501923347ab5fb5 100644 (file)
--- 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")