Fix new option completions-max-height and new values for completion-auto-help

* doc/emacs/mini.texi (Completion Options): Fix pxref for
"Buffer Display Action Alists".

* lisp/minibuffer.el (completion-auto-help): Explain new values in docstring.
(completions-max-height): Use choice to allow nil.

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index afacb9c7cde52b6555bac951b7718af1ea34b8bb..7224c48613948f02d85eaefff799c9476160d841 100644 (file)
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -632,7 +632,7 @@ 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}
+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.
@@ -660,13 +660,15 @@ and if @code{one-column}, just use a single column.
 
 @vindex completions-max-height
   When @code{completions-max-height} is non-@code{nil} it limits the
-size of the completions window. It is specified in lines and include
+size of the completions window.  It is specified in lines and include
 mode, header line and a bottom divider, if any.  For a more complex
 control of the Completion window display properties you can use
-@code{display-buffer-alist} (@pxref{Buffer Display Action Alists}).
+@code{display-buffer-alist} (@pxref{Buffer Display Action
+Alists,,Action Alists for Buffer Display, elisp, The Emacs Lisp
+Reference Manual}).
 
 @vindex completions-highlight-mode
-When the mode @{completions-highlight-mode} is active the candidate
+When the mode @code{completions-highlight-mode} is active the candidate
 under the cursor is highlighted when the completion window is
 selected.  The mode uses the face @code{completions-highlight}.
 

diff --git a/etc/NEWS b/etc/NEWS
index 05f219ca03e983a859fc5b1df1c2b9a40d41632e..9ea6512dcac2e4b5e495b6201bb178feded4da83 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -554,20 +554,23 @@ This option controls the sorting of the completion candidates in
 the "*Completions*" buffer.  Available styles are no sorting,
 alphabetical (the default), or a custom sort function.
 
-*** New values for the 'completion-auto-select' option.
++++
+*** New values for the 'completion-auto-help' option.
 There are two new values to control the way *Completions* behave after
-a <tab> if completion is not unique.  'always updates or shows
-the *Completions* buffer after any attempt to complete.  'visual is
-like 'always, but only update the completions if they are already
-visible.  The default value t always hide the completion buffer after
+a <tab> if completion is not unique.  'always' updates or shows
+the *Completions* buffer after any attempt to complete.  'visual' is
+like 'always', but only update the completions if they are already
+visible.  The default value 't' always hides the completion buffer after
 some completion is made.
 
++++
 *** New user option 'completions-max-height'.
 This option limits the height of the "*Completions*" buffer.
 
-*** New mode completions-highlight.
++++
+*** New mode 'completions-highlight-mode'.
 This mode highlights the current candidate in the *Completions* buffer
-with the completions-highlight face.
+with the 'completions-highlight' face.
 
 ** Isearch and Replace
 

diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 148ba7a8730e41e52904f1f6f97fd0121fd2a34a..9ac18f8df9e62b9ed7e8b6c62ffa85df24122ce3 100644 (file)
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -897,7 +897,12 @@ If the current buffer is not a minibuffer, erase its entire contents."
 If the value is t the *Completions* buffer is displayed whenever completion
 is requested but cannot be done.
 If the value is `lazy', the *Completions* buffer is only displayed after
-the second failed attempt to complete."
+the second failed attempt to complete.
+If the value is 'always', the completion commands are always shown
+after a completion attempt or updated if they are already visible.
+If the value is '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."
   :type '(choice (const :tag "Disabled" nil)
                  (const :tag "Enabled legacy" t)
                  (const :tag "After a second attempt" lazy)
@@ -2141,14 +2146,14 @@ candidates."
 
 (defface completions-highlight
   '((t :inherit highlight :extend t))
-  "Default face for highlighting the current line in Hl-Line mode."
+  "Default face for highlighting the current line in `completions-highlight-mode'."
   :version "29.1")
 
 (defvar completions--overlay nil
   "Overlay to use when `completions-highlight-mode' is enabled.")
 
 (defun completions-highlight--delete ()
-  "Highlight current candidate in *Completions* when ``completions-highlight''."
+  "Highlight current candidate in *Completions* with `completions-highlight'."
   (when (overlayp completions--overlay)
     (delete-overlay completions--overlay)))
 
@@ -2253,7 +2258,7 @@ variables.")
 
 (defcustom completions-max-height nil
   "Maximum height for *Completions* buffer."
-  :type 'natnum
+  :type '(choice (const nil) natnum)
   :version "29.1")
 
 (defun completions--fit-window-to-buffer (&optional win &rest _)