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'.

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index dd78262aeb88d04bdbf73d0d3db158226be6dab7..eeb87972cc3ae3c5b634db414dd03175883ab724 100644 (file)
--- 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 921fba34169ce3798790dc77630f287f5e362d5e..c60abcb1f4344f33c5675db42647707b49d7e9b8 100644 (file)
--- 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)