feature/completions-customs eba9c473a8: Small fixes for new completions features

[Juri Linkov]

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

    Small fixes for new completions features
    
    * lisp/minibuffer.el (completions-header-format):
    Rename from completion-header-format.
    (completions-highlight, completions-highlight-face):
    Move up before first use.
---
 doc/emacs/mini.texi   | 24 ++++++++++++------------
 doc/lispref/text.texi | 13 ++++++-------
 etc/NEWS              | 23 +++++++++++------------
 lisp/minibuffer.el    | 43 +++++++++++++++++++++----------------------
 lisp/simple.el        |  4 ++--
 5 files changed, 52 insertions(+), 55 deletions(-)

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index b66454f930..24517262fa 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -624,15 +624,15 @@ completion alternatives in the completion list.
 @vindex completion-auto-help
   If @code{completion-auto-help} is set to @code{nil}, the completion
 commands never display the completion list buffer; you must type
-@kbd{?}  to display the list.  If the value is @code{lazy}, Emacs only
+@kbd{?} to display the list.  If the value is @code{lazy}, Emacs only
 shows the completion list buffer on the second attempt to complete.
 In other words, if there is nothing to complete, the first @key{TAB}
 echoes @samp{Next char not unique}; the second @key{TAB} shows the
 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}
+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},
 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.
@@ -659,29 +659,29 @@ changed by changing the @code{completions-format} user 
option.  If
 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
+  When @code{completions-max-height} is non-@code{nil}, it limits the
 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
+control of the Completion window display properties, you can use
 @code{display-buffer-alist} (@pxref{Buffer Display Action
 Alists,,Action Alists for Buffer Display, elisp, The Emacs Lisp
 Reference Manual}).
 
-@vindex completion-header-format
-The variable @code{completion-header-format} is a formatted string to
+@vindex completions-header-format
+The variable @code{completions-header-format} is a formatted string to
 control the informative line shown before the completions list of
-candidates.  It may contain a ``%s'' to show the total number of
-completions.  When it is @code{nil} the message is totally suppressed.
+candidates.  It may contain a @code{%s} to show the total number of
+completions.  When it is @code{nil}, the message is totally suppressed.
 Text properties may be added to change the appearance, some useful
 ones are @code{face} or @code{cursor-intangible} (@pxref{Special
 Properties,,Properties with Special Meanings, elisp, The Emacs Lisp
 Reference Manual}).
 
 @vindex completions-highlight-face
-When @code{completions-highlight-face} is a face name; then the
+When @code{completions-highlight-face} is a face name, then the
 current completion candidate will be highlighted with that face.  The
 default value is @code{completions-highlight}.  When the value is
-@code{nil} no highlight is performed. This feature sets the text
+@code{nil}, no highlighting is performed.  This feature sets the text
 property @code{cursor-face}.
 
 @node Minibuffer History
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 30036675e1..edb75b453c 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3553,15 +3553,14 @@ unhighlighted text.
 
 @item cursor-face
 @kindex cursor-face @r{(text property)}
-This property is similar to @code{mouse-face} but the face is used if
+This property is similar to @code{mouse-face}, but the face is used if
 the cursor (instead of mouse) is on or near the character.  Near has
-the same meaning than in @code{mouse-face} and the highlight only
+the same meaning that in @code{mouse-face} and the highlighting only
 takes effect if the mode @code{cursor-face-highlight-mode} is enabled;
-otherwise no highlight is performed.  When the variable
-@code{cursor-face-highlight-nonselected-window} is non-@code{nil} the
-text is highlighted even if the window is not selected similar to
-@code{highlight-nonselected-windows} for the region.  The default
-value is the same of @code{cursor-in-non-selected-windows}.
+otherwise no highlighting is performed.  When the variable
+@code{cursor-face-highlight-nonselected-window} is non-@code{nil}, the
+text is highlighted even if the window is not selected that is similar
+to @code{highlight-nonselected-windows} for the region.
 
 @item fontified
 @kindex fontified @r{(text property)}
diff --git a/etc/NEWS b/etc/NEWS
index bb92e46310..026a9d1f7f 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -556,9 +556,9 @@ alphabetical (the default), or a custom sort function.
 
 +++
 *** New values for the 'completion-auto-help' option.
-There are two new values to control the way *Completions* behave after
+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
+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.
@@ -568,17 +568,16 @@ some completion is made.
 This option limits the height of the "*Completions*" buffer.
 
 +++
-*** New option 'completion-header-format'
+*** New option 'completions-header-format'
 This is a string to control the message to show before completions.
-It may contain a %s to show the total number of completions. If nil no
+It may contain a "%s" to show the total number of completions. If nil no
 completions are shown.
 
 +++
 *** New option 'completions-highlight-face'.
-When this variable is a face name it highlights the current candidate
-in the *Completions* buffer with that face.  When the value is nil no
-highlight is performed at all.
-
+When this variable is a face name, it highlights the current candidate
+in the "*Completions*" buffer with that face.  When the value is nil,
+no highlighting is performed at all.
 
 ** Isearch and Replace
 
@@ -1262,11 +1261,11 @@ property.
 This allows setting a minimum display width for a region of text.
 
 +++
-** New 'cursor-face 'text' property.
-This uses cursor-face instead of the default face when cursor is on or
+** New 'cursor-face' text property.
+This uses 'cursor-face' instead of the default face when cursor is on or
 near the character and 'cursor-face-highlight-mode' is enabled.  The
-variable 'highlight-nonselected-windows' is similar to
-'highlight-nonselected-windows' but for this property.
+variable 'cursor-face-highlight-nonselected-window' is similar to
+'highlight-nonselected-windows', but for this property.
 
 +++
 ** New event type 'touch-end'.
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index 46e7bf2fb0..00d4560865 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -899,8 +899,8 @@ is requested but cannot be done.
 If the value is `lazy', the *Completions* buffer is only displayed after
 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
+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)
@@ -1853,6 +1853,17 @@ Return nil if there is no valid completion, else t."
 This face is only used if the strings used for completions
 doesn't already specify a face.")
 
+(defface completions-highlight
+  '((t :inherit highlight))
+  "Default face for highlighting the current completion candidate."
+  :version "29.1")
+
+(defcustom completions-highlight-face 'completions-highlight
+  "A face name to highlight the current completion candidate.
+If the value is nil, no highlighting is performed."
+  :type '(choice (const nil) face)
+  :version "29.1")
+
 (defcustom completions-format 'horizontal
   "Define the appearance and sorting of completions.
 If the value is `vertical', display completions sorted vertically
@@ -1872,15 +1883,15 @@ completions."
   :type 'boolean
   :version "28.1")
 
-(defcustom completion-header-format
+(defcustom completions-header-format
   (propertize "%s possible completions:\n"
               'face 'shadow
               :help "Please select a completion")
   "Format of completions header.
 It may contain one %s to show the total count of completions.
-When nil no header is shown."
-  :type '(choice (const :tag "No prefix" nil)
-                 (string :tag "Prefix format string"))
+When nil, no header is shown."
+  :type '(choice (const :tag "No header" nil)
+                 (string :tag "Header format string"))
   :version "29.1")
 
 (defun completion--insert-strings (strings &optional group-fun)
@@ -2145,25 +2156,13 @@ candidates."
 
     (with-current-buffer standard-output
       (goto-char (point-max))
-      (when completion-header-format
-        (insert (format completion-header-format (length completions))))
+      (when completions-header-format
+        (insert (format completions-header-format (length completions))))
       (completion--insert-strings completions group-fun)))
 
   (run-hooks 'completion-setup-hook)
   nil)
 
-
-(defface completions-highlight
-  '((t :inherit highlight))
-  "Default face for highlighting the current line in 
`completions-highlight-mode'."
-  :version "29.1")
-
-(defcustom completions-highlight-face 'completions-highlight
-  "A face name to highlight current completion candidate.
-If the value is nil no highlight is performed."
-  :type '(choice (const nil) face)
-  :version "29.1")
-
 (defvar completion-extra-properties nil
   "Property list of extra properties of the current completion job.
 These include:
@@ -2232,12 +2231,12 @@ variables.")
       (completion--message message))))
 
 (defcustom completions-max-height nil
-  "Maximum height for *Completions* buffer."
+  "Maximum height for *Completions* buffer window."
   :type '(choice (const nil) natnum)
   :version "29.1")
 
 (defun completions--fit-window-to-buffer (&optional win &rest _)
-  "Resize completions."
+  "Resize *Completions* buffer window."
   (if temp-buffer-resize-mode
       (let ((temp-buffer-max-height (or completions-max-height
                                         temp-buffer-max-height)))
diff --git a/lisp/simple.el b/lisp/simple.el
index 8eece3e81f..21ea08c0f2 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -6483,7 +6483,7 @@ separate contiguous regions for each line."
   (cdr (region-bounds)))
 
 (defun redisplay--unhighlight-overlay-function (rol)
-  "If ROL is an overlay, call ``delete-overlay''."
+  "If ROL is an overlay, call `delete-overlay'."
   (when (overlayp rol) (delete-overlay rol)))
 
 (defvar redisplay-unhighlight-region-function
@@ -9399,7 +9399,7 @@ Called from `temp-buffer-show-hook'."
         (setq tab-width completion-tab-width))
       ;; Maybe enable cursor completions-highlight.
       (when completions-highlight-face
-        ;; keep highlight even if not selected
+        ;; Keep highlighting even if not selected.
         (setq-local cursor-face-highlight-nonselected-window t)
         (cursor-face-highlight-mode 1))
       ;; Maybe insert help string.