master 6fc54786c3: ; Fix documentation of completion options

[Eli Zaretskii]

branch: master
commit 6fc54786c3bb797068675d7eb7b500fb990bd04a
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Fix documentation of completion options
    
    * doc/emacs/mini.texi (Completion Commands, Completion Options):
    Improve and clarify the wording.
---
 doc/emacs/mini.texi | 44 +++++++++++++++++++++++---------------------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi
index ad5701670e..4e71793b66 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}
-While in the minibuffer, these keys will navigate through the
-completions displayed in the completions buffer.  When
+While in the minibuffer, these keys 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.
+the default), using these commands also inserts the current completion
+candidate into the minibuffer.  If
+@code{minibuffer-completion-auto-choose} is @code{nil}, you can use
+the @kbd{M-@key{RET}} command to insert the completion candidates into
+the minibuffer.  By default, that exits the minibuffer, but with a
+prefix argument, @kbd{C-u M-@key{RET}} inserts the currently active
+candidate without exiting the minibuffer.
 
 @findex switch-to-completions
 @item M-v
@@ -408,8 +408,9 @@ ways (@pxref{Windows}).
 @itemx mouse-2
 While in the completion list buffer, this chooses the completion at
 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.
+@key{RET}} inserts the completion at point into the minibuffer, but
+doesn't exit the minibuffer---thus, you can change your mind and
+choose another candidate.
 
 @findex next-completion
 @item @key{TAB}
@@ -685,18 +686,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 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.
+horizontally, using as many columns as will fit in the window-width,
+but this can be changed by customizing the @code{completions-format}
+user option.  If its value is @code{vertical}, Emacs will sort the
+completions vertically instead, and if it's @code{one-column}, Emacs
+will use just one column.
 
 @vindex completions-sort
-  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.
+  The @code{completions-sort} user option controls the order in which
+the completions are sorted in the @samp{*Completions*} buffer.  The
+default is @code{alphabetical}, which sorts in alphabetical order.
+The value @code{nil} disables sorting.  The value 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