From: Juri Linkov <juri@linkov.net>
Date: Sun, 8 May 2022 18:01:34 +0000 (+0300)
Subject: Minor documentation improvements for completions commands and options
X-Git-Tag: emacs-29.0.90~1910^2~894
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=21ef29d4b1ea85c4b94232f028b3aa29a4a1a81b;p=emacs.git

Minor documentation improvements for completions commands and options

* doc/emacs/mini.texi (Completion Commands): Mention prefix argument
of choose-completion.
(Completion Options): Improve documentation of completions-format
and completions-sort.
---

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index a899fea7e39..ad5701670eb 100644
--- a/doc/emacs/mini.texi
+++ b/doc/emacs/mini.texi
@@ -381,16 +381,16 @@ used with the completion list:
 @vindex minibuffer-completion-auto-choose
 @item M-@key{DOWN}
 @itemx M-@key{UP}
-These keys will navigate through the completions displayed in the
-completions buffer.  When @code{minibuffer-completion-auto-choose} is
-non-@code{nil} (which is the default), using these commands will
-automatically insert the current completion candidate in the
-minibuffer.  If this user option is @code{nil}, the keys will navigate
-the same way as before, but won't automatically insert the candidate
-in the minibuffer.  Instead you have to use the @kbd{M-@key{RET}} command to
-do that.  With a prefix argument, @kbd{C-u M-@key{RET}} inserts the
-currently active candidate to the minibuffer, but doesn't exit the
-minibuffer.
+While in the minibuffer, these keys will navigate through the
+completions displayed in the completions buffer.  When
+@code{minibuffer-completion-auto-choose} is non-@code{nil} (which is
+the default), using these commands will automatically insert the
+current completion candidate in the minibuffer.  If this user option
+is @code{nil}, the keys will navigate the same way as before, but
+won't automatically insert the candidate in the minibuffer.  Instead
+you have to use the @kbd{M-@key{RET}} command to do that.  With
+a prefix argument, @kbd{C-u M-@key{RET}} inserts the currently active
+candidate to the minibuffer, but doesn't exit the minibuffer.
 
 @findex switch-to-completions
 @item M-v
@@ -407,7 +407,9 @@ ways (@pxref{Windows}).
 @itemx mouse-1
 @itemx mouse-2
 While in the completion list buffer, this chooses the completion at
-point (@code{choose-completion}).
+point (@code{choose-completion}).  With a prefix argument, @kbd{C-u
+@key{RET}} inserts the completion at point to the minibuffer, but
+doesn't exit the minibuffer.
 
 @findex next-completion
 @item @key{TAB}
@@ -682,17 +684,19 @@ behavior only when there are @var{n} or fewer alternatives.
 
 @vindex completions-format
   When displaying completions, Emacs will normally pop up a new buffer
-to display the completions.  The completions will (by default) be
-sorted in columns horizontally in alphabetical order, but this can be
-changed by changing the @code{completions-format} user option.  If
-@code{vertical}, sort the completions vertically in columns instead,
-and if @code{one-column}, just use a single column.
+to display the completions.  The completions will by default be sorted
+in rows horizontally, but this can be changed by customizing the
+@code{completions-format} user option.  If @code{vertical}, sort the
+completions vertically in columns instead, and if @code{one-column},
+just use a single column.
 
 @vindex completions-sort
-  This user option controls how completions are sorted in the
-@samp{*Completions*} buffer.  The default is @code{alphabetical}, but
-it can also be a function which will be called with the list of
-completions, and should return the list in the desired order.
+  The @code{completions-sort} user option controls how completions are
+sorted in the @samp{*Completions*} buffer.  The default is
+@code{alphabetical} that sorts in alphabetical order.  The value
+@code{nil} disables sorting.  It can also be a function which will be
+called with the list of completions, and should return the list in the
+desired order.
 
 @vindex completions-max-height
   When @code{completions-max-height} is non-@code{nil}, it limits the
diff --git a/etc/NEWS b/etc/NEWS
index 234aa819be1..dbdc161a416 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -892,7 +892,7 @@ When this user option names a face, the current
 candidate in the "*Completions*" buffer is highlighted with that face.
 The nil value disables this highlighting.
 
----
++++
 *** Choosing a completion with a prefix argument doesn't exit the minibuffer.
 This means that typing 'C-u RET' on a completion candidate in the
 "*Completions*" buffer inserts the completion to the minibuffer,