Subject: bug#43308: 28.0.50; Improvements to Edit->Search menu

From: Ihor Radchenko <[email-masked]>
Date: Sun, 20 Sep 2020 15:15:10 +0800

It seems that the opinions are a bit split here, so I will try to
summarise the current state of the discussion in this message and refine
my suggestions from original bug report.

First of all, let me clarify on the purpose of the menu/toolbar as I
understand it. I tried to make sure that it is consistent with opinions
of others, but feel free to reply if you disagree.

Target users:

1. Menu is designed for users unfamiliar with Emacs concepts
2. Moreover, we do not expect those users to read Emacs manual or even
   tutorial
3. All the users are expected to know functionality, which is common
   among modern editor apps
4. Menu does not try to show all possible functionality of Emacs, just
   the most important (otherwise, people will be lost in too many menu
   items)

The aims of the menu:

1. Show people Emacs equivalents text editing functions they would
   expect to use from other editors
2. Provide an indication how to switch to Emacs-specific commands (by
   indicating key bindings and command help)
3. Provide the most important Emacs-specific commands, which can be
   useful even though they have no equivalent in other editors

Now, let me go through my original proposal and put in into the context
of the above principles, while taking into account the comments on this
bug report.

----------
1. Replacing non-interactive search by interactive search
----------

There seems to be controversy on this part of the proposal:

Eli Zaretskii <[email-masked]> (Thu. 22:59)

> I disagree.  Many applications have only the non-incremental search
> commands, so removing them will leave the user who are used to those
> with the incremental variant, which might be confusing for people who
> have no experience with comparable commands.

Stefan Kangas <[email-masked]> (Thu. 23:38) replying to previous
message

> I think this is less of a concern these days.
> The applications you talk about also have search dialog boxes, which
> make the non-incremental search actually useful.
> 
> Firefox also has incremental search by default, which many (most?) of
> our users will already be familiar with.

Eli Zaretskii <[email-masked]> (Thu. 23:51) replying to previous message

>> The applications you talk about also have search dialog boxes, which
>> make the non-incremental search actually useful.
[ 7 more citation lines. Click/Enter to show. ]
>
> That's true in some cases, but not in all of them.  And the dialog is
> not really relevant here: the issue I raise is with the concept of
> incremental searching being unfamiliar.
>
>> Firefox also has incremental search by default, which many (most?) of
>> our users will already be familiar with.
>
> Some applications added incremental search, but many don't have it,
> and probably never will.  Simple editors are in that class.

Stefan Kangas <[email-masked]> (Fri. 00:19) replying to previous message

>> In what way is this less of a concern?
> Users are more familiar with incremental search, for example from
[ 3 more citation lines. Click/Enter to show. ]
> Firefox.  I checked, and Chromium also has it, and IIRC so does Safari.
> Assuming that our users have used any of those web browsers, they will
> already have had exposure to incremental search.
>
> In any case, even if they haven't, the feature will quickly be learned
> once you start using it.

Eli Zaretskii <[email-masked]> (Fri. 00:30) replying to previous message

> > > In what way is this less of a concern?
> > Users are more familiar with incremental search, for example from
[ 17 more citation lines. Click/Enter to show. ]
> > Firefox.  I checked, and Chromium also has it, and IIRC so does Safari.
> > Assuming that our users have used any of those web browsers, they will
> > already have had exposure to incremental search.
> 
> The example apps you show are not editors.
>
> And, btw, their incremental search works subtly differently: once you
> click the Next or Previous button, typing characters doesn't
> necessarily modify the search string, you need to click in the search
> field for that.
> 
> So even if the user has some experience with these browsers, they
> won't necessarily feel at home with Emacs's Isearch.
> 
> > In any case, even if they haven't, the feature will quickly be learned
> > once you start using it.
> 
> The menus are supposed to help first-time users, with little or no
> experience in using Emacs.  Once they start using the incremental
> search, the menus are probably not for them anymore.

My reply:

The above comment that incremental search may be unfamiliar is a valid
concern. However, non-interactive search is not commonly used in Emacs
by people who get some minimal experience (correct me if I am wrong). We
are promoting the command that may be relatively easy to used for the
user, but it does not help the user to learn the more common and
powerful Emacs equivalent (which is isearch).

As Stefan Kangas mentioned, we can expect that users are somehow
familiar with incremental search concept from browsers. People
unfamiliar with browsers are very uncommon case - if we start to
consider all such possibilities, menu will grow into duplicate of custom
interface (in terms to overly too many features).

It was also mentioned that isearch behaves differently from what users
might expect. However, the non-interactive search also behaves very
differently - users cannot go to next/previous match easily. They have
to go to menu->edit->search->repeat forward/backwards. On the contrary,
isearch does provide forward/backward search buttons at least (though
they are located far from the entered search string - in the toolbar). I
would argue that isearch does a better (not ideal though) job creating
familiar interface.

Therefore, I would favour isearch over the non-interactive version.

-----------
2. Showing next match/previous match toolbar icons to assist users, unfamiliar with key bindings
-----------

When writing this suggestion, I did not know that these icons are
already shown on the toolbar. In fact, toolbar during isearch does even
better job - it provides next/prev match _and_ more useful commands from
isearch-mode-map. Moreover, it even gives a button to show help buffer
about isearch.

There is no such toolbar functionality for non-interactive search
though.

Eli Zaretskii <[email-masked]> (Thu. 22:59)

> > I would also add that we can show transient next match/previous match
> > toolbar icons to assist users, unfamiliar with key bindings.
> 
> Please show the code.  Please also keep in mind that changes on the
> tool bar require redrawing of the tool bar, which could cause
> unpleasant flickering.  We need to consider this potential downside.

Stefan Kangas <[email-masked]> (Thu. 23:38) replying to previous message

> >> repeating search together (via next/prev buttons).
> >> Current Emacs menu forces the user to click Edit->Search menu->...
[ 7 more citation lines. Click/Enter to show. ]
> >> multiple times to repeat the search. That is not a pleasant experience.
> >
> > If you are suggesting a "repeat last search" menu item, it could be a
> > useful idea.  But removing those items because we don't have a simple
> > repeat item is a step in the wrong direction, IMO.
> 
> This is a separate discussion, I think, but on graphical displays I
> would ideally like to see a user interface like the one in C-f Firefox.
> It shows clickable buttons for next/previous match, toggles for "Match
> Case", "Whole Words" and how many matches there are.

Eli Zaretskii <[email-masked]> (Thu. 23:51) replying to previous comment

> > > repeat item is a step in the wrong direction, IMO.
> > This is a separate discussion, I think, but on graphical displays I
[ 6 more citation lines. Click/Enter to show. ]
> > would ideally like to see a user interface like the one in C-f Firefox.
> > It shows clickable buttons for next/previous match, toggles for "Match
> > Case", "Whole Words" and how many matches there are.
> 
> Improving the (non-existing) search dialog is a separate discussion.
> If you want to work on such a dialog, please do.  but that is not what
> we are talking here.  The proposal on the table is to remove
> non-incremental search commands from the Search menu.  let's stay
> focused on that issue, okay?

My reply:

I think I need to clarify that by showing toolbar buttons during search,
I proposed something similar to C-f in Firefox - buttons for prev/next
search are shown right above/below the input box for search string.

In the case of Emacs, that would mean showing prev/next match toolbar
buttons right above the minibuffer.

Moreover, as I mentioned earlier, there is already toolbar functionality
for isearch. If the toolbar was moved to the bottom of the frame during
isearch, it would be sufficient to achieve what I had in mind. Current
top position is very easy to miss (I did miss it even though I was
looking into isearch menu item specifically).

I believe that the same functionality can be implemented for
non-interactive search - we can reuse the same toolbar as in isearch.
Moreover, having prev/next match buttons will effectively provide the
following separate menu items in a single search command (or maybe in
two commands for forward/backward search):
- Edit->Search menu->String Forward
- Edit->Search menu->String Backwards
- Edit->Search menu->Regexp Forward
- Edit->Search menu->Regexp Backwards
- Edit->Search menu->Repeat Forward
- Edit->Search menu->Repeat Backwards

Same with isearch, I believe that the toolbar position would better be
right above the minibuffer.

On the flickering issue: Does it exist with the current toolbar for
isearch? If there no bug reports on it, it is probably just hypothetical
and we should not care about it.

----------
3. Renaming Forward/Backward string to Search forward/backward
----------

Eli Zaretskii <[email-masked]> (Thu. 22:59)

> > Also, the article suggests to rename "Forward/Backward String..." into
> > "Search Forward/Backwards...", which sounds reasonable since
[ 5 more citation lines. Click/Enter to show. ]
> > non-programmer users may be confused by the meaning of word "String".
> 
> The "Search" part is in the parent menu item, so repeating it would be
> a waste of space, which is at premium here.
> 
> If people agree that removing "String" will help, maybe we could do
> that.  But please note that "String" contrasts with "Regexp" in the
> next items; if we remove it, won't that be less clear?

Stefan Kangas <[email-masked]> (Thu. 23:38) replying to previous message

> > The "Search" part is in the parent menu item, so repeating it would be
> > a waste of space, which is at premium here.
[ 7 more citation lines. Click/Enter to show. ]
> >
> > If people agree that removing "String" will help, maybe we could do
> > that.  But please note that "String" contrasts with "Regexp" in the
> > next items; if we remove it, won't that be less clear?
> 
> I think removing it is fine.  Already saying "Regexp" makes it clear
> that this is the odd one out.
> 
> (IIRC, this is what you find in other software: the regexp case is the
> one with a special mention, otherwise it's just called "Search".)

My reply:

No space will be wasted when renaming "Forward/Backward string" to
"Search forward/backward". The char count is the same. But, as I said we
add an extra benefit of not using word that is potentially confusing for
non-programmers.

------
4. Unfamiliar "Search tagged files..." command and other menu items,
   that user is not familiar with (yet)
------

Eli Zaretskii <[email-masked]> (Thu. 22:59)

> > Finally, find "Search tagged files..." and the following "Repeat" menu
> > confusing. What does "tagged files" mean?
[ 11 more citation lines. Click/Enter to show. ]
> 
> Feel free to suggest a better name for the item and/or a better help
> string.

> > I tried to click it, got a prompt about regex, then prompt about tag
> > table (what is it?). Finally, I got error "File ~/TAGS does not
> > exist". This made me recall vague memory about Emacs manual talking
> > about some kind of completion feature for large code projects -
> > something I never used.
> 
> Did you try "C-h k" before selecting that?  This would display the
> documentation of that command.  It's a canonical way of learning about
> menu items that don't explain themselves enough at first reading.  (Of
> course if we can make them more self-explanatory, it's better.)

My reply:

> Feel free to suggest a better name for the item and/or a better help
> string.

I cannot suggest a better name since I have no idea how the TAGS
functionality works. I just wanted to point out that it was confusing
for me. I never had to deal with big multi-file projects where TAGS
search is needed.

> Did you try "C-h k" before selecting that?  This would display the
> documentation of that command.  It's a canonical way of learning about
> menu items that don't explain themselves enough at first reading.  (Of
> course if we can make them more self-explanatory, it's better.)

As you said in another message:

> Once again, menus are for those who don't read the documentation, but
> just start Emacs and want to do something useful.

We cannot expect the user to know about "C-h k".

My concrete suggestion is using the tooltip to hint the user how to get
more information about the command. The tooltip is already showing a
short (yet longer than menu item name) command description. I suggest to
add something like "Use mouse-3 (middle click) to get more information"
and bind mouse-3 to show help buffer on the command.

Best,
Ihor

Eli Zaretskii <[email-masked]> writes:

>> From: Juri Linkov <[email-masked]>
>> Cc: [email-masked],  [email-masked],  [email-masked]
>> Date: Thu, 10 Sep 2020 22:14:00 +0300
>> 
>> >> But it you really don't want to remove nonincremental menu items from
>> >> the Edit menu then they could be swapped with incremental menu items,
>> >> i.e. to promote incremental menu items higher, and demote nonincremental
>> >> menu items deeper to the submenu where currently more often used
>> >> incremental menu items are located.
>> >
>> > That'd be the opposite of what the menu should be doing, which is
>> > putting the easier and more familiar commands closer to the top level.
>> 
>> TUTORIAL teaches about incremental commands:
>
> Once again, menus are for those who don't read the documentation, but
> just start Emacs and want to do something useful.