comparison lispref/minibuf.texi @ 65758:028c8f536edb

(High-Level Completion): Explain that the prompt given to `read-buffer' should end with a colon and a space. Update usage examples.

65757:ee26002f84d8

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.

If @var{existing} is non-@code{nil}, then the name specified must be
that of an existing buffer.  The usual commands to exit the minibuffer
do not exit if the text is not valid, and @key{RET} does completion to
attempt to find a valid name.  If @var{existing} is neither @code{nil}
nor @code{t}, confirmation is required after completion.  (However,

then types @key{RET}.  The argument @var{existing} is @code{t}, and the
only buffer name starting with the given input is
@samp{minibuffer.texi}, so that name is the value.

@example
(read-buffer "Buffer name? " "foo" t)
@group
;; @r{After evaluation of the preceding expression,}
;;   @r{the following prompt appears,}
;;   @r{with an empty minibuffer:}
@end group

@group
---------- Buffer: Minibuffer ----------
Buffer name? (default foo) @point{}
---------- Buffer: Minibuffer ----------
@end group

@group
;; @r{The user types @kbd{minibuffer.t @key{RET}}.}

65758:028c8f536edb

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.

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
@var{prompt} before the colon to follow the convention for reading from
the minibuffer with a default value (@pxref{Programming Tips}).

If @var{existing} is non-@code{nil}, then the name specified must be
that of an existing buffer.  The usual commands to exit the minibuffer
do not exit if the text is not valid, and @key{RET} does completion to
attempt to find a valid name.  If @var{existing} is neither @code{nil}
nor @code{t}, confirmation is required after completion.  (However,

then types @key{RET}.  The argument @var{existing} is @code{t}, and the
only buffer name starting with the given input is
@samp{minibuffer.texi}, so that name is the value.

@example
(read-buffer "Buffer name: " "foo" t)
@group
;; @r{After evaluation of the preceding expression,}
;;   @r{the following prompt appears,}
;;   @r{with an empty minibuffer:}
@end group

@group
---------- Buffer: Minibuffer ----------
Buffer name (default foo): @point{}
---------- Buffer: Minibuffer ----------
@end group

@group
;; @r{The user types @kbd{minibuffer.t @key{RET}}.}