master ab414c5661: Improve documentation of 'completion-auto-select'

[Eli Zaretskii]

branch: master
commit ab414c5661cc4db23f05f017ef81add2e502171f
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve documentation of 'completion-auto-select'
    
    * lisp/simple.el (completion-auto-select):
    * doc/emacs/mini.texi (Completion Options): Improve documentation
    and description of customization options of 'completion-auto-select'.
---
 doc/emacs/mini.texi | 13 ++++++++-----
 lisp/simple.el      | 18 +++++++++++-------
 2 files changed, 19 insertions(+), 12 deletions(-)

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index dd78262aeb..eeb87972cc 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -643,11 +643,14 @@ completion list buffer, and like @code{always} when it 
decides whether
 to pop it down.
 
 @vindex completion-auto-select
-  The completions window can be automatically selected.  To enable
-this behavior, customize the user option @code{completion-auto-select}
-to @code{t} and pressing @key{TAB} will switch to the completion list
-buffer when it pops up that buffer.  If the value is
-@code{second-tab}, then the first @key{TAB} will pop up the
+  Emacs can optionally select the window showing the completions when
+it shows that window.  To enable this behavior, customize the user
+option @code{completion-auto-select} to @code{t}, which changes the
+behavior of @key{TAB} when Emacs pops up the completions: pressing
+@kbd{@key{TAB}} will switch to the completion list buffer, and you can
+then move to a candidate by cursor motion commands and select it with
+@kbd{@key{RET}}.  If the value of @code{completion-auto-select} is
+@code{second-tab}, then the first @kbd{@key{TAB}} will pop up the
 completions list buffer, and the second one will switch to it.
 
 @vindex completion-cycle-threshold
diff --git a/lisp/simple.el b/lisp/simple.el
index 921fba3416..c60abcb1f4 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -9146,13 +9146,17 @@ This affects the commands `next-completion' and
 
 (defcustom completion-auto-select nil
   "Non-nil means to automatically select the *Completions* buffer.
-When the value is t, then pressing TAB will switch to the completion list
-buffer when it pops up that buffer.  If the value is `second-tab', then the
-first TAB will pop up the completions list buffer, and the second one will
-switch to it."
-  :type '(choice (const :tag "Disabled" nil)
-                 (const :tag "Select window on first tab" t)
-                 (const :tag "Select window on second-tab" second-tab))
+When the value is t, pressing TAB will switch to the completion list
+buffer when Emacs pops up a window showing that buffer.
+If the value is `second-tab', then the first TAB will pop up the
+window shwoing the completions list buffer, and the next TAB will
+switch to that window.
+See `completion-auto-help' for controlling when the window showing
+the completions is popped up and down."
+  :type '(choice (const :tag "Don't auto-select completions window" nil)
+                 (const :tag "Select completions window on first TAB" t)
+                 (const :tag
+                        "Select completions window on second TAB" second-tab))
   :version "29.1"
   :group 'completion)