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

classic Classic list List threaded Threaded
40 messages Options
12
Reply | Threaded
Open this post in threaded view
|

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

Charles A. Roelli
Another small change for emacs-26:

diff --git a/lisp/isearch.el b/lisp/isearch.el
index 3725779..7833a7b 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -719,6 +719,10 @@ isearch-forward
 If you try to exit with the search string still empty, it invokes
  nonincremental search.
 
+Exiting pushes the mark where point was before the search
+started, unless `transient-mark-mode' is on and the mark is
+active.
+
 Type \\[isearch-toggle-case-fold] to toggle search case-sensitivity.
 Type \\[isearch-toggle-invisible] to toggle search in invisible text.
 Type \\[isearch-toggle-regexp] to toggle regular-expression mode.


This behavior is already documented in the manual node "Basic
Isearch".



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> Date: Mon, 08 Oct 2018 19:58:15 +0200
> From: [hidden email] (Charles A. Roelli)
>
> Another small change for emacs-26:
>
> diff --git a/lisp/isearch.el b/lisp/isearch.el
> index 3725779..7833a7b 100644
> --- a/lisp/isearch.el
> +++ b/lisp/isearch.el
> @@ -719,6 +719,10 @@ isearch-forward
>  If you try to exit with the search string still empty, it invokes
>   nonincremental search.
>  
> +Exiting pushes the mark where point was before the search
> +started, unless `transient-mark-mode' is on and the mark is
> +active.
> +

Are you sure this is important to say there?  The doc string of that
function is already way beyond annoyingly long.

I'd actually encourage the opposite trend: make the doc string
shorter, and tell users to read the manual for more details.



Reply | Threaded
Open this post in threaded view
|

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

Charles A. Roelli
> Date: Mon, 08 Oct 2018 23:07:59 +0300
> From: Eli Zaretskii <[hidden email]>
> CC: [hidden email]
>
> Are you sure this is important to say there?  The doc string of that
> function is already way beyond annoyingly long.

It is important, but see below.

> I'd actually encourage the opposite trend: make the doc string
> shorter, and tell users to read the manual for more details.

Ok, that would be better than duplicating all the details in both the
function documentation and the manual.  I will prepare a patch.



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> Date: Tue, 09 Oct 2018 20:14:34 +0200
> From: [hidden email] (Charles A. Roelli)
> CC: [hidden email]
>
> > I'd actually encourage the opposite trend: make the doc string
> > shorter, and tell users to read the manual for more details.
>
> Ok, that would be better than duplicating all the details in both the
> function documentation and the manual.  I will prepare a patch.

Thanks!



Reply | Threaded
Open this post in threaded view
|

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

Charles A. Roelli
> Date: Tue, 09 Oct 2018 21:21:02 +0300
> From: Eli Zaretskii <[hidden email]>
>
> > 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!



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> Date: Sun, 14 Oct 2018 21:53:31 +0200
> From: [hidden email] (Charles A. Roelli)
> CC: [hidden email]
>
> 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"

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.



Reply | Threaded
Open this post in threaded view
|

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

Charles A. Roelli
> Date: Mon, 15 Oct 2018 18:02:16 +0300
> From: Eli Zaretskii <[hidden email]>
>
> 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)



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> Date: Tue, 16 Oct 2018 20:57:13 +0200
> From: [hidden email] (Charles A. Roelli)
> CC: [hidden email]
>
> Ok, how about the following?

LGTM, with 2 comments:

>  (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

I think you meant to say that "An input item is the result of a
command that pushes a new state ...".  Right?

> +Info node `Basic Isearch' explains when Emacs pushes a new
> +isearch state.

It is better to use `(emacs)Basic Search' as a link to the manual;
that's what we do elsewhere.

Thanks.



Reply | Threaded
Open this post in threaded view
|

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

Charles A. Roelli
> Date: Sat, 20 Oct 2018 12:59:48 +0300
> From: Eli Zaretskii <[hidden email]>

> > +An input item is a command that pushes a new state of isearch (as
>
> I think you meant to say that "An input item is the result of a
> command that pushes a new state ...".  Right?

Yes.

> > +Info node `Basic Isearch' explains when Emacs pushes a new
> > +isearch state.
>
> It is better to use `(emacs)Basic Search' as a link to the manual;
> that's what we do elsewhere.

Thanks, I've done this and pushed to emacs-26.



Reply | Threaded
Open this post in threaded view
|

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

Charles A. Roelli
The following patch improves indexing of the isearch commands and
bindings mentioned in the current docstring of isearch-forward, and
adds an explanation in the manual for one missing command
(isearch-query-replace-regexp).  This should be one of the last
changes before we can comfortably shorten isearch-forward's docstring.


----
* doc/emacs/search.texi (Basic Isearch): Index isearch-exit,
isearch-abort, isearch-cancel, isearch-repeat-forward,
isearch-repeat-backward and their bindings.
(Repeat Isearch): Index isearch-ring-advance,
isearch-ring-retreat and isearch-edit-string.
(Special Isearch): Index isearch-quote-char,
isearch-char-by-name and their bindings.  Index
isearch-query-replace and isearch-query-replace-regexp, and
the latter's binding.  Explain what
isearch-query-replace-regexp does.  Index isearch-complete.
(Word Search): Index isearch-toggle-word and its binding.
----
diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index 58a7658..9170dc2 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -114,24 +114,30 @@ Basic Isearch
 
 @cindex exit incremental search
 @cindex incremental search, exiting
+@findex isearch-exit
+@kindex RET @r{(Incremental search)}
   When you are satisfied with the place you have reached, type
-@key{RET}.  This stops searching, leaving the cursor where the search
-brought it.  Also, any command not specially meaningful in searches
-stops the searching and is then executed.  Thus, typing @kbd{C-a}
-exits the search and then moves to the beginning of the line; typing
-one of the arrow keys exits the search and performs the respective
-movement command; etc.  @key{RET} is necessary only if the next
-command you want to type is a printing character, @key{DEL},
-@key{RET}, or another character that is special within searches
-(@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, @kbd{C-y}, @kbd{M-y},
-@kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some others described below).
-You can fine-tune the commands that exit the search; see @ref{Not
-Exiting Isearch}.
+@key{RET} (@code{isearch-exit}).  This stops searching, leaving the
+cursor where the search brought it.  Also, any command not specially
+meaningful in searches stops the searching and is then executed.
+Thus, typing @kbd{C-a} exits the search and then moves to the
+beginning of the line; typing one of the arrow keys exits the search
+and performs the respective movement command; etc.  @key{RET} is
+necessary only if the next command you want to type is a printing
+character, @key{DEL}, @key{RET}, or another character that is special
+within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s},
+@kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some others
+described below).  You can fine-tune the commands that exit the
+search; see @ref{Not Exiting Isearch}.
 
   As a special exception, entering @key{RET} when the search string is
 empty launches nonincremental search (@pxref{Nonincremental Search}).
 (This can be customized; see @ref{Search Customizations}.)
 
+@findex isearch-abort
+@findex isearch-cancel
+@kindex C-g C-g @r{(Incremental Search)}
+@kindex ESC ESC ESC @r{(Incremental Search)}
   To abandon the search and return to the place where you started,
 type @kbd{@key{ESC} @key{ESC} @key{ESC}} (@code{isearch-cancel}) or
 @kbd{C-g C-g} (@code{isearch-abort}).
@@ -154,13 +160,18 @@ Basic Isearch
 @node Repeat Isearch
 @subsection Repeating Incremental Search
 
+@kindex C-s @r{(Incremental Search)}
+@kindex C-r @r{(Incremental Search)}
+@findex isearch-repeat-forward
+@findex isearch-repeat-backward
   Suppose you search forward for @samp{FOO} and find a match, but not
 the one you expected to find: the @samp{FOO} you were aiming for
-occurs later in the buffer.  In this event, type another @kbd{C-s} to
-move to the next occurrence of the search string.  You can repeat this
-any number of times.  If you overshoot, you can cancel some @kbd{C-s}
-characters with @key{DEL}.  Similarly, each @kbd{C-r} in a backward
-incremental search repeats the backward search.
+occurs later in the buffer.  In this event, type another @kbd{C-s}
+(@code{isearch-repeat-forward}) to move to the next occurrence of the
+search string.  You can repeat this any number of times.  If you
+overshoot, you can cancel some @kbd{C-s} characters with @key{DEL}.
+Similarly, each @kbd{C-r} (@code{isearch-repeat-backward}) in a
+backward incremental search repeats the backward search.
 
 @cindex lazy search highlighting
   If you pause for a little while during incremental search, Emacs
@@ -200,12 +211,15 @@ Repeat Isearch
 you have already seen.
 
 @cindex search ring
+@findex isearch-ring-advance
+@findex isearch-ring-retreat
 @kindex M-n @r{(Incremental search)}
 @kindex M-p @r{(Incremental search)}
 @vindex search-ring-max
   To reuse earlier search strings, use the @dfn{search ring}.  The
-commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a
-search string to reuse.  These commands leave the selected search ring
+commands @kbd{M-p} (@code{isearch-ring-retreat}) and @kbd{M-n}
+(@code{isearch-ring-advance}) move through the ring to pick a search
+string to reuse.  These commands leave the selected search ring
 element in the minibuffer, where you can edit it.  Type
 @kbd{C-s}/@kbd{C-r} or @key{RET} to accept the string and start
 searching for it.  The number of most recently used search strings
@@ -214,14 +228,16 @@ Repeat Isearch
 
 @cindex incremental search, edit search string
 @cindex interactively edit search string
+@findex isearch-edit-string
 @kindex M-e @r{(Incremental search)}
 @kindex mouse-1 @r{in the minibuffer (Incremental Search)}
   To edit the current search string in the minibuffer without
-replacing it with items from the search ring, type @kbd{M-e} or click
-@kbd{mouse-1} in the minibuffer.  Type @key{RET}, @kbd{C-s} or
-@kbd{C-r} to finish editing the string and search for it.  Type
-@kbd{C-f} or @kbd{@key{RIGHT}} to add to the search string characters
-following point from the buffer from which you started the search.
+replacing it with items from the search ring, type @kbd{M-e}
+(@code{isearch-edit-string}) or click @kbd{mouse-1} in the minibuffer.
+Type @key{RET}, @kbd{C-s} or @kbd{C-r} to finish editing the string
+and search for it.  Type @kbd{C-f} or @kbd{@key{RIGHT}} to add to the
+search string characters following point from the buffer from which
+you started the search.
 
 @node Isearch Yank
 @subsection Isearch Yanking
@@ -357,17 +373,22 @@ Special Isearch
 
 @itemize @bullet
 @item
-Type @kbd{C-q}, followed by a non-graphic character or a sequence of
-octal digits.  This adds a character to the search string, similar to
-inserting into a buffer using @kbd{C-q} (@pxref{Inserting Text}).  For
-example, @kbd{C-q C-s} during incremental search adds the
-@samp{control-S} character to the search string.
+@findex isearch-quote-char
+@kindex C-q @r{(Incremental Search)}
+Type @kbd{C-q} (@code{isearch-quote-char}), followed by a non-graphic
+character or a sequence of octal digits.  This adds a character to the
+search string, similar to inserting into a buffer using @kbd{C-q}
+(@pxref{Inserting Text}).  For example, @kbd{C-q C-s} during
+incremental search adds the @samp{control-S} character to the search
+string.
 
 @item
-Type @kbd{C-x 8 @key{RET}}, followed by 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}).
+@findex isearch-char-by-name
+@kindex C-x 8 RET @r{(Incremental Search)}
+Type @kbd{C-x 8 @key{RET}} (@code{isearch-char-by-name}), followed by
+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
 @kindex C-^ @r{(Incremental Search)}
@@ -400,12 +421,20 @@ Special Isearch
 @code{isearch-occur}, which runs @code{occur} with the current search
 string.  @xref{Other Repeating Search, occur}.
 
+@findex isearch-query-replace
+@findex isearch-query-replace-regexp
 @kindex M-% @r{(Incremental search)}
-  Typing @kbd{M-%} in incremental search invokes @code{query-replace}
-or @code{query-replace-regexp} (depending on search mode) with the
-current search string used as the string to replace.  A negative
-prefix argument means to replace backward.  @xref{Query Replace}.
-
+@kindex C-M-% @r{(Incremental search)}
+  Typing @kbd{M-%} (@code{isearch-query-replace}) in incremental
+search invokes @code{query-replace} or @code{query-replace-regexp}
+(depending on search mode) with the current search string used as the
+string to replace.  A negative prefix argument means to replace
+backward.  @xref{Query Replace}.  Typing @kbd{C-M-%}
+(@code{isearch-query-replace-regexp}) invokes
+@code{query-replace-regexp} with the current search string used as the
+regexp to replace.
+
+@findex isearch-complete
 @kindex M-TAB @r{(Incremental search)}
   Typing @kbd{M-@key{TAB}} in incremental search invokes
 @code{isearch-complete}, which attempts to complete the search string
@@ -599,15 +628,18 @@ Word Search
 Search the Web for the text in region.
 @end table
 
-@kindex M-s w
 @findex isearch-forward-word
+@findex isearch-toggle-word
+@kindex M-s w
+@kindex M-s w @r{(Incremental Search)}
   To begin a forward incremental word search, type @kbd{M-s w}.  If
 incremental search is not already active, this runs the command
 @code{isearch-forward-word}.  If incremental search is already active
-(whether a forward or backward search), @kbd{M-s w} switches to a word
-search while keeping the direction of the search and the current
-search string unchanged.  You can toggle word search back off by
-typing @kbd{M-s w} again.
+(whether a forward or backward search), @kbd{M-s w} runs the command
+@code{isearch-toggle-word}, which switches to a word search while
+keeping the direction of the search and the current search string
+unchanged.  You can toggle word search back off by typing @kbd{M-s w}
+again.
 
 @findex word-search-forward
 @findex word-search-backward



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> Date: Sun, 28 Oct 2018 11:06:46 +0100
> From: [hidden email] (Charles A. Roelli)
> CC: [hidden email]
>
> The following patch improves indexing of the isearch commands and
> bindings mentioned in the current docstring of isearch-forward, and
> adds an explanation in the manual for one missing command
> (isearch-query-replace-regexp).  This should be one of the last
> changes before we can comfortably shorten isearch-forward's docstring.

Thanks, I have a couple of minor comments:

> +search string.  You can repeat this any number of times.  If you
> +overshoot, you can cancel some @kbd{C-s} characters with @key{DEL}.
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
I would say "cancel some @kbd{C-s} commands", not "characters".
"Cancel characters" sounds awkward and slightly confusing.

> +@kindex M-s w
> +@kindex M-s w @r{(Incremental Search)}

It is not useful to have several index entries starting with the same
string and pointing to the same place, or very close places.  In this
case, I think just the first one will do.



Reply | Threaded
Open this post in threaded view
|

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

Charles A. Roelli
> Date: Sun, 28 Oct 2018 17:53:19 +0200
> From: Eli Zaretskii <[hidden email]>
>
> Thanks, I have a couple of minor comments:
>
> > +search string.  You can repeat this any number of times.  If you
> > +overshoot, you can cancel some @kbd{C-s} characters with @key{DEL}.
>                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> I would say "cancel some @kbd{C-s} commands", not "characters".
> "Cancel characters" sounds awkward and slightly confusing.
>
> > +@kindex M-s w
> > +@kindex M-s w @r{(Incremental Search)}
>
> It is not useful to have several index entries starting with the same
> string and pointing to the same place, or very close places.  In this
> case, I think just the first one will do.

Thanks for reviewing, I pushed the change with these amendments.



Reply | Threaded
Open this post in threaded view
|

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

Charles A. Roelli
Now that we have all of the important isearch commands and bindings
indexed, we should be able to shorten isearch-forward's docstring.
The question is, how much?  Here's one attempt that may cut out too
much:

  "Do incremental search forward for a string as you type.
\\<isearch-mode-map>
\\[isearch-repeat-forward] moves forward to the next search hit.
\\[isearch-repeat-backward] moves backward to the previous search hit.
\\[isearch-abort] aborts the search and returns point to its former position.
\\[isearch-exit] exits the search and leaves point where it is.

Many other non-printing keys have special bindings while searching;
Info node `(emacs)Incremental Search' and its descendants describes
them.

If REGEXP-P is non-nil (or interactively, when called with a
prefix argument), do an incremental regular expression search
instead.

If NO-RECURSIVE-EDIT is non-nil (as it is interactively), do not
enter a recursive edit.  If nil, enter a recursive edit and
exit the recursive edit when the search is done."

It covers the absolute basics, but leaves everything else to the
manual.  I'm not sure all users will like that, since the current
docstring covers almost all of the keybindings.

I remember reading somewhere a suggestion for adding a toolbar (and
(or) a dedicated menu) for use during isearch-mode, to help the
discoverability of these myriad keybindings.  That could be a good
alternative to listing verbosely every binding in the docstring.



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> Date: Sat, 10 Nov 2018 14:57:43 +0100
> From: [hidden email] (Charles A. Roelli)
> CC: [hidden email]
>
> Now that we have all of the important isearch commands and bindings
> indexed, we should be able to shorten isearch-forward's docstring.
> The question is, how much?  Here's one attempt that may cut out too
> much:
>
>   "Do incremental search forward for a string as you type.
> \\<isearch-mode-map>
> \\[isearch-repeat-forward] moves forward to the next search hit.
> \\[isearch-repeat-backward] moves backward to the previous search hit.
> \\[isearch-abort] aborts the search and returns point to its former position.
> \\[isearch-exit] exits the search and leaves point where it is.
>
> Many other non-printing keys have special bindings while searching;
> Info node `(emacs)Incremental Search' and its descendants describes
> them.
>
> If REGEXP-P is non-nil (or interactively, when called with a
> prefix argument), do an incremental regular expression search
> instead.
>
> If NO-RECURSIVE-EDIT is non-nil (as it is interactively), do not
> enter a recursive edit.  If nil, enter a recursive edit and
> exit the recursive edit when the search is done."

I think we should at least describe in the doc string what is
described in "Basic Isearch", which would mean adding
isearch-delete-char.  Other than that, I'm okay with this text.

> I remember reading somewhere a suggestion for adding a toolbar (and
> (or) a dedicated menu) for use during isearch-mode, to help the
> discoverability of these myriad keybindings.  That could be a good
> alternative to listing verbosely every binding in the docstring.

I agree, but we should make sure clicking the menu won't exit Isearch.

Thanks.



Reply | Threaded
Open this post in threaded view
|

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

Juri Linkov-2
In reply to this post by Charles A. Roelli
> Now that we have all of the important isearch commands and bindings
> indexed, we should be able to shorten isearch-forward's docstring.

We could move all the current long text from isearch-forward's
docstring to isearch-describe-mode.  Maybe better to move it
to isearch-describe-mode's docstring and then instead of current

  (describe-function 'isearch-forward)

in isearch-describe-mode call

  (describe-function 'isearch-describe-mode)

Then we could add a link to isearch-describe-mode from docstring
of isearch-forward and other isearch commands with an explanation
"For more information, see isearch-describe-mode ..."



Reply | Threaded
Open this post in threaded view
|

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

Charles A. Roelli
In reply to this post by Eli Zaretskii
> Date: Sat, 10 Nov 2018 16:05:05 +0200
> From: Eli Zaretskii <[hidden email]>
>
> I think we should at least describe in the doc string what is
> described in "Basic Isearch", which would mean adding
> isearch-delete-char.  Other than that, I'm okay with this text.

Ok, I will add that in too.

> > I remember reading somewhere a suggestion for adding a toolbar (and
> > (or) a dedicated menu) for use during isearch-mode, to help the
> > discoverability of these myriad keybindings.  That could be a good
> > alternative to listing verbosely every binding in the docstring.
>
> I agree, but we should make sure clicking the menu won't exit Isearch.
>
> Thanks.

There's a first draft of a menu- and tool-bar for Isearch at the end
of this message (on branch master).  Clicking the menu items and icons
should work okay with the mouse, but I haven't yet found a way to show
the menu with either "tmm-menubar" or TTY menus, since activating
these functions will normally exit Isearch.




diff --git a/lisp/isearch.el b/lisp/isearch.el
index 035ff69..1f8a611 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -489,6 +489,142 @@ 'isearch-mode-help
 
 ;; Define isearch-mode keymap.
 
+(defvar isearch-menu-bar-map
+  (let ((map (make-sparse-keymap "Isearch")))
+    (define-key map [isearch-complete]
+      '(menu-item "Complete current search string" isearch-complete
+                  :help "Complete current search string over search history"))
+    (define-key map [isearch-complete-separator]
+      '(menu-item "--"))
+    (define-key map [isearch-query-replace-regexp]
+      '(menu-item "Replace search string as regexp" isearch-query-replace-regexp
+                  :help "Replace matches for current search string as regexp"))
+    (define-key map [isearch-query-replace]
+      '(menu-item "Replace search string" isearch-query-replace
+                  :help "Replace matches for current search string"))
+    (define-key map [isearch-occur]
+      '(menu-item "Show all matches for search string" isearch-occur
+                  :help "Show all matches for current search string"))
+    (define-key map [isearch-highlight-regexp]
+      '(menu-item "Highlight all matches for search string"
+                  isearch-highlight-regexp
+                  :help "Highlight all matches for current search string"))
+    (define-key map [isearch-search-replace-separator]
+      '(menu-item "--"))
+    (define-key map [isearch-toggle-specified-input-method]
+      '(menu-item "Turn on specific input method"
+                  isearch-toggle-specified-input-method
+                  :help "Turn on specific input method for search"))
+    (define-key map [isearch-toggle-input-method]
+      '(menu-item "Toggle input method" isearch-toggle-input-method
+                  :help "Toggle input method for search"))
+    (define-key map [isearch-input-method-separator]
+      '(menu-item "--"))
+    (define-key map [isearch-char-by-name]
+      '(menu-item "Search for char by name" isearch-char-by-name
+                  :help "Search for character by name"))
+    (define-key map [isearch-quote-char]
+      '(menu-item "Search for literal char" isearch-quote-char
+                  :help "Search for literal char"))
+    (define-key map [isearch-special-char-separator]
+      '(menu-item "--"))
+    (define-key map [isearch-toggle-word]
+      '(menu-item "Word matching" isearch-toggle-word
+                  :help "Word matching"
+                  :button (:toggle
+                           . (eq isearch-regexp-function 'word-search-regexp))))
+    (define-key map [isearch-toggle-symbol]
+      '(menu-item "Symbol matching" isearch-toggle-symbol
+                  :help "Symbol matching"
+                  :button (:toggle
+                           . (eq isearch-regexp-function
+                                 'isearch-symbol-regexp))))
+    (define-key map [isearch-toggle-regexp]
+      '(menu-item "Regexp matching" isearch-toggle-regexp
+                  :help "Regexp matching"
+                  :button (:toggle . isearch-regexp)))
+    (define-key map [isearch-toggle-invisible]
+      '(menu-item "Invisible text matching" isearch-toggle-invisible
+                  :help "Invisible text matching"
+                  :button (:toggle . isearch-invisible)))
+    (define-key map [isearch-toggle-char-fold]
+      '(menu-item "Character folding matching" isearch-toggle-char-fold
+                  :help "Character folding matching"
+                  :button (:toggle
+                           . (eq isearch-regexp-function
+                                 'char-fold-to-regexp))))
+    (define-key map [isearch-toggle-case-fold]
+      '(menu-item "Case folding matching" isearch-toggle-case-fold
+                  :help "Case folding matching"
+                  :button (:toggle . isearch-case-fold-search)))
+    (define-key map [isearch-toggle-lax-whitespace]
+      '(menu-item "Lax whitespace matching" isearch-toggle-lax-whitespace
+                  :help "Lax whitespace matching"
+                  :button (:toggle . isearch-lax-whitespace)))
+    (define-key map [isearch-toggle-separator]
+      '(menu-item "--"))
+    (define-key map [isearch-del-char]
+      '(menu-item "Delete last character from search string" isearch-del-char
+                  :help "Delete last character from search string"))
+    (define-key map [isearch-yank-pop]
+      '(menu-item "Yank previous kill on search string" isearch-yank-pop
+                  :help "Replace yanked previous kill on search string"))
+    (define-key map [isearch-yank-kill]
+      '(menu-item "Yank current kill on search string" isearch-yank-kill
+                  :help "Append current kill to search string"))
+    (define-key map [isearch-yank-line]
+      '(menu-item "Yank rest of line on search string" isearch-yank-line
+                  :help "Yank the rest of the current line on search string"))
+    (define-key map [isearch-yank-symbol-or-char]
+      '(menu-item "Yank symbol/char on search string"
+                  isearch-yank-symbol-or-char
+                  :help "Yank next symbol or char on search string"))
+    (define-key map [isearch-yank-word-or-char]
+      '(menu-item "Yank word/char on search string"
+                  isearch-yank-word-or-char
+                  :help "Yank next word or char on search string"))
+    (define-key map [isearch-yank-char]
+      '(menu-item "Yank char on search string" isearch-yank-char
+                  :help "Yank char at point on search string"))
+    (define-key map [isearch-yank-separator]
+      '(menu-item "--"))
+    (define-key map [isearch-edit-string]
+      '(menu-item "Edit current search string" isearch-edit-string
+                  :help "Edit current search string"))
+    (define-key map [isearch-ring-retreat]
+      '(menu-item "Edit previous search string" isearch-ring-retreat
+                  :help "Edit previous search string in Isearch history"))
+    (define-key map [isearch-ring-advance]
+      '(menu-item "Edit next search string" isearch-ring-advance
+                  :help "Edit next search string in Isearch history"))
+    (define-key map [isearch-delete-char]
+      '(menu-item "Cancel last input item" isearch-delete-char
+                  :help "Cancel the last Isearch command"))
+    (define-key map [isearch-repeat-backward]
+      '(menu-item "Repeat search backward" isearch-repeat-backward
+                  :help "Repeat current search backward"))
+    (define-key map [isearch-repeat-forward]
+      '(menu-item "Repeat search forward" isearch-repeat-forward
+                  :help "Repeat current search forward"))
+    (define-key map [isearch-nonincremental]
+      '(menu-item "Nonincremental search" isearch-exit
+                  :help "Start nonincremental search"
+                  :visible (string-equal isearch-string "")))
+    (define-key map [isearch-exit]
+      '(menu-item "Finish search" isearch-exit
+                  :help "Finish search leaving point where it is"
+                  :visible (not (string-equal isearch-string ""))))
+    (define-key map [isearch-abort]
+      '(menu-item "Remove characters not found" isearch-abort
+                  :help "Quit current search"
+                  :visible (not isearch-success)))
+    (define-key map [isearch-cancel]
+      `(menu-item "Cancel search" isearch-cancel
+                  :help "Cancel current search and return to starting point"
+                  :filter ,(lambda (binding)
+                             (if isearch-success 'isearch-abort binding))))
+    map))
+
 (defvar isearch-mode-map
   (let ((i 0)
  (map (make-keymap)))
@@ -595,9 +731,58 @@ isearch-mode-map
     ;; characters to the search string.  See iso-transl.el.
     (define-key map "\C-x8\r" 'isearch-char-by-name)
 
+    (define-key map [menu-bar search-menu]
+      (list 'menu-item "Isearch" isearch-menu-bar-map))
+
     map)
   "Keymap for `isearch-mode'.")
 
+(defvar isearch-tool-bar-old-map nil
+  "Variable holding the old local value of `tool-bar-map', if any.")
+
+(defun isearch-tool-bar-image (image-name)
+  "Return an image specification for IMAGE-NAME."
+  (eval (tool-bar--image-expression image-name)))
+
+(defvar isearch-tool-bar-map
+  (let ((map (make-sparse-keymap)))
+    (define-key map [isearch-describe-mode]
+      (list 'menu-item "Help" 'isearch-describe-mode
+            :help "Get help for Isearch"
+            :image '(isearch-tool-bar-image "help")))
+    (define-key map [isearch-occur]
+      (list 'menu-item "Show hits" 'isearch-occur
+            :help "Show each search hit"
+            :image '(isearch-tool-bar-image "index")))
+    (define-key map [isearch-query-replace]
+      (list 'menu-item "Replace" 'isearch-query-replace
+            :help "Replace search string"
+            :image '(isearch-tool-bar-image "search-replace")))
+    (define-key map [isearch-delete-char]
+      (list 'menu-item "Undo" 'isearch-delete-char
+            :help "Undo last input item"
+            :image '(isearch-tool-bar-image "undo")))
+    (define-key map [isearch-exit]
+      (list 'menu-item "Finish" 'isearch-exit
+            :help "Finish search leaving point where it is"
+            :image '(isearch-tool-bar-image "exit")
+            :visible '(not (string-equal isearch-string ""))))
+    (define-key map [isearch-cancel]
+      (list 'menu-item "Abort" 'isearch-cancel
+            :help "Abort search"
+            :image '(isearch-tool-bar-image "close")
+            :filter (lambda (binding)
+                      (if isearch-success 'isearch-abort binding))))
+    (define-key map [isearch-repeat-forward]
+      (list 'menu-item "Repeat forward" 'isearch-repeat-forward
+            :help "Repeat search forward"
+            :image '(isearch-tool-bar-image "right-arrow")))
+    (define-key map [isearch-repeat-backward]
+      (list 'menu-item "Repeat backward" 'isearch-repeat-backward
+            :help "Repeat search backward"
+            :image '(isearch-tool-bar-image "left-arrow")))
+    map))
+
 (defvar minibuffer-local-isearch-map
   (let ((map (make-sparse-keymap)))
     (set-keymap-parent map minibuffer-local-map)
@@ -733,6 +918,12 @@ isearch--saved-overriding-local-map
     (nconc minor-mode-alist
    (list '(isearch-mode isearch-mode))))
 
+;; We add an entry for `isearch-mode' to `minor-mode-map-alist' so
+;; that `isearch-menu-bar-map' can show on the menu bar.
+(or (assq 'isearch-mode minor-mode-map-alist)
+    (nconc minor-mode-map-alist
+           (list (cons 'isearch-mode isearch-mode-map))))
+
 (defvar-local isearch-mode nil) ;; Name of the minor mode, if non-nil.
 
 (define-key global-map "\C-s" 'isearch-forward)
@@ -978,6 +1169,10 @@ isearch-mode
  isearch-original-minibuffer-message-timeout minibuffer-message-timeout
  minibuffer-message-timeout nil)
 
+  (if (local-variable-p 'tool-bar-map)
+      (setq isearch-tool-bar-old-map tool-bar-map))
+  (setq-local tool-bar-map isearch-tool-bar-map)
+
   ;; We must bypass input method while reading key.  When a user type
   ;; printable character, appropriate input method is turned on in
   ;; minibuffer to read multibyte characters.
@@ -1144,6 +1339,12 @@ isearch-done
       (setq input-method-function isearch-input-method-function)
     (kill-local-variable 'input-method-function))
 
+  (if isearch-tool-bar-old-map
+      (progn
+        (setq-local tool-bar-map isearch-tool-bar-old-map)
+        (setq isearch-tool-bar-old-map nil))
+    (kill-local-variable 'tool-bar-map))
+
   (force-mode-line-update)
 
   ;; If we ended in the middle of some intangible text,
@@ -2486,7 +2687,10 @@ isearch-pre-command-hook
      ;; `set-transient-map' thingy like `universal-argument--mode'.
      ((not (eq overriding-terminal-local-map isearch--saved-overriding-local-map)))
      ;; Don't exit Isearch for isearch key bindings.
-     ((commandp (lookup-key isearch-mode-map key nil)))
+     ((or (commandp (lookup-key isearch-mode-map key nil))
+          (commandp
+           (lookup-key
+            `(keymap (tool-bar menu-item nil ,isearch-tool-bar-map)) key))))
      ;; Optionally edit the search string instead of exiting.
      ((eq search-exit-option 'edit)
       (setq this-command 'isearch-edit-string))



Reply | Threaded
Open this post in threaded view
|

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

Eli Zaretskii
> Date: Thu, 15 Nov 2018 20:57:12 +0100
> From: [hidden email] (Charles A. Roelli)
> CC: [hidden email]
>
> > I agree, but we should make sure clicking the menu won't exit Isearch.
> >
> > Thanks.
>
> There's a first draft of a menu- and tool-bar for Isearch at the end
> of this message (on branch master).

Thanks, I will try that later.

> Clicking the menu items and icons should work okay with the mouse,
> but I haven't yet found a way to show the menu with either
> "tmm-menubar" or TTY menus, since activating these functions will
> normally exit Isearch.

Does it work to give the respective commands a non-nil isearch-scroll
property?  I think at least the TTY menus should work even when the
TTY has no mouse.



Reply | Threaded
Open this post in threaded view
|

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

Juri Linkov-2
In reply to this post by Charles A. Roelli
> There's a first draft of a menu- and tool-bar for Isearch at the end
> of this message (on branch master).

Thanks, this was needed for a long time.  I tried it, and it looks great!

> Clicking the menu items and icons should work okay with the mouse, but
> I haven't yet found a way to show the menu with either "tmm-menubar"
> or TTY menus, since activating these functions will normally
> exit Isearch.

Eli is right.  (put 'tmm-menubar 'isearch-scroll t) did the trick.



Reply | Threaded
Open this post in threaded view
|

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

martin rudalics
 > Eli is right.  (put 'tmm-menubar 'isearch-scroll t) did the trick.

While you're there: Is there anything we could do about Bug#8213?

martin



Reply | Threaded
Open this post in threaded view
|

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

Drew Adams
>  > Eli is right.  (put 'tmm-menubar 'isearch-scroll t) did the trick.
>
> While you're there: Is there anything we could do about Bug#8213?

Sorry for jumping in here in ignorance, but when
I follow the recipe for bug #8213 with Emacs 26
I can move the window divider with no problem.
That does exit Isearch, but that doesn't seem to
be what the bug report was about - it says that
you cannot move the divider.

I'm on Windows 10, though, not Windows 7 as in
the bug report.  And maybe I'm missing something.



12