Subject: Re: bug#32990: 26.1.50; isearch-forward + t-m-m/mark-active doc

From: [email-masked] (Charles A. Roelli)
Date: Tue, 16 Oct 2018 20:57:13 +0200

> Date: Mon, 15 Oct 2018 18:02:16 +0300
> From: Eli Zaretskii <[email-masked]>
>
> Sounds like a good plan to me, thanks.
> 
> I wouldn't rename isearch-delete-char; instead, I'd explain that what
> it does is a kind of "undo", as you describe.

Ok, how about the following?

diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index 053603e..58a7658 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -99,10 +99,18 @@ Basic Isearch
 that customize this highlighting.  The current search string is also
 displayed in the echo area.
 
-  If you make a mistake typing the search string, type @key{DEL}.
-Each @key{DEL} cancels the last character of the search string.
-@xref{Error in Isearch}, for more about dealing with unsuccessful
-search.
+@cindex isearch input item
+@cindex input item, isearch
+@findex isearch-delete-char
+@kindex DEL @r{(Incremental search)}
+  If you make a mistake typing the search string, type @key{DEL}
+(@code{isearch-delete-char}).  Each @key{DEL} cancels the last input
+item entered during the search.  Emacs records a new @dfn{input item}
+whenever you type a command that changes the search string, the
+position of point, the success or failure of the search, the direction
+of the search, the position of the other end of the current search
+result, or the ``wrappedness'' of the search.  @xref{Error in
+Isearch}, for more about dealing with unsuccessful search.
 
 @cindex exit incremental search
 @cindex incremental search, exiting
@@ -283,14 +291,15 @@ Error in Isearch
 @code{isearch-fail}.
 
   At this point, there are several things you can do.  If your string
-was mistyped, you can use @key{DEL} to erase some of it and correct
-it, or you can type @kbd{M-e} and edit it.  If you like the place you
-have found, you can type @key{RET} to remain there.  Or you can type
-@kbd{C-g}, which removes from the search string the characters that
-could not be found (the @samp{T} in @samp{FOOT}), leaving those that
-were found (the @samp{FOO} in @samp{FOOT}).  A second @kbd{C-g} at
-that point cancels the search entirely, returning point to where it
-was when the search started.
+was mistyped, use @key{DEL} to cancel a previous input item
+(@pxref{Basic Isearch}), @kbd{C-M-w} to erase one character at a time,
+or @kbd{M-e} to edit it.  If you like the place you have found, you
+can type @key{RET} to remain there.  Or you can type @kbd{C-g}, which
+removes from the search string the characters that could not be found
+(the @samp{T} in @samp{FOOT}), leaving those that were found (the
+@samp{FOO} in @samp{FOOT}).  A second @kbd{C-g} at that point cancels
+the search entirely, returning point to where it was when the search
+started.
 
 @cindex quitting (in search)
 @kindex C-g @r{(Incremental search)}
diff --git a/lisp/isearch.el b/lisp/isearch.el
index 31571e1..40b0799 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -1956,11 +1956,14 @@ isearch-highlight-regexp
 
 
 (defun isearch-delete-char ()
-  "Discard last input item and move point back.
-Last input means the last character or the last isearch command
-that added or deleted characters from the search string,
-moved point, toggled regexp mode or case-sensitivity, etc.
-If no previous match was done, just beep."
+  "Undo last input item during a search.
+
+An input item is a command that pushes a new state of isearch (as
+recorded by the `isearch--state' structure) to `isearch-cmds'.
+Info node `Basic Isearch' explains when Emacs pushes a new
+isearch state.
+
+If no input items have been entered yet, just beep."
   (interactive)
   (if (null (cdr isearch-cmds))
       (ding)