4 files changed, 71 insertions, 55 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
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index edb75b453c8..f76512c5a0b 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3541,10 +3541,10 @@ special modes that implement their own highlighting.
 
 @item mouse-face
 @kindex mouse-face @r{(text property)}
-This property is used instead of @code{face} when the mouse is on or
-near the character.  For this purpose, ``near'' means that all text
-between the character and where the mouse is have the same
-@code{mouse-face} property value.
+This property is used instead of @code{face} when the mouse pointer
+hovers over the text which has this property.  When this happens, the
+entire stretch of text that has the same @code{mouse-face} property
+value, not just the character under the mouse, is highlighted.
 
 Emacs ignores all face attributes from the @code{mouse-face} property
 that alter the text size (e.g., @code{:height}, @code{:weight}, and
@@ -3553,14 +3553,17 @@ unhighlighted text.
 
 @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.  Near has
-the same meaning that in @code{mouse-face} and the highlighting only
-takes effect if the mode @code{cursor-face-highlight-mode} is enabled;
-otherwise no highlighting is performed.  When the variable
+@findex cursor-face-highlight-mode
+@vindex cursor-face-highlight-nonselected-window
+This property is similar to @code{mouse-face}, but it is used when
+point (not the mouse) is inside text that has this property.  The
+highlighting happens only if the mode
+@code{cursor-face-highlight-mode} is enabled.  When the variable
 @code{cursor-face-highlight-nonselected-window} is non-@code{nil}, the
-text is highlighted even if the window is not selected that is similar
-to @code{highlight-nonselected-windows} for the region.
+text with this face is highlighted even if the window is not selected,
+similarly to what @code{highlight-nonselected-windows} does for the
+region (@pxref{Mark,, The Mark and the Region, emacs, The GNU Emacs
+Manual}).
 
 @item fontified
 @kindex fontified @r{(text property)}
diff --git a/etc/NEWS b/etc/NEWS
index e64fe2d23bd..abee5fcb992 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -579,28 +579,29 @@ alphabetical (the default), or a custom sort function.
 
 +++
 *** New values for the 'completion-auto-help' user option.
-There are two new values to control the way "*Completions*" behave after
-a 'TAB' if completion is not unique.  'always' updates or shows
-the "*Completions*" buffer after any attempt to complete.  'visual' is
-like 'always', but only update the completions if they are already
-visible.  The default value 't' always hides the completion buffer after
-some completion is made.
+There are two new values to control the way the "*Completions*" buffer
+behaves after pressing a 'TAB' if completion is not unique.  The value
+'always' updates or shows the "*Completions*" buffer after any attempt
+to complete.  The value 'visual' is like 'always', but only updates
+the completions if they are already visible.  The default value 't'
+always hides the completion buffer after some completion is made.
 
 +++
 *** New user option 'completions-max-height'.
 This option limits the height of the "*Completions*" buffer.
 
 +++
-*** New user option 'completions-header-format'
-This is a string to control the message to show before completions.
-It may contain a "%s" to show the total number of completions.  If nil no
-completions are shown.
+*** New user option 'completions-header-format'.
+This is a string to control the heading line to show in the
+"*Completions*" buffer before the list of completions.
+If it contains "%s", that is replaced with the number of completions.
+If nil, the heading line is not shown.
 
 +++
 *** New user option 'completions-highlight-face'.
-When this user option is a face name, it highlights the current
-candidate in the "*Completions*" buffer with that face.  When the
-value is nil, no highlighting is performed at all.
+When this user option names a face, the current
+candidate in the "*Completions*" buffer is highlighted with that face.
+The nil value disables this highlighting.
 
 ** Isearch and Replace
 
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 00d4560865c..c4fb1c00391 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -894,20 +894,23 @@ If the current buffer is not a minibuffer, erase its entire contents."
 
 (defcustom completion-auto-help t
   "Non-nil means automatically provide help for invalid completion input.
-If the value is t the *Completions* buffer is displayed whenever completion
+If the value is t, the *Completions* buffer is displayed whenever completion
 is requested but cannot be done.
 If the value is `lazy', the *Completions* buffer is only displayed after
 the second failed attempt to complete.
-If the value is 'always', the completion commands are always shown
-after a completion attempt, or updated if they are already visible.
-If the value is '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."
-  :type '(choice (const :tag "Disabled" nil)
-                 (const :tag "Enabled legacy" t)
-                 (const :tag "After a second attempt" lazy)
-                 (const :tag "Visible update" visible)
-                 (const :tag "Always update" always)))
+If the value is 'always', the *Completions* buffer is always shown
+after a completion attempt, and the list of completions is updated if
+already visible.
+If the value is 'visible', the *Completions* buffer is displayed
+whenever completion is requested but cannot be done for the first time,
+but remains visible thereafter, and the list of completions in it is
+updated for subsequent attempts to complete.."
+  :type '(choice (const :tag "Don't show" nil)
+                 (const :tag "Show only when cannot complete" t)
+                 (const :tag "Show after second failed completion attempt" lazy)
+                 (const :tag
+                        "Leave visible after first failed completion" visible)
+                 (const :tag "Always visible" always)))
 
 (defvar completion-styles-alist
   '((emacs21