bug#4718: 23.1; C-h f gives doc for the wrong function

[Drew Adams]

> emacs22 -Q
> C-h f dolis RET
> 
> will happily descrie the `dolist' function.  So, no, this is 
> no strictly new behavior in this respect.

I already said the same thing:

 >> Emacs has always allowed you, in some contexts (but
 >> not in others), to hit RET to both complete and enter
 >> the completed text. But that becomes less appropriate
 >> when the completion is not obvious from the input text
 >> (as is the case for partial completion).

This change qualitatively alters what to expect from RET. Until now, you could
pretty much be sure of what RET was going to give you - the only case for
possible confusion was multiple names with the same prefix, and there you
typically got some help from the `Complete but not unique' feedback.

Now, you type `orange' and you find out afterward that you entered `apple'.
Qualitatively, we're no longer in the same ballpark.

> The partial completion in Emacs-23 does make it more likely
> that completion will find some function rather than
> return "no match".

That's it. And for RET, especially, that can be quite confusing. With TAB, you
see what you will get, at least.

> If someone wants to make this function
> use a `ask' for `require-match', as is done in M-x, I won't
> object, tho I do not think it's a big deal.

I hope someone will. I don't have the time now. It should have been done when we
introduced `completion-styles' and partial completion as the default behavior.

But we should not impose a regimental `ask' for this in general. The problem
does not exist for prefix completion. We should show you the sole completion and
ask for confirmation only when it does not correspond to prefix completion.
Non-basic completion is the only case where there is really an element of
surprise, confusion, and lack of understanding.

> For what it's worth I have a local patch that indirectly changes this
> behavior: it accepts any function name (even non-existing ones),
> requires confirmation for non-existing ones, and then tries to guess
> which file to load to find the function.

The problem is not non-existing functions. In that case, the current code would
still say `No match'. The problem is (a) treating additional patterns as matches
when combined with (b) RET.

As I said, with TAB it's one thing. With RET, you don't even get a chance to see
what the completion is (until you see the *Help* buffer, and then you're
unlikely to double-check the function name).

I don't even think this is specific to `C-h f'. We should probably do the same
thing most of the time: make RET confirm when the completion is not an obvious
one (i.e. a suffix).