completion-auto-help

completion-auto-help

[Drew Adams]

1. Question:

The doc string for `completion-auto-help' says this:

 Non-nil means automatically provide help for invalid completion input.

The Elisp manual says this about it:

 If this variable is non-`nil', the completion commands
 automatically display a list of possible completions whenever
 nothing can be completed because the next character is not
 uniquely determined.

In neither case are different non-nil values distinguished. So, I don't
understand this code in complete.el:

(if (or (eq completion-auto-help t)
        (and completion-auto-help
             (eq last-command this-command))
        (eq mode 'help))

The second arg to `or' can only be evaluated if `completion-auto-help' is
not `t', and that second arg tests whether it is non-nil.

Am I missing something - is there some special treatment somewhere for
non-nil, non-t value? (That's what the second arg seems to be doing.) I see
no other occurrences of `completion-auto-help' anywhere in the Lisp code
that distinguish different non-nil values.


2. New feature proposal - How about allowing for an
"always-display-*Completions*' behavior:

 - t means what it means now
 - nil means what it means now
 - other means this:

Display *Completions* right from the beginning (empty minibuffer input).
Display it as long as the minibuffer contents match more than one
completion.

IOW, with this value, the user would not need to hit `TAB' to display
*Completions*. (S)he would see the list of completions whenever there are
more than one. There is currently no way to make `completing-read',
`read-file-name' etc. display *Completions* from the outset.

Re: completion-auto-help

[Stefan Monnier]

> The Elisp manual says this about it:

>  If this variable is non-`nil', the completion commands
>  automatically display a list of possible completions whenever
>  nothing can be completed because the next character is not
>  uniquely determined.

> In neither case are different non-nil values distinguished. So, I don't
> understand this code in complete.el:

> (if (or (eq completion-auto-help t)
>         (and completion-auto-help
>              (eq last-command this-command))
>         (eq mode 'help))

complete.el extends the meaning of the variable so that a non-nil non-t
value means "show the help but only on the second attempt to complete".
I.e. if TAB finds nothing to complete, the first TAB will just say "[Next
char not unique]" without bringing up the *Completions* buffer, and the
second TAB will then bring up the *Completions* buffer.
It happens to be my favorite behavior.

> 2. New feature proposal - How about allowing for an
> "always-display-*Completions*' behavior:

>  - t means what it means now
>  - nil means what it means now
>  - other means this:

We could have

   t = what it means now
   nil = what it means now
   eager = what you suggest (always show the completions and update them
                             after each key stroke)
   lazy = what complete.el does for non-nil non-t values

> IOW, with this value, the user would not need to hit `TAB' to display
> *Completions*. (S)he would see the list of completions whenever there are
> more than one. There is currently no way to make `completing-read',
> `read-file-name' etc. display *Completions* from the outset.

Indeed.  The closest is icomplete-mode.


        Stefan

RE: completion-auto-help

[Drew Adams]

    complete.el extends the meaning of the variable so that a non-nil non-t
    value means "show the help but only on the second attempt to complete".
    I.e. if TAB finds nothing to complete, the first TAB will just
    say "[Next
    char not unique]" without bringing up the *Completions* buffer, and the
    second TAB will then bring up the *Completions* buffer.
    It happens to be my favorite behavior.

Thanks. I knew about that behavior, but I couldn't make out the related use
of completion-auto-help.

I still don't see it in complete.el (it is only tested there, never bound),
and I don't see it in C code either. Where is `completion-auto-help's
non-nil, non-t value bound?

If it is only a user who sets such a value, then shouldn't the non-nil,
non-t behavior be documented for the user option? I don't see that, as I
mentioned.

    > 2. New feature proposal - How about allowing for an
    > "always-display-*Completions*' behavior:

    >  - t means what it means now
    >  - nil means what it means now
    >  - other means this:

    We could have

       t = what it means now
       nil = what it means now
       eager = what you suggest (always show the completions and update them
                                 after each key stroke)
       lazy = what complete.el does for non-nil non-t values

Good.

    > IOW, with this value, the user would not need to hit `TAB' to display
    > *Completions*. (S)he would see the list of completions
    whenever there are
    > more than one. There is currently no way to make `completing-read',
    > `read-file-name' etc. display *Completions* from the outset.

    Indeed.  The closest is icomplete-mode.

Yes, in fact, I implement this behavior with regexp matching in Icicles,
where I refer to it, by analogy, as "apropos icompletion" ("apropos" because
it uses a regexp, "icompletion" because it is incremental completion). That
was one of the motivations for this request: I currently have no way to
display the candidates right from the beginning - a user must first request
the display (via, e.g., `TAB').

I proposed `eager' _without_ the automatic update after each keystroke, in
order to allow that as an additional (separate) option. I think that would
be better. Some people (or some functions) might like to display the list of
candidates right from the beginning, as a kind of menu, but prefer to update
it only upon demand (via `TAB'), not automatically at each keystroke. Some
people might find the automatic list updating to be distracting (I find it
very helpful, personally).

IOW, I think we should separate the control of when to display of
*Completions* from the control of whether or not to automatically update it.
The difference only makes sense, probably, for the `eager' value, so we
could just have two values instead of one: `eager-with-auto-update' and
`eager-without-auto-update'.

My implementation of this kind of incremental completion in Icicles uses an
option that is checked in the special self-insert I use. The option values:

 non-nil means update *Completions* incrementally, as you type.
  t means do nothing if *Completions* is not already displayed.
  non-nil and non-t means display *Completions* and update it.

So, for instance, non-nil, non-t causes character insertion to display
*Completions*. That does not take care of displaying it, however, right from
the beginning, which is why I made this request. The special self-insert
gets called inside `completing-read', upon insertion, but I see no way to
get `completing-read' to display *Completions* without any user action.

RE: completion-auto-help

[Drew Adams]

I wrote:

    Some people might find the automatic list updating to be distracting
    (I find it very helpful, personally).

Correction - I find it very helpful, provided I want to see the
*Completions* list at all. If *Completions* is automatically displayed from
the outset, and updated at each keystroke, that can be distracting in some
contexts and helpful in others.

I mentioned two optional auto-update behaviors in Icicles:

     non-nil means update *Completions* incrementally, as you type.
      t means do nothing if *Completions* is not already displayed.
      non-nil and non-t means display *Completions* and update it.

It is the `t' behavior that I find very helpful. I find the non-nil, non-t
behavior distracting, depending on the size of the alist for
completing-read. With a large alist, auto-update as soon as you start typing
something can lead to massive update changes in *Completions*.

I'm still requesting a way to display *Completions* from the beginning, but
I would use that only in particular contexts - for example, when the list of
candidates is relatively small (*Completions* is treated as a menu), in
which case, auto-update is not distracting. Otherwise I would use it without
auto-update.

That's why I'd like to keep the two (display *Completions* initially and
auto-update it) as separate options.

Re: completion-auto-help

[Stefan Monnier]

>     complete.el extends the meaning of the variable so that a non-nil non-t
>     value means "show the help but only on the second attempt to complete".
>     I.e. if TAB finds nothing to complete, the first TAB will just
>     say "[Next
>     char not unique]" without bringing up the *Completions* buffer, and the
>     second TAB will then bring up the *Completions* buffer.
>     It happens to be my favorite behavior.

> Thanks. I knew about that behavior, but I couldn't make out the related use
> of completion-auto-help.

> I still don't see it in complete.el (it is only tested there, never bound),
> and I don't see it in C code either. Where is `completion-auto-help's
> non-nil, non-t value bound?

completion-auto-help is a user variable.  It's only meant to be changed in
the .emacs file.

> If it is only a user who sets such a value, then shouldn't the non-nil,
> non-t behavior be documented for the user option? I don't see that, as I
> mentioned.

It's not documented, because there's no place to document it:
completion-auto-help is part of the basic completion facilities, whereas the
added behavior is only provided in complete.el which is a separate package.

> I proposed `eager' _without_ the automatic update after each keystroke, in
> order to allow that as an additional (separate) option. I think that would
> be better. Some people (or some functions) might like to display the list of
> candidates right from the beginning, as a kind of menu, but prefer to update
> it only upon demand (via `TAB'), not automatically at each keystroke. Some
> people might find the automatic list updating to be distracting (I find it
> very helpful, personally).

I'd wait to see people complaint about one of the two behaviors before
providing both.

> gets called inside `completing-read', upon insertion, but I see no way to
> get `completing-read' to display *Completions* without any user action.

IIRC you can do it from minibuffer-setup-hook.


        Stefan

RE: completion-auto-help

[Drew Adams]

    > If it is only a user who sets such a value, then shouldn't
    the non-nil,
    > non-t behavior be documented for the user option? I don't see
    that, as I
    > mentioned.

    It's not documented, because there's no place to document it:
    completion-auto-help is part of the basic completion
    facilities, whereas the
    added behavior is only provided in complete.el which is a
    separate package.

That doesn't sound right, somehow.

Is the non-nil behavior you describe behavior provided only by complete.el?
Or is it part of the basic completion facilities?

If the latter, then the doc string should be changed to mention the non-nil,
non-t case.

If the former, then complete.el is changing the behavior of the general user
option (instead of, for example, using a new user option). That's OK I
guess, but it should document that - at the very least in the Commentary of
the library. Better, would be for complete.el to update the doc string of
`completion-auto-help', describing the complete.el-specific behavior.

    > I proposed `eager' _without_ the automatic update after each
    > keystroke, in order to allow that as an additional (separate)
    > option. I think that would be better. Some people (or some
    > functions) might like to display the list of candidates right
    > from the beginning, as a kind of menu, but prefer to update
    > it only upon demand (via `TAB'), not automatically at each
    > keystroke. Some people might find the automatic list updating
    > to be distracting (I find it very helpful, personally).

    I'd wait to see people complaint about one of the two behaviors before
    providing both.

I'm complaining - see my second email on this.

The ability to display *Completions* from the start would typically be used
in situations where the number of candidates is not that large - in
particular, where *Completions* is treated much as a menu. In that context,
auto-update is not distracting, and can be very helpful.

However, displaying a long list from the start, and updating it with every
keystroke, can be distracting. You'll say, "Don't use `eager' in that case".
But I don't think the use cases are so cut and dried.

Automatic update is useful even without initial display. It means you need
not keep hitting `TAB' to see what the candidates are.

Initial display is likely to be useful even without automatic update (but I
don't have a great use case here).

    > gets called inside `completing-read', upon insertion, but I
    > see no way to get `completing-read' to display *Completions*
    > without any user action.

    IIRC you can do it from minibuffer-setup-hook.

I've tried that. This is not about minibuffer setup, and it's not about
completion-list setup (for which there is also a hook). This is about
_completion_ setup.

I believe that what's needed is a hook that kicks in as soon as
completing-read (and read-file-name...) displays its prompt (just before or
after). That hook doesn't exist.

RE: completion-auto-help

[Drew Adams]

        > gets called inside `completing-read', upon insertion, but I
        > see no way to get `completing-read' to display *Completions*
        > without any user action.

        IIRC you can do it from minibuffer-setup-hook.

    I've tried that. This is not about minibuffer setup, and it's not about
    completion-list setup (for which there is also a hook). This is about
    _completion_ setup.

    I believe that what's needed is a hook that kicks in as soon as
    completing-read (and read-file-name...) displays its prompt
    (just before or
    after). That hook doesn't exist.


My bad. I did try `minibuffer-setup-hook' previously with no luck, but I
must not have done things correctly. I just retried, and it does what I want
in this regard.

 (add-hook 'minibuffer-setup-hook 'show-it)

 (defun show-it ()
    "Show *Completions* on empty input."
    (with-output-to-temp-buffer "*Completions*"
      (display-completion-list (all-completions "" my-completions)))

RE: completion-auto-help

[Drew Adams]

            > gets called inside `completing-read', upon insertion, but I
            > see no way to get `completing-read' to display *Completions*
            > without any user action.

            IIRC you can do it from minibuffer-setup-hook.

        I've tried that. This is not about minibuffer setup, and
        it's not about
        completion-list setup (for which there is also a hook).
        This is about _completion_ setup.

        I believe that what's needed is a hook that kicks in as soon as
        completing-read (and read-file-name...) displays its prompt
        (just before or after). That hook doesn't exist.


    My bad. I did try `minibuffer-setup-hook' previously with no luck, but I
    must not have done things correctly. I just retried, and it
    does what I want
    in this regard.

     (add-hook 'minibuffer-setup-hook 'show-it)

     (defun show-it ()
        "Show *Completions* on empty input."
        (with-output-to-temp-buffer "*Completions*"
          (display-completion-list (all-completions "" my-completions)))

Guess I'll have to flip-flop again. minibuffer-setup-hook is used for all
entrance to the minibuffer, not just for completion functions.

I'm looking for a hook specific to completion. I think we still need a hook
that runs whenever a completion function (e.g. completing-read) displays its
prompt.

Re: completion-auto-help

[Stefan Monnier]

> Guess I'll have to flip-flop again. minibuffer-setup-hook is used for all
> entrance to the minibuffer, not just for completion functions.

> I'm looking for a hook specific to completion.  I think we still need a hook
> that runs whenever a completion function (e.g. completing-read) displays its
> prompt.

Check the value of minibuffer-completion-table in your hook.


        Stefan

RE: completion-auto-help

[Drew Adams]

    > minibuffer-setup-hook is used for all
    > entrance to the minibuffer, not just for completion functions.

    > I'm looking for a hook specific to completion.  I think we
    > still need a hook that runs whenever a completion function
    > (e.g. completing-read) displays its prompt.

    Check the value of minibuffer-completion-table in your hook.

Not sure what you mean. Do you mean to check, inside the hook, whether that
var is non-nil, and use that test to determine whether or not we are
completing? That is, use (not (null minibuffer-completion-table)) as a kind
of `completing-p'?

If that's what you mean, it doesn't seem to work -
`minibuffer-completion-table' is not nil, even when doing things like
read-from-minibuffer (which doesn't use completion).

Hoping I misunderstand and there is a simple solution.

Re: completion-auto-help

[Stefan Monnier]

> Not sure what you mean.  Do you mean to check, inside the hook, whether
> that var is non-nil, and use that test to determine whether or not we are
> completing?  That is, use (not (null minibuffer-completion-table)) as
> a kind of `completing-p'?

Yes.

> If that's what you mean, it doesn't seem to work -
> `minibuffer-completion-table' is not nil, even when doing things like
> read-from-minibuffer (which doesn't use completion).

That's rather odd.  Can you show a recipe to reproduce it?


        Stefan

RE: completion-auto-help

[Drew Adams]

    > use (not (null minibuffer-completion-table)) as a kind of
    > `completing-p'?  it doesn't seem to work -
    > `minibuffer-completion-table' is not nil, even when doing things like
    > read-from-minibuffer (which doesn't use completion).
    
    That's rather odd.  Can you show a recipe to reproduce it?

My bad. In emacs -q, it works. I must be changing the table in my context.

Thanks.

Re: completion-auto-help

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Fri, 11 Nov 2005 14:10:30 -0500
> Cc: Emacs-Devel <emacs-devel@gnu.org>
> 
> > If it is only a user who sets such a value, then shouldn't the non-nil,
> > non-t behavior be documented for the user option? I don't see that, as I
> > mentioned.
> 
> It's not documented, because there's no place to document it:
> completion-auto-help is part of the basic completion facilities, whereas the
> added behavior is only provided in complete.el which is a separate package.

I documented that in the doc string of partial-completion-mode.

Re: completion-auto-help

[Richard M. Stallman]

    > It's not documented, because there's no place to document it:
    > completion-auto-help is part of the basic completion facilities, whereas the
    > added behavior is only provided in complete.el which is a separate package.

    I documented that in the doc string of partial-completion-mode.

I think it should be documented in the doc string of
completion-auto-help above all.  Could you add something there?

Re: completion-auto-help

[Eli Zaretskii]

> From: "Richard M. Stallman" <rms@gnu.org>
> CC: monnier@iro.umontreal.ca, drew.adams@oracle.com,
> 	emacs-devel@gnu.org
> Date: Sun, 20 Nov 2005 18:23:11 -0500
> 
>     > It's not documented, because there's no place to document it:
>     > completion-auto-help is part of the basic completion facilities, whereas the
>     > added behavior is only provided in complete.el which is a separate package.
> 
>     I documented that in the doc string of partial-completion-mode.
> 
> I think it should be documented in the doc string of
> completion-auto-help above all.  Could you add something there?

Done.

Re: completion-auto-help

[Richard M. Stallman]

    complete.el extends the meaning of the variable so that a non-nil non-t
    value means "show the help but only on the second attempt to complete".
    I.e. if TAB finds nothing to complete, the first TAB will just say "[Next
    char not unique]" without bringing up the *Completions* buffer, and the
    second TAB will then bring up the *Completions* buffer.
    It happens to be my favorite behavior.

Could you document this?  It seems not to be documented now,
not even in complete.el.  It would be convenient to document this
in the doc string of that variable.