(Input Focus): Add documentation for `select-frame-set-input-focus'.

Replace refs to non-existent `switch-frame' with `select-frame'.
Minor corrections and tidying up of text-only terminal stuff.

From Alan Mackenzie.

2 files changed, 24 insertions, 8 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index dfb558463fe..f8f492777cc 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2004-07-04  Alan Mackenzie  <acm@muc.de>
+
+        * frames.texi (Input Focus): Add documentation for
+        `select-frame-set-input-focus'.  Replace refs to non-existent
+        `switch-frame' with `select-frame'.  Minor corrections and tidying
+        up of text-only terminal stuff.
+
 2004-07-02  Richard M. Stallman  <rms@gnu.org>
 
         * files.texi (Saving Buffers): Cleanup write-contents-function.
diff --git a/lispref/frames.texi b/lispref/frames.texi
index fe3bca7c119..24540f471f8 100644
--- a/lispref/frames.texi
+++ b/lispref/frames.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2004
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/frames
@@ -996,19 +996,28 @@ This function returns the selected frame.
 Some window systems and window managers direct keyboard input to the
 window object that the mouse is in; others require explicit clicks or
 commands to @dfn{shift the focus} to various window objects.  Either
-way, Emacs automatically keeps track of which frame has the focus.
+way, Emacs automatically keeps track of which frame has the focus.  To
+switch to a different frame from a lisp function, call
+@code{select-frame-set-input-focus}.
 
 Lisp programs can also switch frames ``temporarily'' by calling the
 function @code{select-frame}.  This does not alter the window system's
 concept of focus; rather, it escapes from the window manager's control
 until that control is somehow reasserted.
 
-When using a text-only terminal, only the selected terminal frame is
-actually displayed on the terminal.  @code{switch-frame} is the only way
-to switch frames, and the change lasts until overridden by a subsequent
-call to @code{switch-frame}.  Each terminal screen except for the
-initial one has a number, and the number of the selected frame appears
-in the mode line before the buffer name (@pxref{Mode Line Variables}).
+When using a text-only terminal, only one frame can be displayed at a
+time on the terminal, so @code{select-frame} actually displays the
+newly selected frame.  This frame remains displayed until a subsequent
+call to @code{select-frame} or @code{select-frame-set-input-focus}.
+Each terminal frame has a number which appears in the mode line before
+the buffer name (@pxref{Mode Line Variables}).
+
+@defun select-frame-set-input-focus frame
+This function makes @var{frame} the selected frame, raises it (should
+it happen to be obscured by other frames) and tries to give it the X
+server's focus.  On a text-only terminal, the new frame gets displayed
+on the entire terminal screen.
+@end defun
 
 @c ??? This is not yet implemented properly.
 @defun select-frame frame