From 3e8cdc404fb884f0be473fe2785c3b041c1129fd Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Mon, 2 Nov 2020 19:49:32 +0200
Subject: [PATCH] Improve documentation of a recent commit

* lisp/international/mule-cmds.el (transient-input-method): Doc
fix.  Add :version tag.
(transient-input-method): Doc fix.

* etc/NEWS:
* doc/emacs/mule.texi (Select Input Method): Fix wording of the
last change.
---
 doc/emacs/mule.texi             | 22 +++++++++++++---------
 etc/NEWS                        | 13 ++++++++-----
 lisp/international/mule-cmds.el |  8 +++++---
 3 files changed, 26 insertions(+), 17 deletions(-)

diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi
index d4ad1d6d5e2..2fca4a544ca 100644
--- a/doc/emacs/mule.texi
+++ b/doc/emacs/mule.texi
@@ -579,8 +579,8 @@ Enable or disable use of the selected input method (@code{toggle-input-method}).
 Select a new input method for the current buffer (@code{set-input-method}).
 
 @item C-x \ @var{method} @key{RET}
-Temporarily enable the selected transient input method, and
-automatically disable it after inserting a single character
+Temporarily enable the selected transient input method ; it will be
+automatically disabled after inserting a single character
 (@code{transient-input-method}).
 
 @item C-h I @var{method} @key{RET}
@@ -682,13 +682,17 @@ including the string that stands for it in the mode line.
 
 @findex transient-input-method
 @kindex C-x \
-  To insert only a single character using a transient input method you
-can first select a transient input method by typing @kbd{C-u C-x \}.
-Then typing @kbd{C-x \} (@code{transient-input-method}) will
-temporarily enable the selected transient input method, and disable it
-automatically after using the activated input method to insert
-a single character.  This is useful to insert a character from input
-methods with rare Unicode characters.
+  Sometimes it can be convenient to enable an input method
+@dfn{transiently}, for inserting only a single character.  Typing
+@kbd{C-x \} (@code{transient-input-method}) will temporarily enable an
+input method, let you insert a single character using the input method
+rules, and then automatically disable the input method.  If no
+transient input method was selected yet, @kbd{C-x \} will prompt you
+for an input method; subsequent invocations of this command will
+enable the selected transient input method.  To select a different
+transient input method, type @kbd{C-u C-x \}.  You can select a
+transient method that is different from the input method which you
+selected using @kbd{C-u C-\}.
 
 @node Coding Systems
 @section Coding Systems
diff --git a/etc/NEWS b/etc/NEWS
index 4ddb1924935..e11effc9e80 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -624,11 +624,14 @@ The menu bar "Help" menu now has a "Show Recent Inputs" item under the
 ** Input methods
 
 +++
-*** 'C-x \' temporarily enables a transient input method.
-'C-u C-x \' can be used to select a transient input method, e.g.
-'C-u C-x \ compose RET' selects the 'compose' input method.  Then typing
-'C-x \ 1 2' will insert the character '½', and disable the input method
-afterwards.
+*** Emacs now supports "transient" input methods.
+A transient input method is enabled for inserting a single character,
+and is then automatically disabled.  'C-x \' temporarily enables the
+selected transient input method.  Use 'C-u C-x \' to select a
+transient input method (which can be different from the input method
+enabled by 'C-\').  For example, 'C-u C-x \ compose RET' selects the
+'compose' input method; then typing 'C-x \ 1 2' will insert the
+character '½', and disable the 'compose' input method afterwards.
 
 ---
 *** New input method 'compose' based on X Multi_key sequences.
diff --git a/lisp/international/mule-cmds.el b/lisp/international/mule-cmds.el
index c5a01451637..dc435d9b170 100644
--- a/lisp/international/mule-cmds.el
+++ b/lisp/international/mule-cmds.el
@@ -1347,13 +1347,14 @@ This is the input method activated automatically by the command
 
 (defcustom transient-input-method nil
   "Default transient input method.
-This is the input method activated automatically by the command
+This is the input method activated by the command
 `transient-input-method' (\\[transient-input-method])."
   :link  '(custom-manual "(emacs)Input Methods")
   :group 'mule
   :type '(choice (const nil)
                  mule-input-method-string)
-  :set-after '(current-language-environment))
+  :set-after '(current-language-environment)
+  :version "28.1")
 
 (put 'input-method-function 'permanent-local t)
 
@@ -1531,7 +1532,8 @@ To deactivate it programmatically, use `deactivate-input-method'."
   "Non-nil inside `toggle-input-method'.")
 
 (defun transient-input-method (&optional arg interactive)
-  "Enable transient input method for the current buffer."
+  "Enable a transient input method for the current buffer.
+If `transient-input-method' was not yet defined, prompt for it."
   (interactive "P\np")
   (when (or arg (not transient-input-method))
     (let* ((default (or (car input-method-history) default-input-method))
-- 
2.39.2