Re: Select completions from the minibuffer

[Ergus <spacibba@aol.com>]

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.