2 files changed, 43 insertions, 31 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)}