Subject: Re: bug#43709: minibuffer keybinding cheatsheet and launcher [CODE SUBMISSION]

From: Boruch Baum <[email-masked]>
Date: Thu, 1 Oct 2020 16:46:17 -0400

On 2020-10-01 12:04, Stefan Monnier wrote:
> I'm thinking that this would be useful for someone that not very
> familiar with Emacs,

It could be, yes.

> it seems instead geared toward users that are already familiar with
> Emacs and want to get to know some new mode or something like that.

True.

> For a novice, we'd ideally want the user to be able to find and use this
> functionality "naturally" without even knowing beforehand how to look
> for it and how Emacs generally works ;-)

Oh, emacs. I'm the wrong person to ask because my reflexive response was
to assume everyone should expect something like 'C-u C-h k'.

BTW, a few months (years?) ago I had an email exchange with Eli
Zaretskii in which he mentioned the help feature that he felt was most
useful and important ... and it turned out not to even have a
keybinding o even a mention in 'C-h ?' (and now I've forgotten even what
it was the command was...)

> I think skipping the prompt is an easier way to avoid the confusion.
> Only prompt if the user asks for it (e.g. with a `C-u` prefix, an
> alternative entry-point, ...).

My initial inclination was to go for the prefix-arg option, but that
wouldn't be friendly to novice users. And then I thought the same thing
about an alternative entry-point, because it's asking someone to
remember two separate commands. If the goal is to deal with the
confusion of novices, the way to do it is with a single command and
verbose interface. Even for non-novices, the goal here is to reduce the
requirement to memorize, so having multiple ways of invoking the command
is contradictory in that it asks for more memorization. A golden mean
would be to come up with a short and clear prompt that can be ignored
for most cases.

> Or maybe we'd want to offer this prompt *afterwards*, as a special
> command to change&recompute the completion table based on
> a new criterion.

Not difficult to program, but when I think about it, I see two
obstacles:

1) The prompt ends up being at least as messy or confusing. What I end
   up with is a three-line prompt, something like (example being a dired
   buffer):

     Presenting list of 'dired-' commands.
     Select an item on the current list, or
     <key> to present a list using a different regexp

2) What <key> could you use to guarantee no conflict with any other
   entry on the list? Remember that we're inside 'completing-read' at
   this point, so we can't be using control characters, can we? Even if
   we can dynamically change the <key> based upon a uniqueness check of
   all characters in the list, that would just add to confusion, because
   each different invocation would generate a different <key>. In
   practice, it would be difficult to generate such a unique key because
   completing-read matches against all characters in list, which in our
   case includes all characters in the description, not just those of
   the keybindings.

> >>    and then it said "no choices found".
> I was in *scratch*, so should have been `lisp-interaction-mode`.
> Maybe the "no choices found" message should mention the search string
> that was used (that's also a good way to teach the user what the first
> prompt means).

Agreed. I'll work on it. My preference would then be for a verbose
minibuffer message, maybe as much as three long lines, amounting to a
mini-tutorial, the goal being to reduce confusion for novices or people
unfamiliar with the operation.

> >>   So I tried again in a dired buffer, where it instead showed me a
> >>   minibuffer prompt "Select: " with no indication of what it is I
> >>   should be selecting,
> >
> > I had difficulty deciding what text to use for this prompt because many
> > users can be expected to be using some non-default minibuffer completion
> > supplemental package (eg. ido, icicles, ivy), and those all have
> > slightly different behavior; many present a result-list without needing
> > to TAB.
>
> Good point.  For the plain old default, it would make a lot of sense to
> eagerly popup the *Completions*, but I'm not sure how we could do it
> without getting in the way for ivy and friends.

Is this again something to consider implementing as a patch inside
completing-read, ie. change the message/prompt inside completing-read;
would users of the packages that commandeer the mini-buffer interface
("ivy and friends") see the completing-read prompt at that point? At
that point, they've already commandeered the interface.

--
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0