Re: Suggestion: Add discussion of input focus handling to select-window; add select-frame-window

[Eli Zaretskii <eliz@gnu.org>]

> From: Robert Weiner <rsw@gnu.org>
> Date: Sat, 16 Dec 2017 11:11:43 -0500
> Cc: Eli Zaretskii <eliz@gnu.org>, martin rudalics <rudalics@gmx.at>, emacs-devel <emacs-devel@gnu.org>
> 
> So if I programmatically select-window in a frame that does not have or gain
> input focus, will most editing take place there?

That's a meaningless question, IMO, because "editing takes place"
means interactive editing, and that only happens _after_ your command
finishes its job, and Emacs returns to the main command loop.  And the
manual says "_most_ editing" for a reason.

> Maybe there is another as yet undefined idea in there of interactive
> window selection where input focus does shift.

I think you are interpreting the ELisp manual too literally.  It is
not meant to describe how the Emacs internals work, certainly not in
all cases.  The text which describes what it means for the window to
be "selected" is intended to make the _notion_ of the selected window
clear enough to continue describing the features which manipulate the
selected window, nothing more, nothing less.  You should not interpret
that text as an exhaustive and mathematically rigorous _definition_ of
what a selected window is, and even less when Emacs decides on its own
to select a different window.  The simplest example is the minibuffer
window.

> At the very least, the basic sequence of calls to select an arbitrary window
> for user editing should be explained both here and in the select-window function,
> since someone thinking about windows and buffers isn't likely to reference
> frame-related documentation even though input focus is a frame-related concept.

And they don't need to look up frame- and focus-related documentation,
as long as they only need to select a window.  What you needed is to
select another frame, select another window on that frame, and make
sure that frame is at the top of the z-order.  That has very little to
do with selecting a window, and much more to do with frames and input
focus -- and those topics are described in the docs under their proper
subjects.

I could support some gentle notes in the ELisp manual's node
"Selecting Windows", where it already mentions frames.  But doc
strings are inappropriate for references to almost unrelated subjects,
nor for general descriptions of complex topics.