Fix minibuffer window related docs and strings (Bug#28978)

* src/frame.c (Vdefault_minibuffer_frame): Fix doc-string.
* src/window.c (Fminibuffer_selected_window): Fix doc-string.
* doc/lispref/frames.texi (Buffer Parameters): Rewrite
description of `minibuffer' parameter.
* doc/lispref/minibuf.texi (Minibuffer Windows): Reorder
entries and partly rewrite section.
(Minibuffer Misc): Clarify description of
`minibuffer-selected-window'.
* etc/NEWS: Mention new semantics of 'minibuffer' frame
parameter.

5 files changed, 45 insertions, 33 deletions

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index ad853418ac4..5ea7125882f 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -1850,8 +1850,14 @@ yes, @code{nil} means no, @code{only} means this frame is just a
 minibuffer.  If the value is a minibuffer window (in some other
 frame), the frame uses that minibuffer.
 
-This frame parameter takes effect when the frame is created, and can
-not be changed afterwards.
+This parameter takes effect when the frame is created.  If specified as
+@code{nil}, Emacs will try to set it to the minibuffer window of
+@code{default-minibuffer-frame} (@pxref{Minibuffers and Frames}).  For
+an existing frame, this parameter can be used exclusively to specify
+another minibuffer window.  It is not allowed to change it from a
+minibuffer window to @code{t} and vice-versa, or from @code{t} to
+@code{nil}.  If the parameter specifies a minibuffer window already,
+setting it to @code{nil} has no effect.
 
 @vindex buffer-predicate, a frame parameter
 @item buffer-predicate
@@ -1872,6 +1878,7 @@ most-recently-selected first.
 If non-@code{nil}, this frame's window is never split automatically.
 @end table
 
+
 @node Frame Interaction Parameters
 @subsubsection Frame Interaction Parameters
 @cindex frame interaction parameters
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 1ece8996008..db69e7d8919 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -2256,39 +2256,44 @@ contents of the minibuffer before the point.
 These functions access and select minibuffer windows, test whether they
 are active and control how they get resized.
 
-@defun active-minibuffer-window
-This function returns the currently active minibuffer window, or
-@code{nil} if there is none.
-@end defun
-
 @defun minibuffer-window &optional frame
 @anchor{Definition of minibuffer-window}
 This function returns the minibuffer window used for frame @var{frame}.
-If @var{frame} is @code{nil}, that stands for the current frame.  Note
-that the minibuffer window used by a frame need not be part of that
+If @var{frame} is @code{nil}, that stands for the selected frame.
+
+Note that the minibuffer window used by a frame need not be part of that
 frame---a frame that has no minibuffer of its own necessarily uses some
-other frame's minibuffer window.
+other frame's minibuffer window.  The minibuffer window of a
+minibuffer-less frame can be changed by setting that frame's
+@code{minibuffer} frame parameter (@pxref{Buffer Parameters}).
 @end defun
 
 @defun set-minibuffer-window window
 This function specifies @var{window} as the minibuffer window to use.
 This affects where the minibuffer is displayed if you put text in it
-without invoking the usual minibuffer commands.  It has no effect on
-the usual minibuffer input functions because they all start by
-choosing the minibuffer window according to the current frame.
+without invoking the usual minibuffer commands.  It has no effect on the
+usual minibuffer input functions because they all start by choosing the
+minibuffer window according to the selected frame.
 @end defun
 
 @c Emacs 19 feature
 @defun window-minibuffer-p &optional window
 This function returns non-@code{nil} if @var{window} is a minibuffer
-window.
-@var{window} defaults to the selected window.
+window.  @var{window} defaults to the selected window.
+@end defun
+
+The following function returns the window showing the currently active
+minibuffer.
+
+@defun active-minibuffer-window
+This function returns the currently active minibuffer window, or
+@code{nil} if there is none.
 @end defun
 
-It is not correct to determine whether a given window is a minibuffer by
-comparing it with the result of @code{(minibuffer-window)}, because
-there can be more than one minibuffer window if there is more than one
-frame.
+It is not sufficient to determine whether a given window is the
+currently active minibuffer window by comparing it with the result of
+@code{(minibuffer-window)}, because there can be more than one
+minibuffer window if there is more than one frame.
 
 @defun minibuffer-window-active-p window
 This function returns non-@code{nil} if @var{window} is the currently
@@ -2439,9 +2444,9 @@ minibuffer, it scrolls this window.
 @end defvar
 
 @defun minibuffer-selected-window
-This function returns the window that was selected when the
-minibuffer was entered.  If selected window is not a minibuffer
-window, it returns @code{nil}.
+This function returns the window that was selected at the moment the
+minibuffer was entered.  If the currently selected window is not a
+minibuffer window, it returns @code{nil}.
 @end defun
 
 @defopt max-mini-window-height
diff --git a/etc/NEWS b/etc/NEWS
index 357d528924f..1166e81da03 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1814,6 +1814,11 @@ handle fitting a frame to its buffer individually.
 'drag-with-mode-line', 'snap-width', 'top-visible' and 'bottom-visible'
 allow to drag and resize frames with the mouse.
 
++++
+**** 'minibuffer' is now set to the default minibuffer window when
+initially specified as nil and is not reset to nil when initially
+specifying a minibuffer window.
+
 *** The new function 'frame-list-z-order' returns a list of all frames
 in Z (stacking) order.
 
diff --git a/src/frame.c b/src/frame.c
index ab801eec9c7..fe1709e6ede 100644
--- a/src/frame.c
+++ b/src/frame.c
@@ -5895,16 +5895,11 @@ or call the function `tool-bar-mode'.  */);
 #endif
 
   DEFVAR_KBOARD ("default-minibuffer-frame", Vdefault_minibuffer_frame,
-                 doc: /* Minibufferless frames use this frame's minibuffer.
-Emacs cannot create minibufferless frames unless this is set to an
-appropriate surrogate.
-
-Emacs consults this variable only when creating minibufferless
-frames; once the frame is created, it sticks with its assigned
-minibuffer, no matter what this variable is set to.  This means that
-this variable doesn't necessarily say anything meaningful about the
-current set of frames, or where the minibuffer is currently being
-displayed.
+                 doc: /* Minibuffer-less frames by default use this frame's minibuffer.
+Emacs consults this variable only when creating a minibuffer-less frame
+and no explicit minibuffer window has been specified for that frame via
+the `minibuffer' frame parameter.  Once such a frame has been created,
+setting this variable does not change that frame's previous association.
 
 This variable is local to the current terminal and cannot be buffer-local.  */);
 
diff --git a/src/window.c b/src/window.c
index ba86d73911f..f08979e1320 100644
--- a/src/window.c
+++ b/src/window.c
@@ -5833,7 +5833,7 @@ by this function.  This happens in an interactive call.  */)
 
 DEFUN ("minibuffer-selected-window", Fminibuffer_selected_window, Sminibuffer_selected_window, 0, 0, 0,
        doc: /* Return the window which was selected when entering the minibuffer.
-Returns nil, if selected window is not a minibuffer window.  */)
+Return nil if the selected window is not a minibuffer window.  */)
   (void)
 {
   if (minibuf_level > 0