Re: Select completions from the minibuffer

[Ergus]

On Tue, Mar 22, 2022 at 03:38:20PM +0200, Eli Zaretskii wrote:
> > From: Juri Linkov <juri@linkov.net>
> > Date: Tue, 22 Mar 2022 10:24:00 +0200
> > Cc: Ergus <spacibba@aol.com>, emacs-devel@gnu.org
> >
> > >> Since Ergus finished implementing new features in the
> > >> feature/completions-customs branch (and I fixed small things
> > >> like renaming completion-header-format to completions-header-format),
> > >> the branch is ready for merging to master now.  After that
> > >> we could add more patches based on new features.
> > >
> > > Sounds good to me.
> >
> > So now the branch is merged to master.  Thanks Ergus for implementing
> > these features.
>
> Thanks, but please see some questions/comments below, and either fix
> them or explain what you meant so that I could fix them:
Thanks to you

>     If @code{completion-auto-help} is set to @code{nil}, the completion
>   commands never display the completion list buffer; you must type
>  -@kbd{?}  to display the list.  If the value is @code{lazy}, Emacs only
>  +@kbd{?} to display the list.  If the value is @code{lazy}, Emacs only
>   shows the completion list buffer on the second attempt to complete.
>   In other words, if there is nothing to complete, the first @key{TAB}
>   echoes @samp{Next char not unique}; the second @key{TAB} shows the
>  -completion list buffer.
>  +completion list buffer.  With the previous values and the default
>
> What are those "previous values" which you mention here?

t, nil, lazy

>  +@code{t} the completions are hidden when some unique completion is
>  +executed.
>
> What do you mean by "unique completion is executed"?  Both the
> "unique" and the "executed" parts need clarification.
unique means that, there is a single candidate o prefix so the <tab>
"added" some letter. example: com<tab>pi<tab> -> compil

The first tab shows completions but the second hides it... it is a bit
confusing compared to any other completion engine (bash, zsh,
fish)... that's why I started this changes...

> If @code{completion-auto-help} is set to @code{always}, the
>  +completion commands are always shown after a completion attempt, or
>
> "Commands"? didn't you mean "candidates" or "alternatives"?  (The same
> problem exists in the doc string of this variable, btw.)
Maybe candidates is better,

>  +updated if they are already visible.  If the value is @code{visible},
>  +then completions are not hidden, but updated if they are already
>  +visible while the current behavior stays the same as default if they
>  +are not.
>
> I think the last sentence should be reworded as follows:
>
>  If the value is @code{visible}, Emacs displays completion the
>  completion alternatives when it is unable to complete for the first
>  time; thereafter the completion list buffer remains visible and is
>  updated as you type.
>
> Is this accurate and correct?
"and is updated as you type."

I am not sure that last part is accurate. updates need <tab> to update
in all cases. "as you type" suggests more an icomplete-like behavior I
thinks.

>  +@vindex completions-header-format
>  +The variable @code{completions-header-format} is a formatted string to
>  +control the informative line shown before the completions list of
>  +candidates.  It may contain a @code{%s} to show the total number of
>  +completions.  When it is @code{nil}, the message is totally suppressed.
>  +Text properties may be added to change the appearance, some useful
>  +ones are @code{face} or @code{cursor-intangible} (@pxref{Special
>  +Properties,,Properties with Special Meanings, elisp, The Emacs Lisp
>  +Reference Manual}).
>
> Shouldn't this have a cross-reference to where header-line-format is
> described?  This variable determines the format of the header-line
> shown in the window that displays the *Completions* buffer, right?  So
> knowing what can be used in header-line-format should be useful.
You are right... I just didn't even know there was a header-line-format ;p

>  +@vindex completions-highlight-face
>  +When @code{completions-highlight-face} is a face name, then the
>
> Saying "face name" might mislead people to think this is a string.  It
> is better to say "If the value of this variable is a face, ..."
>
> Also, I'd lose "then": it's redundant here.
>
>  +current completion candidate will be highlighted with that face.  The
>  +default value is @code{completions-highlight}.  When the value is
>  +@code{nil}, no highlighting is performed.  This feature sets the text
>  +property @code{cursor-face}.
>
> This should explain what is "the current completion candidate".  It
> isn't trivial: trying the current defaults with completion commands, I
> sometimes see a candidate highlighted, and sometimes don't.  I
> couldn't figure out why.

when it is not highlighting? So far the only way to not have a candidate
highlighted is when there is not candidate effectively selected (like
when completions are just updated (with no completion-auto-select) and
the cursor is before the help line; I that case there is not "current
candidate"); a return in that moment won't execute anything because
there is nothing to select, so "current completion candidate" means
that... Maybe you have a better way to explain it?

>  +@item cursor-face
>  +@kindex cursor-face @r{(text property)}
>  +This property is similar to @code{mouse-face}, but the face is used if
>  +the cursor (instead of mouse) is on or near the character.
>                                                   ^^^^^^^^^
> Which character?  There's no reference to "characters" in the
> preceding text, so this is confusing.
The previous text for mouse-face says:

‘mouse-face’
     This property is used instead of ‘face’ when the mouse is on or
     near the character.

>  I suggest something like
>  when point is inside text which has this face

Maybe: when point is inside text which has cursor-face property

Please if you have the time change it... Otherwise I will do in some
days.