; Move documentation for multiple-terminals-merge-keyboards.

doc/emacs/commands.texi

@@ -79,6 +79,10 @@ and @kbd{C-M-l}.  If you have this problem, you can either customize
 your window manager to not block those keys, or rebind the
 affected Emacs commands (@pxref{Customization}).
 
+  If one Emacs frame is doing minibuffer prompting and other Emacs
+frames appear to ignore input, you may wish to disable single-keyboard
+mode.  @xref{Multiple Displays}.
+
 @cindex input event
   Simple characters and control characters, as well as certain
 non-keyboard inputs such as mouse clicks, are collectively referred to

doc/emacs/frames.texi

@@ -1014,6 +1014,37 @@ Create a new frame on monitor @var{monitor} whose screen area is
 a part of the current display.
 @end table
 
+@subsection Single-keyboard mode
+@cindex single-keyboard mode
+
+  Each display has an associated keyboard.  Normally, Emacs assumes that
+these keyboards are physically distinct, so that someone could be typing
+on one keyboard and someone else typing on another, into different
+frames on different terminals.  In certain situations, however, Emacs
+enters single-keyboard mode, in which input from all but one keyboard is
+blocked.  This prevents keys typed on one keyboard from interfering with
+an operation started on another keyboard.  The main operation to which
+this applies is entering a recursive edit (@pxref{Recursive Edit}),
+which includes all minibuffer prompting (@pxref{Basic Minibuffer}).
+
+  Single-keyboard mode can be inconvenient when there are distinct
+displays and so distinct keyboards, but only one user and one physical
+keyboard in control of Emacs.  This can happen with X forwarding: with a
+remote Emacs daemon and multiple frames created with a command like
+@w{@code{ssh -X daemon-host emacsclient -c}}, then from the remote Emacs
+daemon's point of view there is one terminal and one keyboard per
+@w{@code{ssh -X daemon-host}} command invoked, but in fact a single
+local X server displays all frames, and there is just one physical
+keyboard.
+
+@vindex multiple-terminals-merge-keyboards
+  In this situation, you may prefer to have the different frames behave
+as though they had been created with @kbd{C-x 5 2} (@pxref{Creating
+Frames}).  In that case, starting a recursive edit in one frame does not
+mean that keyboard input into other frames is blocked.  Customize the
+variable @code{multiple-terminals-merge-keyboards} to a non-@code{nil}
+value to achieve this.
+
 @node Frame Parameters
 @section Frame Parameters
 @vindex default-frame-alist

doc/emacs/misc.texi

@@ -2044,7 +2044,9 @@ called @command{emacsclient}.
 
   You can also force @command{emacsclient} to open a new frame on a
 graphical display using the @samp{-c} option, or on a text terminal
-using the @samp{-t} option.  @xref{emacsclient Options}.
+using the @samp{-t} option.  @xref{emacsclient Options}.  If you use
+@samp{-c} to open multiple frames using X forwarding you may wish to
+disable single-keyboard mode.  @xref{Multiple Displays}.
 
   If you are running on a single text terminal, you can switch between
 @command{emacsclient}'s shell and the Emacs server using one of two
@@ -3054,6 +3056,9 @@ visiting files and all.  But this could have surprising effects (such as
 stack overflow) from time to time.  So remember to exit or abort the
 recursive edit when you no longer need it.
 
+  Recursive edits normally enable single-keyboard mode.  @xref{Multiple
+Displays}.
+
   In general, we try to minimize the use of recursive editing levels in
 GNU Emacs.  This is because they constrain you to go back in a
 particular order---from the innermost level toward the top level.  When

src/keyboard.c

@@ -14451,36 +14451,10 @@ function is called to remap that sequence.  */);
   DEFVAR_BOOL ("multiple-terminals-merge-keyboards",
 	       multiple_terminals_merge_keyboards,
     doc: /* If non-nil, treat different terminals' keyboards as less isolated.
-
-Each terminal displaying Emacs frames has an associated keyboard.
-Normally, Emacs assumes that these keyboards are physically
-distinct, so that someone could be typing on one keyboard and
-someone else typing on another, into different frames on different
-terminals.  In certain situations, however, Emacs enters
-single-keyboard mode, in which input from all but one keyboard is
-blocked.  This prevents keys typed on one keyboard from interfering
-with an operation started on another keyboard.  The main operation
-to which this applies is entering a recursive edit, which includes
-all minibuffer prompting.
-
-Single-keyboard mode can be inconvenient when there are distinct
-terminals and so distinct keyboards, but only one user and one
-physical keyboard in control of Emacs.  This can happen with X
-forwarding: with a remote Emacs daemon and multiple frames created
-with a command like `ssh -X daemon-host emacsclient -c', then from
-the remote Emacs daemon's point of view there is one terminal and
-one keyboard per `ssh -X daemon-host' command invoked, but in fact a
-single local X server displays all frames, and there is just one
-physical keyboard.  In this situation, you may prefer to have the
-different frames behave as though they had been created with
-\\[make-frame-command].  In that case, starting a recursive edit in \
-one frame does
-not mean that keyboard input into other frames is blocked.
-
-If this option is non-nil, Emacs will not enter single-keyboard
-mode when entering a recursive edit.  It will still enter
-single-keyboard mode in certain other cases where doing so is
-necessary for the operation to work at all.  */);
+If this option is non-nil, Emacs will not enter single-keyboard mode
+when entering a recursive edit.  It will still enter single-keyboard
+mode in certain other cases where doing so is necessary for the
+operation to work at all.  */);
   multiple_terminals_merge_keyboards = false;
 
   pdumper_do_now_and_after_load (syms_of_keyboard_for_pdumper);