Improve documentation of native input methods

* doc/emacs/mule.texi (International, Input Methods)
(Unibyte Mode): Document user-level features of native input
methods.

1 files changed, 38 insertions, 8 deletions

diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi
index 09fedb7f9f2..92e055300e1 100644
--- a/doc/emacs/mule.texi
+++ b/doc/emacs/mule.texi
@@ -50,13 +50,14 @@ others.
 
 @item
 You can insert non-@acronym{ASCII} characters or search for them.  To do that,
-you can specify an input method (@pxref{Select Input Method}) suitable
+you can specify an Emacs input method (@pxref{Select Input Method}) suitable
 for your language, or use the default input method set up when you choose
 your language environment.  If
 your keyboard can produce non-@acronym{ASCII} characters, you can select an
 appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs
-will accept those characters.  Latin-1 characters can also be input by
-using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}.
+will accept those characters.  On graphical displays, modern systems
+typically provide their native input methods, and Latin-1 characters
+can also be input by using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}.
 
 With the X Window System, your locale should be set to an appropriate
 value to make sure Emacs interprets keyboard input correctly; see
@@ -449,10 +450,13 @@ for that key.
 
 @cindex input methods
   An @dfn{input method} is a kind of character conversion designed
-specifically for interactive input.  In Emacs, typically each language
-has its own input method; sometimes several languages that use the same
-characters can share one input method.  A few languages support several
-input methods.
+specifically for interactive input.  This section describes input
+methods that come with Emacs; for native input methods provided by the
+underlying OS, @pxref{Unibyte Mode}.
+
+  In Emacs, typically each language has its own input method;
+sometimes several languages that use the same characters can share one
+input method.  A few languages support several input methods.
 
   The simplest kind of input method works by mapping @acronym{ASCII} letters
 into another alphabet; this allows you to use one other alphabet
@@ -1798,12 +1802,38 @@ as @code{xterm}, you can arrange for Meta to be converted to @key{ESC}
 and still be able to type 8-bit characters present directly on the
 keyboard or using @key{Compose} or @key{AltGr} keys.  @xref{User Input}.
 
+@cindex input methods, native
+@cindex XIM, X Input Methods
+@cindex GTK input methods
+Many modern systems provide @dfn{native input methods} for many
+languages whose characters don't have keyboard keys assigned to them.
+If Emacs was built with support for these native input methods, you
+can activate such an input method and type the characters they
+support.  How to activate and use these input methods depends on the
+system and the input method, and will not be described here; see your
+system documentation.  Here we describe some Emacs facilities to
+control the use of the native input methods.
+
+@vindex x-gtk-use-native-input
+In Emacs built with the GTK toolkit, the variable
+@code{x-gtk-use-native-input} controls whether Emacs should receive
+characters produced by GTK input methods.  If the value is @code{nil},
+the default, Emacs uses the X input methods (@acronym{XIM}), otherwise
+it uses the GTK input methods.  The @code{useXIM} X resource controls
+whether to use @acronym{XIM}, and @code{inputStyle} X resource
+controls the display on X of preview text generated by the native
+input methods; @pxref{Table of Resources}.
+
+On MS-Windows, Emacs supports native inputs methods provided by
+@acronym{IMM}, the Input Method Manager; but that can be turned off if
+needed; @pxref{Windows Keyboard}.
+
 @cindex @code{iso-transl} library
 @cindex compose character
 @cindex dead character
 @item
 You can use the key @kbd{C-x 8} as a compose-character prefix for
-entry of non-@acronym{ASCII} Latin-1 and a few other printing
+entry of non-@acronym{ASCII} Latin-1 and other printing
 characters.  @kbd{C-x 8} is good for insertion (in the minibuffer as
 well as other buffers), for searching, and in any other context where
 a key sequence is allowed.