feature/completions-customs 7b62bef2d3: Fix new option completions-max-height and new values for completion-auto-help

[Juri Linkov]

branch: feature/completions-customs
commit 7b62bef2d3ed7d998b8d50b7ce7f7ec8c5fe7db1
Author: Juri Linkov <juri@linkov.net>
Commit: Juri Linkov <juri@linkov.net>

    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.
---
 doc/emacs/mini.texi | 10 ++++++----
 etc/NEWS            | 17 ++++++++++-------
 lisp/minibuffer.el  | 13 +++++++++----
 3 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index afacb9c7cd..7224c48613 100644
--- 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 05f219ca03..9ea6512dca 100644
--- 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 148ba7a873..9ac18f8df9 100644
--- 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 _)