From 71aec1d0444ab351a4f20ae1ed10dee7bc12af88 Mon Sep 17 00:00:00 2001
From: Juri Linkov <juri@linkov.net>
Date: Thu, 24 Mar 2022 19:54:14 +0200
Subject: [PATCH] Small fixes for the new feature 'second-tab' of
 'completion-auto-select'

* lisp/simple.el (completion-auto-select): Extend the docstring.
---
 doc/emacs/mini.texi | 10 +++++-----
 etc/NEWS            |  7 ++++---
 lisp/minibuffer.el  | 10 +++++-----
 lisp/simple.el      | 14 +++++++++-----
 4 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index 181cade80b3..dd78262aeb8 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -643,12 +643,12 @@ 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
+  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 pops up the
-completions list buffer and the second one will switch to it.
+@code{second-tab}, then the first @key{TAB} will pop up the
+completions list buffer, and the second one will switch to it.
 
 @vindex completion-cycle-threshold
   If @code{completion-cycle-threshold} is non-@code{nil}, completion
diff --git a/etc/NEWS b/etc/NEWS
index 9633a1ff6f6..d26c6568b9b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -585,11 +585,12 @@ value.
 
 ** Minibuffer and Completions
 
++++
 *** The "*Completions*" buffer can now be automatically selected.
 To enable this behavior, customize the user option
-'completion-auto-select' to t and pressing 'TAB' will switch to the
-"*Completions*" buffer when it pops up that buffer. If the value is
-'second-tab', then the first tab will display "*Completions*" and the
+'completion-auto-select' to t, then pressing 'TAB' will switch to the
+"*Completions*" buffer when it pops up that buffer.  If the value is
+'second-tab', then the first tab will display "*Completions*", and the
 second one will switch to the "*Completions*" buffer.
 
 *** New user option 'completion-wrap-movement'.
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 742d39f2d29..d8df1799c93 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -1413,20 +1413,20 @@ scroll the window of possible completions."
     (let ((window minibuffer-scroll-window))
       (with-current-buffer (window-buffer window)
         (cond
-         ;; here this is possible only when second-tab, so jump now.
+         ;; Here this is possible only when second-tab, so jump now.
          (completion-auto-select
           (switch-to-completions))
-         ;; reverse tab
+         ;; Reverse tab
          ((equal (this-command-keys) [backtab])
           (if (pos-visible-in-window-p (point-min) window)
-              ;; If beginning is in view, scroll up to the end
+              ;; If beginning is in view, scroll up to the end.
               (set-window-point window (point-max))
             ;; Else scroll down one screen.
             (with-selected-window window (scroll-down))))
-         ;; normal tab
+         ;; Normal tab
          (t
           (if (pos-visible-in-window-p (point-max) window)
-              ;; If end is in view, scroll up to the end
+              ;; If end is in view, scroll up to the end.
               (set-window-start window (point-min) nil)
             ;; Else scroll down one screen.
             (with-selected-window window (scroll-up)))))
diff --git a/lisp/simple.el b/lisp/simple.el
index f2296086908..6dd8d141ae1 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -9145,9 +9145,13 @@ This affects the commands `next-completion' and
   :group 'completion)
 
 (defcustom completion-auto-select nil
-  "Non-nil means to automatically select the *Completions* buffer."
-  :type '(choice (const :tag "Select window" t)
-                 (const :tag "Disabled" 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))
   :version "29.1"
   :group 'completion)
@@ -9413,8 +9417,8 @@ Called from `temp-buffer-show-hook'."
 	(insert (substitute-command-keys
 		 "In this buffer, type \\[choose-completion] to \
 select the completion near point.\n\n")))))
-  (if (eq completion-auto-select t)
-      (switch-to-completions)))
+  (when (eq completion-auto-select t)
+    (switch-to-completions)))
 
 (add-hook 'completion-setup-hook #'completion-setup-function)
 
-- 
2.39.5