From: Martin Rudalics <rudalics@gmx.at>
Date: Mon, 30 Oct 2017 18:43:29 +0000 (+0100)
Subject: Fix doc and doc-strings for minibuffer window related functions (Bug#28978)
X-Git-Tag: emacs-26.0.91~427^2
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=d10c9479ca4d873a8bd09bb63ae865b4a953d5c8;p=emacs.git

Fix doc and doc-strings for minibuffer window related functions (Bug#28978)

These fixes were suggested by Drew Adams.

* src/window.c (Fminibuffer_selected_window): Disambiguate
doc-string.
* doc/lispref/minibuf.texi (Intro to Minibuffers)
(Minibuffer Windows, Recursive Mini, Minibuffer Misc):  Avoid
the term "currently active minibuffer window".  Disambiguate
documentation of `minibuffer-selected-window'.
---

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index db69e7d8919..75dec13ab7c 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -59,15 +59,16 @@ boundary between the prompt and the actual text.
 
 @c See https://debbugs.gnu.org/11276
   The minibuffer's window is normally a single line; it grows
-automatically if the contents require more space.  Whilst it is
-active, you can explicitly resize it temporarily with the window
-sizing commands; it reverts to its normal size when the minibuffer is
-exited.  When the minibuffer is not active, you can resize it
-permanently by using the window sizing commands in the frame's other
-window, or dragging the mode line with the mouse.  (Due to details of
-the current implementation, for this to work @code{resize-mini-windows}
-must be @code{nil}.)  If the frame contains just a minibuffer, you can
-change the minibuffer's size by changing the frame's size.
+automatically if the contents require more space.  Whilst the minibuffer
+is active, you can explicitly resize its window temporarily with the
+window sizing commands; the window reverts to its normal size when the
+minibuffer is exited.  When the minibuffer is not active, you can resize
+its window permanently by using the window sizing commands in the
+frame's other window, or dragging the mode line with the mouse.  (Due to
+details of the current implementation, for this to work
+@code{resize-mini-windows} must be @code{nil}.)  If the frame contains
+just a minibuffer window, you can change its size by changing the
+frame's size.
 
   Use of the minibuffer reads input events, and that alters the values
 of variables such as @code{this-command} and @code{last-command}
@@ -2286,18 +2287,18 @@ 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.
+This function returns the window of the currently active minibuffer, or
+@code{nil} if there is no active minibuffer.
 @end defun
 
-It is not sufficient to determine whether a given window is the
-currently active minibuffer window by comparing it with the result of
+It is not sufficient to determine whether a given window shows the
+currently active 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.
 
 @defun minibuffer-window-active-p window
-This function returns non-@code{nil} if @var{window} is the currently
-active minibuffer window.
+This function returns non-@code{nil} if @var{window} shows the currently
+active minibuffer.
 @end defun
 
 The following two options control whether minibuffer windows are resized
@@ -2379,14 +2380,14 @@ returns zero.
 
 @defopt enable-recursive-minibuffers
 If this variable is non-@code{nil}, you can invoke commands (such as
-@code{find-file}) that use minibuffers even while the minibuffer window
-is active.  Such invocation produces a recursive editing level for a new
+@code{find-file}) that use minibuffers even while the minibuffer is
+active.  Such invocation produces a recursive editing level for a new
 minibuffer.  The outer-level minibuffer is invisible while you are
 editing the inner one.
 
-If this variable is @code{nil}, you cannot invoke minibuffer
-commands when the minibuffer window is active, not even if you switch to
-another window to do it.
+If this variable is @code{nil}, you cannot invoke minibuffer commands
+when the minibuffer is active, not even if you switch to another window
+to do it.
 @end defopt
 
 @c Emacs 19 feature
@@ -2444,8 +2445,8 @@ minibuffer, it scrolls this window.
 @end defvar
 
 @defun minibuffer-selected-window
-This function returns the window that was selected at the moment the
-minibuffer was entered.  If the currently selected window is not a
+This function returns the window that was selected just before the
+minibuffer window was selected.  If the selected window is not a
 minibuffer window, it returns @code{nil}.
 @end defun
 
diff --git a/src/window.c b/src/window.c
index f08979e1320..9bb2c43a698 100644
--- a/src/window.c
+++ b/src/window.c
@@ -5832,7 +5832,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.
+       doc: /* Return window selected just before minibuffer window was selected.
 Return nil if the selected window is not a minibuffer window.  */)
   (void)
 {