bug#33595: 26; Have `try-completion' or `completion--done' run abnormal hook if sole completion

[Drew Adams <drew.adams@oracle.com>]

> >> More concretely, do you expect a hook function places on this variable
> >> to apply for "any completion table" or would it be specific to
> >> a particular completion table?
> > The former.  At least I don't see how this has anything to
> > do with what kind of completion is used or how it's done.
> 
> Not sure what you mean by "kind of completion" but a completion table
> describes the "kind" of completion in the sense of describing the set of
> possible completions (i.e. either a set of function names, or a set of
> file names, or ...).
> 
> In your example, the hook function calls `describe-function` so it only
> makes sense when the completion table is a set of function names, an
> becomes absurd when it's a set of file names, or Git revisions, ...

If that's what you meant by your question then yes,
I think I answered that when I said that the person
who writes the code that invokes `completing-read',
say, is the person who adds a function to the hook,
or binds the hook - or not (does not use the hook).

What you put on the hook typically is specific to
the completion candidates you provide, and to the
command that uses the candidate the user chooses.

If that's what you meant by "tightly linked to the
completion table", then yes.  But the hook does not
change the completion table or change completion in
any way.  It's only about what a user does with a
completion (the "UI" you mentioned?).

> So in your example, your hook function is very tightly linked to the
> completion table.  I still don't understand this example well enough to
> understand if/how it's linked to the UI (e.g. what should happen if the
> user happens to use, say, ido-ubiquitous to complete his function names).

Ido?  Idon't.  I don't know either.  Try it, to see. ;-)

> >> The example you give in `my-describe-function` gives me the impression
> >> that those would inevitably be tightly linked to the completion table.
> >> So instead of a hook variable, it would probably make more sense to add
> >> a new `completion-extra-properties` alongside to :exit-function.
> > No, I don't think that's relevant.
> 
> What do you mean by "relevant"?  It would require the code to be a bit
> different but you could get the exact same behavior with it.

It's not clear yet that you are clear about what this
is about.  But if you feel you are, and if you think
there's a better way to provide such behavior to users,
go for it.

As I said, I don't use this myself.  It's just something
simple that I saw as possible, easy, and (I expect)
likely to be of some (limited) use.

If you want to close the bug, I won't cry.

> >> PS: I'm not sure I completely understand the intended behavior of
> >>     `my-describe-function`, but I get the impression that for this
> >>     particular example, a maybe even better approach is to use
> >>     minibuffer-with-setup-hook to set a post-command-hook that calls
> >>     describe-function whenever the minibuffer names a valid function
> >>     (whether we get there via completion or plain typing, and regardless
> >>     if it's the sole completion).
> >
> > No, that's something else.  This is not about describing
> > everything that shows up in the minibuffer.  It's about
> > a user asking to do something with a (full) completion - on
> > demand.  Something defined by the person who wrote the code
> > calling for completion.  Something specific for the command
> > that is asking for user input, or at least for its candidates.
> 
> One part I don't fully understand is why this code wants to call
> `describe-function` only and exactly when the user hits TAB and it
> completes to an sole match.  Why should the user not want to see that
> same result when typing the name explicitly instead of completing to it?

I never said a user could not want that.  But there is
a difference between typing something and knowing that
it is one of a set of provided choices.

Doing this only for a sole completion (which is what
I'd recommend here) avoids having it kick in at a
zillion places where a user likely doesn't want it.

In my view of this it would be only on demand, and
only when a user knows that what's in the minibuffer
is a full completion (what Emacs calls completed and
unique).

That's the goal here.  But feel free to design
something different, for some different, but perhaps
related, purpose.

> Why should the user not want to see the same result when completing to
> an exact-but-not-sole match?

A user might.  See above.  Users can want all kinds
of things.  Different users, and the same user, can
want different things at different times.

This simple suggestion is not trying to do more than
what I suggested.  It's not trying to provide an
extended eldoc or a partial Icicles/Helm or anything
of the sort.

The hook function can do pretty much anything with
the completion, and it can ignore it.  It's not
limited to providing more info about the completion.

This just lets a user, on demand, invoke an action
(defined by whoever wrote the code invoking the
input-reading function) on user input that has
already been completed (the input is complete and
unique).  That's all.  Really not a big deal.

> Another thing I don't understand about your example is: what is the user
> expected to do after hitting TAB (which completed to a sole match)?
> The only thing left to do seems to be RET but that's redundant since
> `describe-function` was already called.
> 
> > [To be clear about one thing: This is not at all for _me_, as
> > it has no effect with my setup, which uses Icicles, which (1)
> > completes and uses TAB differently and (2) has a different
> > mechanism for optionally doing something when there is a sole
> > completion.  I just thought/think that this might be useful
> > for some users (and it is simple).]
> 
> It's not as simple as it seems: if the user goes to some other buffer in
> the middle of the completion, your completion-sole-match-functions will
> not wreak havoc in unrelated completions.

I don't know what you mean.  Maybe give a specific
example (e.g. recipe, using the patch)?  Or not.

I haven't tried to look for problems this might
introduce, as none came to mind spontaneously.
Do you really see something problematic here?

I don't want to spend a lot of time on this.  If
you don't get it, or you don't think it's helpful,
or you think it's problematic, please feel free
to drop it and close the bug.  No harm done.

But I'm happy to answer questions about what the
behavior or intention is, if I know the answers.
IOW, if you're interested then we can continue
to chat if something's not clear or there's a
problem, but if you're not interested then let's
call it quits.

> > When TAB tells you that there is only one completion for your
> > input (and completes to it), you can hit RET to choose that
> > completion (act on it).  But in some cases you might want to
> > first, or instead, take some other action on it - in particular,
> > maybe get some more info about it.  This lets you do that.
> 
> Why only in that specific case?

See above.  Did I answer that sufficiently?

> > Hitting TAB again at that point does nothing now - it's a no-op.
> > If this hook were bound it would instead do something.
> 
> Ah, so you want this hook to be run when TAB is hit a second time, in
> which case it normally does nothing (tho that depends on the config, it
> may also display the *Completions* buffer)?

Absolutely.  If you just try the code I think it will
become clear what the behavior and intention are.
It's harder to describe than to experience.  If you
try it then maybe it will be easier to discuss any
problems you see or further questions you have.

> I think I'm beginning to understand.  But I think it belongs in the
> completion data (i.e. alongside :exit-function).

I don't.  But you're the expert on that.  Go for it,
if you think it's useful and that's a better approach.

Do you think that's easier for someone writing a call
to `completing-read' or `read-file-name', while giving
users the same behavior?  You're not just trying to
promote uptake of `completion-extra-properties', are
you? ;-)  Really, I have no problem with your providing
this some other way, or with deciding not to provide
it at all.