(Text from Minibuffer, Minibuffer Completion, High-Level Completion):

Document a list of default value strings in the DEFAULT argument,
for which minibuffer functions return the first element.

2 files changed, 33 insertions, 19 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index e0d9db962f9..164f8e27023 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2007-10-22  Juri Linkov  <juri@jurta.org>
+
+        * minibuf.texi (Text from Minibuffer, Minibuffer Completion)
+        (High-Level Completion): Document a list of default value strings
+        in the DEFAULT argument, for which minibuffer functions return the
+        first element.
+
 2007-10-17  Juri Linkov  <juri@jurta.org>
 
         * text.texi (Filling): Update arguments of fill-paragraph.
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 8252b42ca94..6561460d1f9 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -129,8 +129,8 @@ reads the text and returns the resulting Lisp object, unevaluated.
 (@xref{Input Functions}, for information about reading.)
 
 The argument @var{default} specifies a default value to make available
-through the history commands.  It should be a string, or @code{nil}.
-If non-@code{nil}, the user can access it using
+through the history commands.  It should be a string, a list of strings,
+or @code{nil}.  If non-@code{nil}, the user can access its values using
 @code{next-history-element}, usually bound in the minibuffer to
 @kbd{M-n}.  If @var{read} is non-@code{nil}, then @var{default} is
 also used as the input to @code{read}, if the user enters empty input.
@@ -176,8 +176,9 @@ The keymap used is @code{minibuffer-local-map}.
 The optional argument @var{default} is used as in
 @code{read-from-minibuffer}, except that, if non-@code{nil}, it also
 specifies a default value to return if the user enters null input.  As
-in @code{read-from-minibuffer} it should be a string, or @code{nil},
-which is equivalent to an empty string.
+in @code{read-from-minibuffer} it should be a string, a list of strings,
+or @code{nil}, which is equivalent to an empty string.  When @var{default}
+is a list of strings, it returns the first element of this list.
 
 This function is a simplified interface to the
 @code{read-from-minibuffer} function:
@@ -190,7 +191,7 @@ This function is a simplified interface to the
        (read-from-minibuffer @var{prompt} @var{initial} nil nil
                              @var{history} @var{default} @var{inherit})))
   (if (and (equal value "") @var{default})
-      @var{default}
+      (if (consp @var{default}) (car @var{default}) @var{default})
     value))
 @end group
 @end smallexample
@@ -840,9 +841,10 @@ input already in the buffer matches an element of @var{collection}.
 
 However, empty input is always permitted, regardless of the value of
 @var{require-match}; in that case, @code{completing-read} returns
-@var{default}, or @code{""}, if @var{default} is @code{nil}.  The
-value of @var{default} (if non-@code{nil}) is also available to the
-user through the history commands.
+the first element of @var{default}, if it is a list, @code{""},
+if @var{default} is @code{nil}, or @var{default}.  The value of
+@var{default} (if non-@code{nil}) is also available to the user
+through the history commands.
 
 The function @code{completing-read} uses
 @code{minibuffer-local-completion-map} as the keymap if
@@ -1073,8 +1075,10 @@ specification.  @xref{Defining Commands}.
 This function reads the name of a buffer and returns it as a string.
 The argument @var{default} is the default name to use, the value to
 return if the user exits with an empty minibuffer.  If non-@code{nil},
-it should be a string or a buffer.  It is mentioned in the prompt, but
-is not inserted in the minibuffer as initial input.
+it should be a string, a list of strings, or a buffer.  If it is
+a list, the default value is the first element of this list.  It is
+mentioned in the prompt, but is not inserted in the minibuffer as
+initial input.
 
 The argument @var{prompt} should be a string ending with a colon and a
 space.  If @var{default} is non-@code{nil}, the function inserts it in
@@ -1130,11 +1134,12 @@ which @code{commandp} returns @code{t}, and a command name is a symbol
 for which @code{commandp} returns @code{t}.  @xref{Interactive Call}.
 
 The argument @var{default} specifies what to return if the user enters
-null input.  It can be a symbol or a string; if it is a string,
-@code{read-command} interns it before returning it.  If @var{default} is
-@code{nil}, that means no default has been specified; then if the user
-enters null input, the return value is @code{(intern "")}, that is, a
-symbol whose name is an empty string.
+null input.  It can be a symbol, a string or a list of strings.  If it
+is a string, @code{read-command} interns it before returning it.
+If it is a list, @code{read-command} returns the first element of this list.
+If @var{default} is @code{nil}, that means no default has been
+specified; then if the user enters null input, the return value is
+@code{(intern "")}, that is, a symbol whose name is an empty string.
 
 @example
 (read-command "Command name? ")
@@ -1177,10 +1182,12 @@ This function reads the name of a user variable and returns it as a
 symbol.
 
 The argument @var{default} specifies what to return if the user enters
-null input.  It can be a symbol or a string; if it is a string,
-@code{read-variable} interns it before returning it.  If @var{default}
-is @code{nil}, that means no default has been specified; then if the
-user enters null input, the return value is @code{(intern "")}.
+null input.  It can be a symbol, a string or a list of strings.  If it
+is a string, @code{read-variable} interns it before returning it.
+If it is a list, @code{read-variable} returns the first element of
+this list.  If @var{default} is @code{nil}, that means no default has
+been specified; then if the user enters null input, the return value
+is @code{(intern "")}.
 
 @example
 @group