[Emacs-diffs] emacs-26 4189d0e: Fix minibuffer window related docs and strings (Bug#28978)

[Martin Rudalics]

branch: emacs-26
commit 4189d0ef7bf935fb8e6ab941e93d591be654ddac
Author: Martin Rudalics <address@hidden>
Commit: Martin Rudalics <address@hidden>

    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.
---
 doc/lispref/frames.texi  | 11 +++++++++--
 doc/lispref/minibuf.texi | 45 +++++++++++++++++++++++++--------------------
 etc/NEWS                 |  5 +++++
 src/frame.c              | 15 +++++----------
 src/window.c             |  2 +-
 5 files changed, 45 insertions(+), 33 deletions(-)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index ad85341..5ea7125 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
address@hidden, Emacs will try to set it to the minibuffer window of
address@hidden (@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
address@hidden  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 address@hidden, 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 1ece899..db69e7d 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.
 
address@hidden active-minibuffer-window
-This function returns the currently active minibuffer window, or
address@hidden if there is none.
address@hidden 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
address@hidden 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 address@hidden if @var{window} is a minibuffer
-window.
address@hidden defaults to the selected window.
+window.  @var{window} defaults to the selected window.
address@hidden defun
+
+The following function returns the window showing the currently active
+minibuffer.
+
address@hidden active-minibuffer-window
+This function returns the currently active minibuffer window, or
address@hidden 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
address@hidden(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 address@hidden 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 357d528..1166e81 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 ab801ee..fe1709e 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 ba86d73..f08979e 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