master 9260904072d 2/3: Add documentation for 'switch-window' event

[Eli Zaretskii]

branch: master
commit 9260904072d01e4b0f585825bfbc077310c8a974
Author: Jared Finder <jared@finder.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Add documentation for 'switch-window' event
    
    * doc/lispref/commands.texi (Focus Events): Add
    documentation for the structure of 'switch-window' events.
    Make sure to be clear when referring to window system windows
    vs Emacs windows.
    * doc/lispref/windows.texi (Mouse Window Auto-selection):
    Adding cross-reference to "Focus Events".  (Bug#69915)
---
 doc/lispref/commands.texi | 66 +++++++++++++++++++++++++++++++++--------------
 doc/lispref/windows.texi  |  2 +-
 2 files changed, 48 insertions(+), 20 deletions(-)

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 4fe4969c0db..335a41dbb44 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -2303,15 +2303,34 @@ touch sequence after it is called.
 @subsection Focus Events
 @cindex focus event
 
+This section talks about both window systems and Emacs frames.  When
+talking about just ``frames'' or ``windows'', it refers to Emacs frames
+and Emacs windows.  When talking about window system windows, which are
+also Emacs frames, this section always says ``window system window''.
+
+@noindent
 Window systems provide general ways for the user to control which window
-gets keyboard input.  This choice of window is called the @dfn{focus}.
-When the user does something to switch between Emacs frames, that
-generates a @dfn{focus event}.  The normal definition of a focus event,
-in the global keymap, is to select a new frame within Emacs, as the user
-would expect.  @xref{Input Focus}, which also describes hooks related
-to focus events.
+system window, or Emacs frame, gets keyboard input.  This choice of
+window system window is called the @dfn{focus}.  When the user does
+something to switch between Emacs frames, that generates a @dfn{focus
+event}.  Emacs also generates focus events when using
+@var{mouse-autoselect-window} to switch between Emacs windows within
+Emacs frames.
+
+A focus event in the middle of a key sequence would garble the
+sequence.  So Emacs never generates a focus event in the middle of a key
+sequence.  If the user changes focus in the middle of a key
+sequence---that is, after a prefix key---then Emacs reorders the events
+so that the focus event comes either before or after the multi-event key
+sequence, and not within it.
 
-Focus events are represented in Lisp as lists that look like this:
+@heading Focus events for frames
+
+The normal definition of a focus event that switches frames, in the
+global keymap, is to select that new frame within Emacs, as the user
+would expect.  @xref{Input Focus}, which also describes hooks related to
+focus events for frames.  Focus events for frames are represented in
+Lisp as lists that look like this:
 
 @example
 (switch-frame @var{new-frame})
@@ -2321,19 +2340,28 @@ Focus events are represented in Lisp as lists that look 
like this:
 where @var{new-frame} is the frame switched to.
 
 Some X window managers are set up so that just moving the mouse into a
-window is enough to set the focus there.  Usually, there is no need
-for a Lisp program to know about the focus change until some other
-kind of input arrives.  Emacs generates a focus event only when the
-user actually types a keyboard key or presses a mouse button in the
-new frame; just moving the mouse between frames does not generate a
-focus event.
+frame is enough to set the focus there.  Usually, there is no need for a
+Lisp program to know about the focus change until some other kind of
+input arrives.  Emacs generates a focus event only when the user
+actually types a keyboard key or presses a mouse button in the new
+frame; just moving the mouse between frames does not generate a focus
+event.
 
-A focus event in the middle of a key sequence would garble the
-sequence.  So Emacs never generates a focus event in the middle of a key
-sequence.  If the user changes focus in the middle of a key
-sequence---that is, after a prefix key---then Emacs reorders the events
-so that the focus event comes either before or after the multi-event key
-sequence, and not within it.
+@heading Focus events for windows
+
+When @var{mouse-autoselect-window} is set, moving the mouse over a new
+window within a frame can also switch the selected window.  @xref{Mouse
+Window Auto-selection}, which describes the behavior for different
+values.  When the mouse is moved over a new window, a focus event for
+switching windows is generated.  Focus events for windows are
+reperesented in Lisp as lists that look like this:
+
+@example
+(select-window @var{new-window})
+@end example
+
+@noindent
+where @var{new-window} is the window switched to.
 
 @node Xwidget Events
 @subsection Xwidget events
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index b2c1b79780d..104420235df 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -6207,7 +6207,7 @@ The following option enables automatically selecting the 
window under
 the mouse pointer.  This accomplishes a policy similar to that of
 window managers that give focus to a frame (and thus trigger its
 subsequent selection) whenever the mouse pointer enters its
-window-system window (@pxref{Input Focus}).
+window-system window (@pxref{Input Focus}, @pxref{Focus Events}).
 
 @defopt mouse-autoselect-window
 If this variable is non-@code{nil}, Emacs will try to automatically