From c3adbc88a00f2c8fa773d46bfcf4571c9ebde8fb Mon Sep 17 00:00:00 2001 From: "Charles A. Roelli" Date: Thu, 25 Oct 2018 21:01:53 +0200 Subject: [PATCH] Improve 'isearch-delete-char' documentation (Bug#32990) * doc/emacs/search.texi (Basic Isearch): Index 'isearch-delete-char', its keybinding and the isearch "input item" concept, and define the latter. (Error in Isearch): Clarify the different uses of DEL and C-M-w during isearch. * lisp/isearch.el (isearch-delete-char): Correct its documentation and link to the Info node '(emacs)Basic Isearch' which explains less technically how this function works in everyday usage. --- doc/emacs/search.texi | 33 +++++++++++++++++++++------------ lisp/isearch.el | 13 ++++++++----- 2 files changed, 29 insertions(+), 17 deletions(-) diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index 053603e54fc..58a76580d76 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -99,10 +99,18 @@ text that matches the search string---using the @code{isearch} face 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 @@ string that failed to match is highlighted using the face @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 31571e11cd5..b180e63d8e8 100644 --- a/lisp/isearch.el +++ b/lisp/isearch.el @@ -1956,11 +1956,14 @@ and reads its face argument using `hi-lock-read-face-name'." (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 the result of a command that pushes a new state +of isearch (as recorded by the `isearch--state' structure) to +`isearch-cmds'. Info node `(emacs)Basic Isearch' explains when +Emacs records a new input item. + +If no input items have been entered yet, just beep." (interactive) (if (null (cdr isearch-cmds)) (ding) -- 2.39.5