[Emacs-diffs] emacs-26 c3b6742: Improve documentation of selecting windows

[Eli Zaretskii]

branch: emacs-26
commit c3b6742b3fb7459af64eec4986837c4714636c51
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of selecting windows
    
    * doc/lispref/windows.texi (Basic Windows, Selecting Windows):
    Clarify what selecting a window means for keyboard input, and that
    input focus may need to be considered when selecting windows on
    other frames.  See
    http://lists.gnu.org/archive/html/emacs-devel/2017-12/msg00372.html
    for more details.
---
 doc/lispref/windows.texi | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 07c8f27..d73b410 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -125,11 +125,13 @@ including for the case where @var{object} is a deleted 
window.
 as @dfn{selected within the frame}.  For the selected frame, that
 window is called the @dfn{selected window}---the one in which most
 editing takes place, and in which the cursor for selected windows
-appears (@pxref{Cursor Parameters}).  The selected window's buffer is
-usually also the current buffer, except when @code{set-buffer} has
-been used (@pxref{Current Buffer}).  As for non-selected frames, the
-window selected within the frame becomes the selected window if the
-frame is ever selected.  @xref{Selecting Windows}.
+appears (@pxref{Cursor Parameters}).  Keyboard input that inserts or
+deletes text is also normally directed to this window.   The selected
+window's buffer is usually also the current buffer, except when
address@hidden has been used (@pxref{Current Buffer}).  As for
+non-selected frames, the window selected within the frame becomes the
+selected window if the frame is ever selected.  @xref{Selecting
+Windows}.
 
 @defun selected-window
 This function returns the selected window (which is always a live
@@ -1726,7 +1728,7 @@ windows.
 
 @defun select-window window &optional norecord
 This function makes @var{window} the selected window and the window
-selected within its frame (@pxref{Basic Windows}) and selects that
+selected within its frame (@pxref{Basic Windows}), and selects that
 frame.  It also makes @var{window}'s buffer (@pxref{Buffers and
 Windows}) current and sets that buffer's value of @code{point} to the
 value of @code{window-point} (@pxref{Window Point}) in @var{window}.
@@ -1743,6 +1745,11 @@ next time.  If @var{norecord} is address@hidden, such 
updates are
 usually not performed.  If, however, @var{norecord} equals the special
 symbol @code{mark-for-redisplay}, the additional actions mentioned above
 are omitted but @var{window} will be nevertheless updated.
+
+Note that sometimes selecting a window is not enough to show it, or
+make its frame the top-most frame on display: you may also need to
+raise the frame or make sure input focus is directed to that frame.
address@hidden Focus}.
 @end defun
 
 @cindex select window hook