; Fix documentation of 'completion-auto-deselect'

* lisp/minibuffer.el (completion-auto-deselect): Doc fix.

* etc/NEWS: Improve wording of corresponding entry.

2 files changed, 20 insertions, 14 deletions

diff --git a/etc/NEWS b/etc/NEWS
index e14ab4aed27..03a40c11c5b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -639,13 +639,15 @@ then all these keys have their usual meaning in the minibuffer.
 This option is supported for in-buffer completion as well.
 
 *** Selected completion candidates are deselected on typing.
-When a user types, point in the *Completions* window will be moved off
-any completion candidates.  'minibuffer-choose-completion' ('M-RET')
-will still choose a previously-selected completion candidate, but the
-new command 'minibuffer-choose-completion-or-exit' (bound by
-'minibuffer-visible-completions') will exit with the minibuffer
-contents instead.  The deselection behavior can be controlled with the
-new user option 'completion-auto-deselect'.
+When you type at the minibuffer prompt, the current completion
+candidate will be un-highlighted,and point in the *Completions* window
+will be moved off that candidate.  'minibuffer-choose-completion'
+('M-RET') will still choose a previously-selected completion
+candidate, but the new command 'minibuffer-choose-completion-or-exit'
+(bound to 'RET' by 'minibuffer-visible-completions') will exit with
+the minibuffer contents instead.  This deselection behavior can be
+controlled with the new user option 'completion-auto-deselect', which
+is t by default.
 
 *** New value 'historical' for user option 'completions-sort'
 When 'completions-sort' is set to 'historical', completion candidates
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 2ddaf0af120..d35a487a6cf 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -961,6 +961,8 @@ is at its default value `grow-only'."
                (reverse multi-message-list)
                multi-message-separator)))
 
+(defvar touch-screen-current-tool)
+
 (defun clear-minibuffer-message ()
   "Clear message temporarily shown in the minibuffer.
 Intended to be called via `clear-message-function'."
@@ -2433,12 +2435,15 @@ These include:
     (fit-window-to-buffer win completions-max-height)))
 
 (defcustom completion-auto-deselect t
-  "If non-nil, deselect the selected completion candidate when you type.
-
-A non-nil value means that after typing, point in *Completions*
-will be moved off any completion candidates.  This means
-`minibuffer-choose-completion-or-exit' will exit with the
-minibuffer's current contents, instead of a completion candidate."
+  "If non-nil, deselect current completion candidate when you type in minibuffer.
+
+A non-nil value means that after typing at the minibuffer prompt,
+any completion candidate highlighted in *Completions* window (to
+indicate that it is the selected candidate) will be un-highlighted,
+and point in the *Completions* window will be moved off such a candidate.
+This means that `RET' (`minibuffer-choose-completion-or-exit') will exit
+the minubuffer with the minibuffer's current contents, instead of the
+selected completion candidate."
   :type '(choice (const :tag "Candidates in *Completions* stay selected as you type" nil)
                  (const :tag "Typing deselects any completion candidate in *Completions*" t))
   :version "30.1")
@@ -3101,7 +3106,6 @@ displaying the *Completions* buffer exists."
   "<down>"  (minibuffer-visible-completions-bind #'minibuffer-next-line-completion)
   "RET"     (minibuffer-visible-completions-bind #'minibuffer-choose-completion-or-exit)
   "C-g"     (minibuffer-visible-completions-bind #'minibuffer-hide-completions))
-
 
 ;;; Completion tables.