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

From: [email-masked] (Charles A. Roelli)
Date: Sun, 14 Oct 2018 21:53:31 +0200

> Date: Tue, 09 Oct 2018 21:21:02 +0300
> From: Eli Zaretskii <[email-masked]>
>
> > Ok, that would be better than duplicating all the details in both the
> > function documentation and the manual.  I will prepare a patch.
> 
> Thanks!

This line of isearch-forward's current docstring points to several
issues which make me uncomfortable changing or deleting it yet:

  Type DEL to cancel last input item from end of search string.

(DEL is the binding for "isearch-delete-char").

"Last input" is defined by the documentation of "isearch-delete-char"
as "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.".

This definition of "last input" is not in the manual, and DEL is never
advertised to be capable of canceling regexp mode or case-sensitivity
toggling.  DEL is only advertised as being capable of "canceling the
last character of the search string" (in node "Basic Isearch") and
"canceling some C-s characters" (in node "Repeat Isearch").

For example, from emacs -Q, M-< C-s buffer M-r DEL deletes the "r" off
the search string, instead of "canceling the last input item", which I
understand should be the "M-r" regexp mode toggling.

To make matters more complicated, DEL /sometimes/ does cancel the
"last input" of a search: for example, if you have some text on your
kill ring, C-s C-y DEL undoes the yanking of the string into the
search.  (This is surprisingly sophisticated to me, and, I think,
something to document better.)

All of this makes it sound as if "isearch-delete-char" is badly named:
it is a wrapper around "isearch-pop-state", and seems to be a sort of
general (but incomplete) "undo" command for ISEARCH.  Maybe we should
name it differently and even provide a more intuitive binding for it
(on the master branch).  Its name also clashes with
"isearch-del-char".

Thus, some first steps for the emacs-26 branch could be to:

  . correct the definition of "last input item" as mentioned in the
    documentation of "isearch-delete-char"

  . name, index and fully explain "isearch-delete-char" in the Emacs
    manual

  . mention in more places how and when to use "isearch-delete-char"

If anybody can explain more about "isearch-delete-char", please do!