From d983e080e027bd7b680b1e40ccfa0c71d6a3cd94 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Thu, 13 Jan 2022 16:40:28 +0200
Subject: [PATCH] Improve documentation of 'isearch-emoji-by-name'

* lisp/isearch.el (isearch-menu-bar-map, isearch-emoji-by-name):
Fix wording of documentation.

* etc/NEWS: Fix wording of the 'isearch-emoji-by-name' entry.

* doc/emacs/search.texi (Special Isearch): Fix wording of the
documentation of 'isearch-emoji-by-name'; move it out of the
enumeration that deals with non-ASCII characters in general.
---
 doc/emacs/search.texi | 18 ++++++++++--------
 etc/NEWS              |  6 +++---
 lisp/isearch.el       | 10 +++++-----
 3 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index e29c2c91af4..397bddbe995 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -443,14 +443,6 @@ a Unicode name or code-point in hex.  This adds the specified
 character into the search string, similar to the usual
 @code{insert-char} command (@pxref{Inserting Text}).
 
-@item
-@findex isearch-emoji-by-name
-@kindex C-x 8 e RET @r{(Incremental Search)}
-Type @kbd{C-x 8 e @key{RET}} (@code{isearch-emoji-by-name}), followed
-by the CLDR short name of an Emoji (for example, @samp{smiling face}
-or @samp{heart with arrow}).  This adds the specified Emoji into the
-search string.
-
 @item
 @kindex C-^ @r{(Incremental Search)}
 @findex isearch-toggle-input-method
@@ -481,6 +473,16 @@ character to the search string using an input method, and
 automatically disable the input method afterwards.
 @end itemize
 
+@findex isearch-emoji-by-name
+@kindex C-x 8 e RET @r{(Incremental Search)}
+  You can also include Emoji sequences in the search string.  Type
+@w{@kbd{C-x 8 e @key{RET}}} (@code{isearch-emoji-by-name}), followed
+by the Unicode name of an Emoji (for example, @kbd{smiling face} or
+@kbd{heart with arrow}).  This adds the specified Emoji to the search
+string.  If you don't know the name of the Emoji you want to search
+for, you can use @kbd{C-x 8 e l} (@code{emoji-list}) and @kbd{C-x 8 e
+d} (@code{emoji-describe}) (@pxref{Input Methods}).
+
 @kindex M-s o @r{(Incremental Search)}
 @findex isearch-occur
   Typing @kbd{M-s o} in incremental search invokes
diff --git a/etc/NEWS b/etc/NEWS
index 0cd4322a5e9..06a6886ebf6 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -407,9 +407,9 @@ the *Completions* buffer.
 +++
 *** New command 'isearch-emoji-by-name'.
 It is bound to 'C-x 8 e RET' during an incremental search.  The
-command accepts the CLDR short name of an Emoji (for example, "smiling
-face" or "heart with arrow"), with minibuffer completion, and inserts
-the Emoji character into the search string.
+command accepts the Unicode name of an Emoji (for example, "smiling
+face" or "heart with arrow"), like 'C-x 8 e e', with minibuffer
+completion, and adds the Emoji into the search string.
 
 ** New minor mode 'glyphless-display-mode'.
 This allows an easy way to toggle seeing all glyphless characters in
diff --git a/lisp/isearch.el b/lisp/isearch.el
index 5bb11aab839..833d031c562 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -760,7 +760,7 @@ This is like `describe-bindings', but displays only Isearch keys."
     ["Search for char by name" isearch-char-by-name
      :help "Search for character by name"]
     ["Search for Emoji by name" isearch-emoji-by-name
-     :help "Search for Emoji by name"]
+     :help "Search for Emoji by its Unicode name"]
     "---"
     ["Toggle input method" isearch-toggle-input-method
      :help "Toggle input method for search"]
@@ -2751,10 +2751,10 @@ With argument, add COUNT copies of the character."
 						      string ""))))))))
 
 (defun isearch-emoji-by-name (&optional count)
-  "Read an Emoji name and add it to the search string.
-The command accepts CLDR short names like 'smiling face' or
-'heart with arrow' and completion is available.  With argument,
-add COUNT copies of the Emoji."
+  "Read an Emoji name and add it to the search string COUNT times.
+COUNT (interactively, the prefix argument) defaults to 1.
+The command accepts Unicode names like \"smiling face\" or
+\"heart with arrow\", and completion is available."
   (interactive "p")
   (with-isearch-suspended
    (let ((emoji (with-temp-buffer
-- 
2.39.2