Re: Select completions from the minibuffer

[Eli Zaretskii]

> 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:

     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?

  +@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.

             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.)

  +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?

  +@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.

  +@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.

  +@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.  I suggest something like

  when point is inside text which has this face