Fix documentation of the new completion-related features

* etc/NEWS:
* lisp/minibuffer.el (completion-auto-help):
* doc/lispref/text.texi (Special Properties):
* doc/emacs/mini.texi (Completion Options): Fix wording of
recently added documentation and customization options.

1 files changed, 29 insertions, 20 deletions

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index 24517262fa6..72a3cf24912 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -628,14 +628,19 @@ commands never display the completion list buffer; you must type
 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.  With the previous values and the default
-@code{t} the completions are hidden when some unique completion is
-executed.  If @code{completion-auto-help} is set to @code{always}, the
-completion commands are always shown after a completion attempt, or
-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.
+completion list buffer.  If the value is @code{always}, the completion
+list buffer is always shown when completion is attempted.
+
+The display of the completion list buffer after it is shown for the
+first time is also controlled by @code{completion-auto-help}.  If the
+value is @code{t} or @code{lazy}, the window showing the completions
+pops down when Emacs is able to complete (and may pop up again if
+Emacs is again unable to complete after you type some more text); if
+the value is @code{always}, the window pops down only when you exit
+the completion.  The value @code{visible} is a hybrid: it behaves like
+@code{t} when it decides whether to pop up the window showing the
+completion list buffer, and like @code{always} when it decides whether
+to pop it down.
 
 @vindex completion-cycle-threshold
   If @code{completion-cycle-threshold} is non-@code{nil}, completion
@@ -668,21 +673,25 @@ Alists,,Action Alists for Buffer Display, elisp, The Emacs Lisp
 Reference Manual}).
 
 @vindex completions-header-format
-The variable @code{completions-header-format} is a formatted string to
+The variable @code{completions-header-format} is a format spec 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}).
+candidates.  If it contains a @samp{%s} construct, that get replaced
+by the number of completions shown in the completion list buffer.  To
+suppress the display of the heading line, customize this variable to
+@code{nil}.  The string that is the value of this variable can have
+text properties to change the visual appearance of the heading line;
+some useful properties @code{face} or @code{cursor-intangible}
+(@pxref{Special Properties,,Properties with Special Meanings, elisp,
+The Emacs Lisp Reference Manual}).
 
 @vindex completions-highlight-face
-When @code{completions-highlight-face} is a face name, then the
-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}.
+When @code{completions-highlight-face} names a face, the current
+completion candidate, the one that will be selected by typing
+@kbd{@key}RET}} or clicking the mouse, will be highlighted using that
+face.  The default value of this variable is
+@code{completions-highlight}; the value is @code{nil} disables this
+highlighting.  This feature uses the special text property
+@code{cursor-face}.
 
 @node Minibuffer History
 @section Minibuffer History