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.

2 files changed, 34 insertions, 22 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